![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to make.texinfo CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Early binutils] / binutils|
Return to make.texinfo CVS log | Up to [Early binutils] / binutils |
1.1 root 1: \input texinfo @c -*- Texinfo -*-
2: @setfilename make.info
3: @synindex vr fn
4:
5: @c $Header: make.texinfo,v 2.9 88/07/10 17:52:55 mcgrath Rel $
6:
7: @ifinfo
8: This file documents the GNU Make utility.
9:
10: Copyright (C) 1988 Free Software Foundation, Inc.
11:
12: Permission is granted to make and distribute verbatim copies of
13: this manual provided the copyright notice and this permission notice
14: are preserved on all copies.
15:
16: @ignore
17: Permission is granted to process this file through TeX and print the
18: results, provided the printed document carries copying permission
19: notice identical to this one except for the removal of this paragraph
20: (this paragraph not being relevant to the printed manual).
21:
22: @end ignore
23: Permission is granted to copy and distribute modified versions of this
24: manual under the conditions for verbatim copying, provided also that
25: the section entitled ``Copying Conditions'' is included exactly as in
26: the original, and provided that the entire resulting derived work is
27: distributed under the terms of a permission notice identical to this
28: one.
29:
30: Permission is granted to copy and distribute translations of this
31: manual into another language, under the above conditions for modified
32: versions, except that the text of the translations of the section
33: entitled ``Copying Conditions'' must be approved for accuracy by the
34: Foundation.
35: @end ifinfo
36: @c
37: @setchapternewpage odd
38: @settitle Make
39:
40: @titlepage
41: @sp 6
42: @center @titlefont{GNU Make}
43: @sp 1
44: @center A Program for Directing Recompilation
45: @sp 2
46: @center April 1988
47: @sp 5
48: @center Richard M. Stallman, Roland McGrath
49: @page
50: @vskip 0pt plus 1filll
51: Copyright @copyright{} 1988 Free Software Foundation, Inc.
52:
53: Permission is granted to make and distribute verbatim copies of
54: this manual provided the copyright notice and this permission notice
55: are preserved on all copies.
56:
57: Permission is granted to copy and distribute modified versions of this
58: manual under the conditions for verbatim copying, provided also that
59: the section entitled ``Copying Conditions'' is included exactly as in
60: the original, and provided that the entire resulting derived work is
61: distributed under the terms of a permission notice identical to this
62: one.
63:
64: Permission is granted to copy and distribute translations of this
65: manual into another language, under the above conditions for modified
66: versions, except that the text of the translation of the section
67: entitled ``Copying Conditions'' must be approved for accuracy by the
68: Foundation.
69: @end titlepage
70: @page
71:
72: @node Copying, Bugs, Top, Top
73: @unnumbered Copying Conditions
74: @center (Clarified 11 Feb 1988)
75:
76: The license agreements of most software companies keep you at the mercy of
77: those companies. By contrast, our general public license is intended to
78: give everyone the right to share GNU Make. To make sure that you get the
79: rights we want you to have, we need to make restrictions that forbid anyone
80: to deny you these rights or to ask you to surrender the rights. Hence this
81: license agreement.
82:
83: Specifically, we want to make sure that you have the right to give away
84: copies of GNU Make, that you receive source code or else can get it if you
85: want it, that you can change GNU Make or use pieces of it in new free
86: programs, and that you know you can do these things.
87:
88: To make sure that everyone has such rights, we have to forbid you to
89: deprive anyone else of these rights. For example, if you distribute copies
90: of GNU Make, you must give the recipients all the rights that you have.
91: You must make sure that they, too, receive or can get the source code. And
92: you must tell them their rights.
93:
94: Also, for our own protection, we must make certain that everyone finds out
95: that there is no warranty for GNU Make. If GNU Make is modified by someone
96: else and passed on, we want its recipients to know that what they have is
97: not what we distributed, so that any problems introduced by others will not
98: reflect on our reputation.
99:
100: Therefore we (Richard Stallman and the Free Software Foundation,
101: Inc.) make the following terms which say what you must do to be
102: allowed to distribute or change GNU Make.
103:
104: @unnumberedsec Copying Policies
105:
106: @enumerate
107: @item
108: You may copy and distribute verbatim copies of GNU Make source code as
109: you receive it, in any medium, provided that you conspicuously and
110: appropriately publish on each copy a valid copyright notice
111: ``Copyright @copyright{} 1988 Free Software Foundation, Inc.'' (or
112: with whatever year is appropriate), and include following the
113: copyright notice a verbatim copy of the above disclaimer of warranty
114: and of this License. You may charge a distribution fee for the
115: physical act of transferring a copy.
116:
117: @item
118: You may modify your copy or copies of GNU Make or any portion of it,
119: and copy and distribute such modifications under the terms of
120: Paragraph 1 above, provided that you also do the following:
121:
122: @itemize @bullet
123: @item
124: cause the modified files to carry prominent notices stating
125: that you changed the files and the date of any change; and
126:
127: @item
128: cause the whole of any work that you distribute or publish, that
129: in whole or in part contains or is a derivative of Bison or any
130: part thereof, to be licensed at no charge to all third parties on
131: terms identical to those contained in this License Agreement
132: (except that you may choose to grant more extensive warranty
133: protection to some or all third parties, at your option).
134:
135: @item
136: You may charge a distribution fee for the physical act of
137: transferring a copy, and you may at your option offer warranty
138: protection in exchange for a fee.
139: @end itemize
140:
141: Mere aggregation of another unrelated program with this program (or its
142: derivative) on a volume of a storage or distribution medium does not bring
143: the other program under the scope of these terms.
144:
145: @item
146: You may copy and distribute GNU Make (or a portion or derivative of it,
147: under Paragraph 2) in object code or executable form under the terms
148: of Paragraphs 1 and 2 above provided that you also do one of the
149: following:
150:
151: @itemize @bullet
152: @item
153: accompany it with the complete corresponding machine-readable
154: source code, which must be distributed under the terms of
155: Paragraphs 1 and 2 above; or,
156:
157: @item
158: accompany it with a written offer, valid for at least three
159: years, to give any third party free (except for a nominal
160: shipping charge) a complete machine-readable copy of the
161: corresponding source code, to be distributed under the terms of
162: Paragraphs 1 and 2 above; or,
163:
164: @item
165: accompany it with the information you received as to where the
166: corresponding source code may be obtained. (This alternative is
167: allowed only for noncommercial distribution and only if you
168: received the program in object code or executable form alone.)
169: @end itemize
170:
171: For an executable file, complete source code means all the source code
172: for all modules it contains; but, as a special exception, it need not
173: include source code for modules which are standard libraries that
174: accompany the operating system on which the executable file runs.
175:
176: @item
177: You may not copy, sublicense, distribute or transfer GNU Make except as
178: expressly provided under this License Agreement. Any attempt
179: otherwise to copy, sublicense, distribute or transfer GNU Make is void
180: and your rights to use the program under this License agreement shall
181: be automatically terminated. However, parties who have received
182: computer software programs from you with this License Agreement will
183: not have their licenses terminated so long as such parties remain in
184: full compliance.
185:
186: @item
187: If you wish to incorporate parts of GNU Make into other free programs
188: whose distribution conditions are different, write to the Free Software
189: Foundation at 675 Mass Ave, Cambridge, MA 02139. We have not yet worked
190: out a simple rule that can be stated here, but we will often permit this.
191: We will be guided by the two goals of preserving the free status of all
192: derivatives of our free software and of promoting the sharing and reuse of
193: software.
194: @end enumerate
195:
196: Your comments and suggestions about our licensing policies and our
197: software are welcome! Please contact the Free Software Foundation, Inc.,
198: 675 Mass Ave, Cambridge, MA 02139, or call (617) 876-3296.
199:
200: @unnumberedsec NO WARRANTY
201:
202: BECAUSE GNU MAKE IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY NO
203: WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT
204: WHEN OTHERWISE STATED IN WRITING, THE FREE SOFTWARE FOUNDATION, INC,
205: RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU MAKE "AS IS" WITHOUT
206: WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
207: LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
208: A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
209: PERFORMANCE OF GNU MAKE IS WITH YOU. SHOULD GNU MAKE PROVE DEFECTIVE, YOU
210: ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
211:
212: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL RICHARD M.
213: STALLMAN, THE FREE SOFTWARE FOUNDATION, INC., AND/OR ANY OTHER PARTY
214: WHO MAY MODIFY AND REDISTRIBUTE GNU MAKE AS PERMITTED ABOVE, BE LIABLE TO
215: YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
216: SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
217: INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
218: BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
219: FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS) GNU MAKE, EVEN
220: IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR
221: ANY CLAIM BY ANY OTHER PARTY.
222:
223: @node Top, Copying,, (DIR)
224: @chapter Overview of @code{make}
225:
226: The purpose of the @code{make} utility is to determine automatically which
227: pieces of a large program need to be recompiled, and issue the commands to
228: recompile them. This manual describes the GNU implementation of
229: @code{make}, which was implemented by Richard Stallman and Roland McGrath.
230:
231: Our examples show C programs, since they are most common, but you can use
232: @code{make} with any programming language whose compiler can be run with a
233: shell command. In fact, @code{make} is not limited to programs. You can
234: use it to describe any task where some files must be updated automatically
235: from others whenever the others change.
236:
237: To prepare to use @code{make}, you must write a file called
238: the @dfn{makefile} that describes the relationships among files
239: in your program, and the states the commands for updating each file.
240: In a program, typically the executable file is updated from object
241: files, which are in turn made by compiling source files.@refill
242:
243: Once a suitable makefile exists, each time you change some source files,
244: this simple shell command:
245:
246: @example
247: make
248: @end example
249:
250: @noindent
251: suffices to perform all necessary recompilations. The @code{make} program
252: uses the makefile data base and the last-modification times of the files to
253: decide which of the files need to be updated. For each of those files, it
254: issues the commands recorded in the data base.
255:
256: @iftex
257: Command arguments to @code{make} can be used to control which files should
258: be recompiled, or how. @xref{Running}.
259: @end iftex
260:
261: @menu
262: * Copying:: Copying conditions for GNU Make.
263: * Bugs:: If you have problems, or think you've found a bug.
264: * Simple:: A simple example explained.
265: * Makefiles:: The data base contains rules and variable definitions.
266: * Rules:: A rule says how and when to remake one file.
267: * Commands:: A rule contains shell commands that say how to remake.
268: * Variables:: A variable holds a text string for substitution into rules.
269: * Conditionals::Makefiles that do one thing or another depending on
270: variable values.
271: * Functions:: Functions can do text-processing within @code{make}.
272:
273: * Running:: How to run @code{make}; how you can adjust the way
274: @code{make} uses the makefile.
275:
276: * Implicit:: Implicit rules take over if the makefile doesn't say
277: how a file is to be remade.
278: * Archives:: How to use @code{make} to update archive files.
279:
280: * Features:: GNU @code{make}'s advanced features and how GNU @code{make}
281: relates to other versions of @code{make}.
282: * Missing:: Features of other @code{make}s not supported
283: by GNU @code{make}.
284:
285: * Concept Index::Index of cross-references to where concepts are discussed.
286: * Name Index:: Index of cross-references for names of @code{make}'s
287: variables, functions, special targets and directives.
288: @end menu
289:
290: @node Bugs, Simple, Copying, Top
291: @section Problems and Bugs
292:
293: If you have problems with GNU @code{make} or think you've found a bug,
294: please report it to Roland McGrath; he doesn't promise to do anything
295: but he might well want to fix it.
296:
297: Before reporting a bug, make sure you've actually found a real bug.
298: Carefully reread the documentation and see if it really says you can do
299: what you're trying to do. If it's not clear whether you should be able
300: to do something or not, report that too; it's a bug in the documentation!
301:
302: Before reporting a bug or trying to fix it yourself, try to isolate it to
303: the smallest possible makefile that reproduces the problem. Then send
304: us the makefile and the exact results @code{make} gave you. Also say what
305: you expected to occur; this will help us decide whether the problem
306: was really in the documentation.
307:
308: Once you've got a precise problem, send email to (Internet)
309: @samp{bug-gnu-utils@@prep.ai.mit.edu} or (UUCP)
310: @samp{mit-eddie!prep.ai.mit.edu!bug-gnu-utils}. Please include the version
311: number of @code{make} you are using. You can get this information with the
312: command @samp{make -v -f /dev/null}.@refill
313:
314: Non-bug suggestions are always welcome as well.
315: If you have questions about things that are unclear in the documentation
316: or are just obscure features, ask Roland McGrath; he'll be happy to help
317: you out (but no promises). You can send him electronic mail at Internet
318: address @samp{roland@@wheaties.ai.mit.edu} or UUCP path
319: @samp{mit-eddie!wheaties.ai.mit.edu!roland}.
320:
321: @node Simple, Makefiles, Bugs, Top
322: @section Simple Example of @code{make}
323:
324: Suppose we have a text editor consisting of eight C source files and three
325: header files. We need a makefile to tell @code{make} how to compile and
326: link the editor. Assume that all the C files include @file{defs.h}, but
327: only those defining editing commands include @file{commands.h} and only low
328: level files that change the editor buffer include @file{buffer.h}.
329:
330: To recompile the editor, each changed C source file must be recompiled. If
331: a header file has changed, to be safe each C source file that
332: includes the header file must be recompiled. Each compilation produces an
333: object file corresponding to the source file. Finally, if any source file
334: has been recompiled, all the object files, whether newly made or saved from
335: previous compilations, must be linked together to produce the new
336: executable editor.
337:
338: Here is a straightforward makefile that describes these criteria and says
339: how to compile and link when the time comes:
340:
341: @example
342: edit : main.o kbd.o commands.o display.o \
343: insert.o search.o files.o utils.o
344: cc -o edit main.o kbd.o commands.o display.o \
345: insert.o search.o files.o utils.o
346:
347: main.o : main.c defs.h
348: cc -c main.c
349: kbd.o : kbd.c defs.h command.h
350: cc -c kbd.c
351: commands.o : command.c defs.h command.h
352: cc -c commands.c
353: display.o : display.c defs.h buffer.h
354: cc -c display.c
355: insert.o : insert.c defs.h buffer.h
356: cc -c insert.c
357: search.o : search.c defs.h buffer.h
358: cc -c search.c
359: files.o : files.c defs.h buffer.h command.h
360: cc -c files.c
361: utils.o : utils.c defs.h
362: cc -c utils.c
363: @end example
364:
365: We split each long line into two lines using a backslash-newline; this is
366: like using one long line, but is easier to read.
367:
368: Each file that is generated by a program---that is to say, each file except
369: for source files---is the @dfn{target} of a @dfn{rule} (@pxref{Rules}).
370: (In this example, these are the object files such as @file{main.o},
371: @file{kbd.o}, etc., and the executable file @file{edit}.) The target
372: appears at the beginning of a line, followed by a colon.
373:
374: After the colon come the target's @dfn{dependencies}: all the files that
375: are used as input when the target file is updated. A target file needs to
376: be recompiled or relinked if any of its dependencies changes. In addition,
377: any dependencies that are themselves automatically generated should be
378: updated first. In this example, @file{edit} depends on each of the eight
379: object files; the object file @file{main.o} depends on the source file
380: @file{main.c} and on the header file @file{defs.h}.
381:
382: By default, @code{make} starts with the first rule (not counting rules
383: whose target names start with @samp{.}). This is called the @dfn{default
384: goal}. Therefore, we put the rule for the executable program @file{edit}
385: first. The other rules are processed because their targets appear as
386: dependencies of the goal.
387:
388: After each line containing a target and dependencies come one or more lines
389: of shell commands that say how to update the target file. These lines
390: start with a tab to tell @code{make} that they are command lines. But
391: @code{make} does not know anything about how the commands work. It is up
392: to you to supply commands that will update the target file properly.
393: All @code{make} does is execute the commands you have specified when the
394: target file needs to be updated.
395:
396: @subsection How @code{make} Processes This Makefile
397:
398: After reading the makefile, @code{make} begins its real work by processing
399: the first rule, the one for relinking @file{edit}; but before it can fully
400: process this rule, it must process the rules for the files @file{edit}
401: depends on: all the object files. Each of these files is processed
402: according to its own rule. These rules say to update the @samp{.o} file by
403: compiling its source file. The recompilation must be done if the source
404: file, or any of the header files named as dependencies, is more recent than
405: the object file, or if the object file does not exist.
406:
407: Before recompiling an object file, @code{make} considers updating its
408: dependencies, the source file and header files. This makefile does not
409: specify anything to be done for them---the @samp{.c} and @samp{.h} files
410: are not the targets of any rules---so nothing needs to be done. But
411: automatically generated C programs, such as made by Yacc (or Bison), would
412: be updated by their own rules at this time.
413:
414: After recompiling whichever object files need it, @code{make} can now
415: decide whether to relink @file{edit}. This must be done if the file
416: @file{edit} does not exist, or if any of the object files are newer than
417: it. If an object file was just recompiled, it is now newer than
418: @file{edit}, so @file{edit} will be relinked.
419:
420: @subsection Variables Make Makefiles Simpler
421:
422: In our example, we had to list all the object files twice in the rule for
423: @file{edit} (repeated here):
424:
425: @example
426: edit : main.o kbd.o commands.o display.o \
427: insert.o search.o files.o utils.o
428: cc -o edit main.o kbd.o commands.o display.o \
429: insert.o search.o files.o utils.o
430: @end example
431:
432: @vindex objects
433: Such duplication is error-prone; if a new object file is added to the
434: system, we might add it to one list and forget the other. We can eliminate
435: the risk and simplify the makefile by using a @dfn{variable}. Variables
436: allow a text string to be defined once and substituted in multiple places
437: later (@pxref{Variables}).
438:
439: It's standard practice for every makefile to have a variable named
440: @code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj} or
441: @code{OBJ} which is a list of all object file names. We would define
442: such a variable @code{objects} with a line like this in the makefile:@refill
443:
444: @example
445: objects = main.o kbd.o commands.o display.o \
446: insert.o search.o files.o utils.o
447: @end example
448:
449: @noindent
450: Then, each place we want to put a list of the object file names, we can
451: substitute the variable's value by writing @samp{$(objects)}
452: (@pxref{Variables}). Here is how the rule for @code{edit} looks as a
453: result:
454:
455: @example
456: edit : $(objects)
457: cc -o edit $(objects)
458: @end example
459:
460: @subsection Letting @code{make} Deduce the Commands
461:
462: It is not necessary to spell out the commands for compiling the individual
463: C source files, because @code{make} can figure them out: it has an
464: @dfn{implicit rule} for updating a @samp{.o} file from a correspondingly
465: named @samp{.c} file using a @samp{cc -c} command. For example, it will
466: use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into
467: @file{main.o}. We can therefore omit the commands from the rules for the
468: object files. @xref{Implicit}.@refill
469:
470: When a @samp{.c} file is used automatically in this way, it is also
471: automatically added to the list of dependencies. We can therefore omit
472: the @samp{.c} files from the dependencies, provided we omit the commands.
473:
474: Here is the entire example, with both of these changes, and a variable
475: @code{objects} as suggested above:
476:
477: @example
478: objects = main.o kbd.o commands.o display.o \
479: insert.o search.o files.o utils.o
480:
481: edit : $(objects)
482: cc -o edit $(objects)
483:
484: main.o : defs.h
485: kbd.o : defs.h command.h
486: commands.o : defs.h command.h
487: display.o : defs.h buffer.h
488: insert.o : defs.h buffer.h
489: search.o : defs.h buffer.h
490: files.o : defs.h buffer.h command.h
491: utils.o : defs.h
492: @end example
493:
494: @noindent
495: This is how we would write the makefile in actual practice.
496:
497: @subsection Another Style of Makefile
498:
499: Since the rules for the object files specify only dependencies, no
500: commands, one can alternatively combine them by dependency instead of by
501: target. Here is what it looks like:
502:
503: @example
504: objects = main.o kbd.o commands.o display.o \
505: insert.o search.o files.o utils.o
506:
507: edit : $(objects)
508: cc -o edit $(objects)
509:
510: $(objects) : defs.h
511: kbd.o commands.o files.o : command.h
512: display.o insert.o search.o files.o : buffer.h
513: @end example
514:
515: @noindent
516: Here @file{defs.h} is given as a dependency of all the object files;
517: @file{commands.h} and @file{buffer.h} are dependencies of the specific
518: object files listed for them.
519:
520: Whether this is better is a matter of taste: it is more compact, but some
521: people dislike it because they find it clearer to put all the information
522: about each target in one place.
523:
524: @node Makefiles, Rules, Simple, Top
525: @chapter Writing Makefiles
526:
527: @cindex makefile
528: The information that tells @code{make} how to recompile a system comes from
529: reading a data base called the @dfn{makefile}.
530:
531: @menu
532: * Contents: Makefile Contents. Overview of what you put in a makefile.
533: * Names: Makefile Names. Where @code{make} finds the makefile.
534: * MAKEFILES Variable:: The environment can specify extra makefiles.
535: * Include:: How one makefile can use another makefile.
536: @end menu
537:
538: @node Makefile Contents, Makefile Names, Makefiles, Makefiles
539: @section What Makefiles Contain
540:
541: Makefiles contain four kinds of things: @dfn{rules}, @dfn{variable
542: definitions}, @dfn{directives} and @dfn{comments}. Rules, variables and
543: directives are described at length in later chapters.@refill
544:
545: @itemize @bullet
546: @item
547: A rule says when and how to remake one or more files, called the rule's
548: @dfn{targets}. It lists the other files that the targets @dfn{depend on},
549: and may also give commands to use to create or update the targets.
550: @xref{Rules}.
551:
552: @item
553: A variable definition is a line that specifies a text string value for
554: a @dfn{variable} that can be substituted into the text later. The
555: simple makefile example (@pxref{Simple}) shows a variable definition
556: for @code{objects} as a list of all object files. @xref{Variables},
557: for full details.
558:
559: @item
560: A directive is a command for @code{make} to do something special while
561: reading the makefile. These include:
562:
563: @itemize @bullet
564: @item
565: Reading another makefile (@pxref{Include}).
566:
567: @item
568: Deciding (based on the values of variables) whether to use or
569: ignore a part of the makefile (@pxref{Conditionals}).
570:
571: @item
572: Defining a variable from a verbatim string containing multiple lines
573: (@pxref{Defining}).
574: @end itemize
575:
576: @item
577: @cindex comments
578: @samp{#} in a line of a makefile starts a comment. It and the rest of
579: the line are ignored. Comments may appear on any of the lines in the
580: makefile, except within a @code{define} directive, and perhaps within
581: commands (where the shell decides what is a comment). A line
582: containing just a comment (with perhaps spaces before it) is
583: effectively blank, and is ignored.
584: @end itemize
585:
586: @node Makefile Names, MAKEFILES Variable, Makefile Contents, Makefiles
587: @section What Name to Give Your Makefile
588:
589: By default, when @code{make} looks for the makefile, it tries the names
590: @file{./makefile} and @file{./Makefile} in that order. So normally you call
591: your makefile by one of these two names, and @code{make} finds it
592: automatically. We recommend @file{Makefile} because it appears prominently
593: near the beginning of a directory listing (right near other important
594: files such as @file{README}).@refill
595:
596: If @code{make} finds neither of these two names, it does not use any
597: makefile. Then you must specify a goal with a command argument, and
598: @code{make} will attempt to figure out how to remake it using only its
599: built-in implicit rules. @xref{Implicit}.
600:
601: If you want to use a nonstandard name for your makefile, you can specify
602: the makefile name with the @samp{-f} option. The arguments @samp{-f
603: @var{name}} tell @code{make} to read the file @var{name} as the makefile.
604: If you use more than one @samp{-f} option, you can specify several
605: makefiles. All the makefiles are effectively concatenated in the order
606: specified. The default makefile names @file{./makefile} and
607: @file{./Makefile} are not used if you specify @samp{-f}.@refill
608:
609: @node MAKEFILES Variable, Include, Makefile Names, Makefiles
610: @section The Variable @code{MAKEFILES}
611:
612: @vindex MAKEFILES
613: If the environment variable @code{MAKEFILES} is defined, @code{make}
614: considers its value as a list of names (separated by whitespace) of
615: additional makefiles to be read before the others. This works much like
616: the @code{include} directive: various directories are searched for those
617: files and the default goal is never taken from them. @xref{Include}. In
618: addition, it is not an error if the files listed in @code{MAKEFILES} are
619: not found.@refill
620:
621: The main use of @code{MAKEFILES} is in communication between recursive
622: invocations of @code{make} (@pxref{Recursion}). It usually isn't
623: desirable to set the environment variable before a top-level invocation
624: of @code{make}, because it is usually better not to mess with a makefile
625: from outside. However, if you are running @code{make} without a specific
626: makefile, a makefile in @code{MAKEFILES} can do useful things to help the
627: built-in implicit rules work better, such as defining search paths.
628:
629: Some users are tempted to set @code{MAKEFILES} in the environment
630: automatically on login, and program makefiles to expect this to be done.
631: This is a very bad idea, because such makefiles will fail to work if run by
632: anyone else. It is much better to write explicit @code{include} directives
633: in the makefiles.
634:
635: @node Include,, MAKEFILES Variable, Makefiles
636: @section Including Other Makefiles
637:
638: @findex include
639: The @code{include} directive tells @code{make} to suspend reading the
640: current makefile and read another makefile before continuing. The
641: directive is a line in the makefile that looks like this:
642:
643: @example
644: include @var{filename}
645: @end example
646:
647: Extra spaces are allowed and ignored at the beginning of the line, but a
648: tab is not allowed. (If the line begins with a tab, it will be considered
649: a command line.) Whitespace is required between @code{include} and
650: @var{filename}; extra whitespace is ignored there and at the end of the
651: directive. A comment starting with @samp{#} is allowed at the end of the
652: line.
653:
654: Reading of the containing makefile is temporarily suspended while the file
655: @var{filename} is read as a makefile. When that is finished, @code{make}
656: goes on with reading the makefile in which the directive appears.
657:
658: The default goal target is never taken from an included makefile
659: (@pxref{Goals}).
660:
661: One occasion for using @code{include} directives is when several programs,
662: handled by individual makefiles in various directories, need to use a
663: common set of variable definitions (@pxref{Setting}) or pattern rules
664: (@pxref{Pattern Rules}).
665:
666: Another such occasion is when you want to automatically generate
667: dependencies from source files; the dependencies can be put in a file that
668: is included by the main makefile. This practice is generally cleaner than
669: that of somehow appending the dependencies to the end of the main makefile
670: as has been traditionally done with other versions of @code{make}.
671:
672: If the specified name does not start with a slash, and the file is not
673: found in the current directory, several other directories are searched.
674: First, any directories you have specified with the @samp{-I} option are
675: searched (@pxref{Options}). Then the following directories (if they
676: exist) are searched, in this order: @file{/usr/gnu/include},
677: @file{/usr/local/include}, @file{/usr/include}.
678: If an included makefile cannot be found in any of these directories, a
679: warning message is generated, but it is not a fatal error.@refill
680:
681: @node Rules, Commands, Makefiles, Top
682: @chapter Writing Rules
683:
684: @cindex rule
685: @cindex target
686: @cindex dependency
687: A @dfn{rule} appears in the makefile and says when and how to remake
688: certain files, called the rule's @dfn{targets} (usually only one per rule).
689: It lists the other files that are the @dfn{dependencies} of the target, and
690: @dfn{commands} to use to create or update the target.
691:
692: The order of rules is not significant, except for determining the
693: @dfn{default goal}: the target for @code{make} to consider, if you do not
694: otherwise specify one. The default goal comes from the first rule (not
695: counting included makefiles) whose target does not start with a period.
696: Therefore, the first rule is normally one for compiling the entire program
697: or all the programs described by the makefile. @xref{Goals}.
698:
699: @menu
700: * Rule Example:: An explained example of a rule.
701: * Rule Syntax:: General syntax of rules, with explanation.
702:
703: * Wildcards:: Using wildcard characters like `*' in file names.
704: * Directory Search:: Searching other directories for source files.
705:
706: * Phony Targets:: Using a target that isn't a real file's name.
707: * Special Targets:: Targets with special built-in meanings.
708: * Empty Targets:: Real files that are empty--only the date matters.
709: * Multiple Targets:: When it is useful to have several targets in a rule.
710: * Static Pattern:: Static pattern rules apply to multiple targets
711: and can vary the dependencies according to the
712: target name.
713: * Multiple Rules:: Using several rules with the same target.
714: * Double-Colon:: Special kind of rule allowing
715: several independent rules for one target.
716: * Commands:: Special features and details of how commands
717: in a rule are executed.
718: @end menu
719:
720: @ifinfo
721: @node Rule Example, Rule Syntax, Rules, Rules
722: @isubsection Rule Example
723:
724: Here is an example of a rule:
725:
726: @example
727: foo.o : foo.c defs.h # module for twiddling the frobs
728: cc -c -g foo.c
729: @end example
730:
731: Its target is @file{foo.o} and its dependencies are @file{foo.c} and
732: @file{defs.h}. It has one command, which is @samp{cc -c -g foo.c}.
733: The command line starts with a tab to identify it as a command.
734:
735: This rule says two things:
736:
737: @itemize @bullet
738: @item
739: How to decide whether @file{foo.o} is out of date: it is out of date
740: if it does not exist, or if either @file{foo.c} or @file{defs.h} is
741: more recent than it.
742:
743: @item
744: How to update the file @file{foo.o}: by running @code{cc} as stated.
745: The command does not explicitly mention @file{defs.h}, but we presume
746: that @file{foo.c} includes it, and that that is why @file{defs.h} was
747: added to the dependencies.
748: @end itemize
749: @end ifinfo
750:
751: @node Rule Syntax, Wildcards, Rule Example, Rules
752: @section Rule Syntax
753:
754: In general, a rule looks like this:
755:
756: @example
757: @var{targets} : @var{dependencies}
758: @var{command}
759: @var{command}
760: ...
761: @end example
762:
763: @noindent
764: or like this:
765:
766: @example
767: @var{targets} : @var{dependencies} ; @var{command}
768: @var{command}
769: @var{command}
770: ...
771: @end example
772:
773: The @var{targets} are file names, separated by spaces. Wild card
774: characters may be used (@pxref{Wildcards}) and a name of the form
775: @file{@var{a}(@var{m})} represents member @var{m} in archive file @var{a}
776: (@pxref{Archive Members}). Usually there is only one target per rule, but
777: occasionally there is a reason to have more (@pxref{Multiple Targets}).
778:
779: The @var{command} lines start with a tab character. The first command may
780: appear on the line after the dependencies, with a tab character, or may
781: appear on the same line, with a semicolon. Either way, the effect is the
782: same. @xref{Commands}.
783:
784: Because dollar signs are used to start variable references, if you really
785: want a dollar sign in the rule you must write two of them (@samp{$$}).
786: @xref{Variables}. A long line may be split by inserting a backslash
787: followed by a newline, but this is not required, as there is no limit on
788: the length of a line.
789:
790: A rule tells @code{make} two things: when the targets are out of date,
791: and how to update them when necessary.
792:
793: The criterion for being out of date is specified in terms of the
794: @var{dependencies}, which consist of file names separated by spaces.
795: (Wildcards and archive members are allowed here too.) A target is out of
796: date if it does not exist or if it is older than any of the dependencies
797: (by comparison of last-modification times). The idea is that the contents
798: of the target file are computed based on information in the dependencies,
799: so if any of the dependencies changes, the contents of the existing target
800: file are no longer necessarily valid.
801:
802: How to update is specified by @var{commands}. These are lines to be
803: executed by the shell (normally @samp{sh}), but with some extra features
804: (@pxref{Commands}).
805:
806: @node Wildcards, Directory Search, Rule Syntax, Rules
807: @section Using Wildcards Characters in File Names
808: @cindex wildcard
809: @cindex file name
810:
811: A single file name can specify many files using @dfn{wildcard characters}.
812: The wildcard characters in @code{make} are @samp{*}, @samp{?} and
813: @samp{[@dots{}]}, the same as in the Bourne shell. For example, @file{*.c}
814: specifies a list of all the files (in the working directory) whose names
815: end in @samp{.c}.@refill
816:
817: Wildcard expansion happens automatically in targets, in dependencies, and
818: in commands. In other contexts, wildcard expansion happens only if you
819: request it explicitly with the @code{wildcard} function.
820:
821: The special significance of a wildcard character can be turned off by
822: preceding it with a backslash. Thus, @file{foo\*bar} would refer to a
823: specific file whose name consists of @samp{foo}, an asterisk, and
824: @samp{bar}.@refill
825:
826: @menu
827: * Examples: Wildcard Examples. Some simple examples.
828: * Pitfall: Wildcard Pitfall. @code{*.o} won't do what you want!
829: * Function: Wildcard Function.
830: How to do wildcard expansion when defining a variable
831: using the function @code{wildcard}.
832: @end menu
833:
834: @node Wildcard Examples, Wildcard Function, Wildcards, Wildcards
835: @subsection Wildcard Examples
836:
837: Wildcards can be used in the commands of a rule. For example, here is a
838: rule to delete all the object files:
839:
840: @example
841: clean:
842: rm -f *.o
843: @end example
844:
845: Wildcards are also useful in the dependencies of a rule. With the
846: following rule in the makefile, @samp{make print} will print all the
847: @samp{.c} files that have changed since the last time you printed them:
848:
849: @example
850: print: *.c
851: lpr -p $?
852: touch print
853: @end example
854:
855: @noindent
856: This rule uses @file{print} as an empty target file; @pxref{Empty Targets}.
857:
858: Wildcard expansion does not happen when you define a variable. Thus, if
859: you write this:
860:
861: @example
862: objects=*.o
863: @end example
864:
865: @noindent
866: then the value of the variable @code{objects} is the actual string
867: @samp{*.o}. However, if you use the value of @code{objects} in a target,
868: dependency or command, wildcard expansion will take place at that time.
869:
870: @node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards
871: @subsection Pitfalls of Using Wildcards
872:
873: Now here is an example of a naive way of using wildcard expansion, that
874: does not do what you would intend. Suppose you would like to say that the
875: executable file @file{foo} is made from all the object files in the
876: directory, and you write this:
877:
878: @example
879: objects=*.o
880:
881: foo : $(objects)
882: cc -o foo $(CFLAGS) $(objects)
883: @end example
884:
885: @noindent
886: The value of @code{objects} is the actual string @samp{*.o}. Wildcard
887: expansion happens in the rule for @file{foo}, so that each @emph{existing}
888: @samp{.o} file becomes a dependency of @file{foo} and will be recompiled if
889: necessary.
890:
891: But what if you delete all the @samp{.o} files? Then @samp{*.o} will
892: expand into @emph{nothing}. The target @file{foo} will have no
893: dependencies and would be remade by linking no object files. This is not
894: what you want!
895:
896: Actually you can use wildcard expansion for this purpose, but you need more
897: sophisticated techniques, including the @code{wildcard} function and string
898: substitution.
899: @ifinfo
900: @xref{Wildcard Function}.
901: @end ifinfo
902: @iftex
903: These are described in the following section.
904: @end iftex
905:
906: @node Wildcard Function,, Wildcard Pitfall, Wildcards
907: @subsection The Function @code{wildcard}
908: @findex wildcard
909:
910: Wildcard expansion happens automatically in rules. But wildcard expansion
911: does not normally take place when a variable is set, or inside the
912: arguments of a function. If you want to do wildcard expansion in such
913: places, you need to use the @code{wildcard} function, like this:
914:
915: @example
916: $(wildcard @var{pattern})
917: @end example
918:
919: This string, used anywhere in a makefile, is replaced by a space-separated
920: list of names of existing files that match the pattern @var{pattern}.
921:
922: One use of the @code{wildcard} function is to get a list of all the C source
923: files in a directory, like this:
924:
925: @example
926: $(wildcard *.c)
927: @end example
928:
929: We can change the list of C source files into a list of object files by
930: substituting @samp{.o} for @samp{.c} in the result, like this:
931:
932: @example
933: $(subst .c,.o,$(wildcard *.c))
934: @end example
935:
936: Here we have used another function, @code{subst} (@pxref{Text Functions}).
937:
938: Thus, a makefile to compile all C source files in the directory and then
939: link them together could be written as follows:
940:
941: @example
942: objects:=$(subst .c,.o,$(wildcard *.c))
943:
944: foo : $(objects)
945: cc -o foo $(LDFLAGS) $(objects)
946: @end example
947:
948: @noindent
949: (This takes advantage of the implicit rule for compiling C programs, so
950: there is no need to write explicit rules for compiling the files.)
951:
952: @node Directory Search, Phony Targets, Wildcards, Rules
953: @section Searching Directories for Dependencies
954: @vindex VPATH
955: @findex vpath
956: @cindex vpath
957: @cindex search path for dependencies
958: @cindex directory search
959:
960: For large systems, it is often desirable to put sources in a separate
961: directory from the binaries. The @dfn{directory search} features of
962: @code{make} facilitate this by searching several directories automatically
963: to find a dependency. When you redistribute the files among directories,
964: you do not need to change the individual rules, just the search paths.
965:
966: @menu
967: * General Search:: The @code{VPATH} variable specifies a search path
968: that applies to every dependency.
969: * Selective Search:: The @code{vpath} directive specifies a search path
970: for a specified class of names.
971: * Commands/Search:: How to write shell commands that work together
972: with search paths.
973: * Implicit/Search:: How search paths affect implicit rules.
974: * Libraries/Search:: Directory search for link libraries.
975: @end menu
976:
977: @node General Search, Selective Search, Directory Search, Directory Search
978: @subsection @code{VPATH}: Search Path for All Dependencies
979:
980: The value of the variable @code{VPATH} is a list of directories which
981: @code{make} should search (in the order specified) for dependency files.
982: The directory names are separated by colons. For example:
983:
984: @example
985: VPATH = src:../headers
986: @end example
987:
988: @noindent
989: specifies a path containing two directories, @file{src} and @file{../headers}.
990:
991: Whenever a file listed as a dependency does not exist in the current
992: directory, the directories listed in @code{VPATH} are searched for a file
993: with that name. If a file is found in one of them, that file becomes the
994: dependency. Rules may then specify the names of source files as if they
995: all existed in the current directory.
996:
997: Using the value of @code{VPATH} set in the previous example, a rule like this:
998:
999: @example
1000: foo.o : foo.c
1001: @end example
1002:
1003: @noindent
1004: is interpreted as if it were written like this:
1005:
1006: @example
1007: foo.o : src/foo.c
1008: @end example
1009:
1010: @noindent
1011: assuming the file @file{foo.c} does not exist in the current directory but
1012: is found in the directory @file{src}.
1013:
1014: @node Selective Search, Commands/Search, General Search, Directory Search
1015: @subsection The @code{vpath} Directive
1016:
1017: Similar to the @code{VPATH} variable but more selective is the @code{vpath}
1018: directive, which allows you to specify a search path for a particular class
1019: of filenames, those that match a particular pattern. Thus you can supply
1020: certain search directories for one class of filenames and other directories
1021: (or none) for other filenames.
1022:
1023: There are three forms of the @code{vpath} directive:
1024:
1025: @table @code
1026: @item vpath @var{pattern} @var{directories}
1027: Specify the search path @var{directories} for filenames that match
1028: @code{pattern}. If another path was previously specified for the same
1029: pattern, the new path replaces it. Note that it does @emph{not} add
1030: to the old path for this pattern.@refill
1031:
1032: The search path, @var{directories}, is a colon-separated list of
1033: directories to be searched, just like the search path used in the
1034: @code{VPATH} variable.
1035:
1036: @item vpath @var{pattern}
1037: Clear out the search path associated with @var{pattern}.
1038:
1039: @item vpath
1040: Clear all search paths previously specified with @code{vpath} directives.
1041: @end table
1042:
1043: A @code{vpath} pattern is a string containing a @samp{%} character. The
1044: string must match the filename of a dependency that is being searched for,
1045: the @samp{%} character matching any sequence of zero or more characters (as
1046: in pattern rules; @pxref{Pattern Rules}). (It is valid to omit the
1047: @samp{%}, but then the pattern must match the dependency exactly, which may
1048: not be very useful.)
1049:
1050: When a dependency fails to exist in the current directory, if the
1051: @var{pattern} in a @code{vpath} directive matches the name of the
1052: dependency file, then the @var{directories} in that directive are searched
1053: just like (and before) the directories in the @code{VPATH} variable.@refill
1054:
1055: If several @code{vpath} patterns match the dependency file's name, then
1056: @code{make} processes each matching @code{vpath} directive one by one,
1057: searching all the directories mentioned in each directive. The @code{vpath}
1058: directives are processed in the order in which they appear in the makefiles.
1059:
1060: @node Commands/Search, Implicit/Search, Selective Search, Directory Search
1061: @subsection Writing Shell-Commands with Directory Search
1062:
1063: When a dependency is found in another directory through directory search,
1064: this cannot change the commands of the rule; they will execute as written.
1065: Therefore, you must write the commands with care so that they will look for
1066: the dependency in the directory where @code{make} finds it.
1067:
1068: This is done with the @dfn{automatic variables} such as @samp{$^}
1069: (@pxref{Automatic}). For instance, the value of @samp{$^} is a list of all
1070: the dependencies of the rule, including the names of the directories in
1071: which they were found, and the value of @samp{$@@} is the target. Thus:
1072:
1073: @example
1074: foo.o : foo.c
1075: cc -c $(CFLAGS) $^ -o $@@
1076: @end example
1077:
1078: @noindent
1079: The variable @code{CFLAGS} exists so you can specify flags for C
1080: compilation by implicit rule; we use it here for consistency so it will
1081: affect all C compilations uniformly (@pxref{Implicit Variables}).
1082:
1083: Often the dependencies include header files as well, which you don't want
1084: to mention in the commands. The function @code{firstword} can be used to
1085: extract just the first dependency from the entire list, as shown here
1086: (@pxref{Filename Functions}):
1087:
1088: @example
1089: VPATH = src:../headers
1090: foo.o : foo.c defs.h hack.h
1091: cc -c $(CFLAGS) $(firstword $^) -o $@@
1092: @end example
1093:
1094: @noindent
1095: Here the value of @samp{$^} would be something like @samp{src/foo.c
1096: ../headers/defs.h hack.h}, from which @samp{$(firstword $^)} extracts just
1097: @samp{src/foo.c}.@refill
1098:
1099: @node Implicit/Search, Libraries/Search, Commands/Search, Directory Search
1100: @subsection Directory Search and Implicit Rules
1101:
1102: The search through the directories specified in @code{VPATH} or with
1103: @code{vpath} happens also during consideration of implicit rules
1104: (@pxref{Implicit}).
1105:
1106: For example, when a file @file{foo.o} has no explicit rule, @code{make}
1107: considers implicit rules, such as to compile @file{foo.c} if that file
1108: exists. If such a file is lacking in the current directory, the
1109: appropriate directories are searched for it. If @file{foo.c} exists (or is
1110: mentioned in the makefile) in any of the directories, the implicit rule for
1111: C compilation is applicable.
1112:
1113: The commands of all the built-in implicit rules normally use automatic
1114: variables as a matter of necessity; consequently they will use the file
1115: names found by directory search with no extra effort.
1116:
1117: @node Libraries/Search,, Implicit/Search, Directory Search
1118: @subsection Directory Search for Link Libraries
1119:
1120: Directory search applies in a special way to libraries used with the
1121: linker. This special feature comes into play when you write a dependency
1122: whose name is of the form @samp{-l@var{name}}. (You can tell something
1123: funny is going on here because the dependency is normally the name of a
1124: file, and the @emph{file name} of the library looks like
1125: @file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill
1126:
1127: When a dependency's name has the form @samp{-l@var{name}}, @code{make}
1128: handles it specially by searching for the file @samp{lib@var{name}.a} in
1129: the directories @samp{/lib} and @samp{/usr/lib}, and then using matching
1130: @code{vpath} search paths and the @code{VPATH} search path.@refill
1131:
1132: For example,
1133:
1134: @example
1135: foo : foo.c -lcurses
1136: cc $^ -o $@@
1137: @end example
1138:
1139: @noindent
1140: would cause the command @samp{cc foo.c -lcurses -o foo} to be executed when
1141: @file{foo} is older than @file{foo.c} or than @file{libcurses.a} (which has
1142: probably been found by directory search in the file
1143: @file{/usr/lib/libcurses.a}).@refill
1144:
1145: As shown by the example above, the file name found by directory search is
1146: used only for comparing the file time with the target file's time. It
1147: does not replace the file's name in later usage (such as in automatic
1148: variables like @code{$^}); the name remains unchanged, still starting
1149: with @samp{-l}. This leads to the correct results because the linker
1150: will repeat the appropriate search when it processes its arguments.@refill
1151:
1152: @node Phony Targets, Empty Targets, Directory Search, Rules
1153: @section Phony Targets
1154: @cindex phony targets
1155:
1156: A phony target is one that is not really the name of a file.
1157: It is only a name for some commands to be executed when explicitly
1158: requested.
1159:
1160: If you write a rule whose commands will not create the target file, the
1161: commands will be executed every time the target comes up for remaking.
1162: Here is an example:
1163:
1164: @example
1165: clean:
1166: rm *.o temp
1167: @end example
1168:
1169: @noindent
1170: Because the @code{rm} command does not create a file named @file{clean},
1171: probably no such file will ever exist. Therefore, the @code{rm} command
1172: will be executed every time you say @samp{make clean}.
1173:
1174: @findex .PHONY
1175: The phony target will cease to work if anything ever does create a file
1176: named @file{clean} in this directory. Since there are no dependencies, the
1177: @file{clean} would be considered up to date and its commands would not be
1178: executed. To avoid this problem, you can explicitly declare the target to
1179: be phony, using the special target @code{.PHONY} (@pxref{Special Targets})
1180: as follows:
1181:
1182: @example
1183: .PHONY : clean
1184: @end example
1185:
1186: @noindent
1187: Once this is done, @code{make} will run the commands regardless of whether
1188: there is a file named @file{clean}.
1189:
1190: A phony target should not be a dependency of a real target file; strange
1191: things can result from that. As long as you don't do that, the phony
1192: target commands will be executed only when the phony target is a goal
1193: (@pxref{Goals}).
1194:
1195: Phony targets can have dependencies. When one directory contains multiple
1196: programs, it is most convenient to describe all of the programs in one
1197: makefile @file{./Makefile}. Since the target remade by default will be the
1198: first one in the makefile, it is common to make this a phony target named
1199: @samp{all} and give it, as dependencies, all the individual programs. For
1200: example:
1201:
1202: @example
1203: all : prog1 prog2 prog3
1204: .PHONY : all
1205:
1206: prog1 : prog1.o utils.o
1207: cc -o prog1 prog1.o utils.o
1208:
1209: prog2 : prog2.o
1210: cc -o prog2 prog2.o
1211:
1212: prog3 : prog3.o sort.o utils.o
1213: cc -o prog3 prog3.o sort.o utils.o
1214: @end example
1215:
1216: @noindent
1217: Now you can say just @samp{make} to remake all three programs, or specify
1218: as arguments the ones to remake (as in @samp{make prog1 prog3}).
1219:
1220: When one phony target is a dependency of another, it serves as a subroutine
1221: of the other. For example, here @samp{make cleanall} will delete the
1222: object files, the difference files, and the file @file{program}:
1223:
1224: @example
1225: cleanall : cleanobj cleandiff
1226: rm program
1227:
1228: cleanobj :
1229: rm *.o
1230:
1231: cleandiff :
1232: rm *.diff
1233: @end example
1234:
1235: @node Empty Targets, Special Targets, Phony Targets, Rules
1236: @section Empty Target Files to Record Events
1237: @cindex empty targets
1238:
1239: The @dfn{empty target} is a variant of the phony target; it is used to hold
1240: commands for an action that you request explicitly from time to time.
1241: Unlike a phony target, this target file can really exist; but the file's
1242: contents do not matter, and usually are empty.
1243:
1244: The purpose of the empty target file is to record, with its
1245: last-modification-time, when the rule's commands were last executed. It
1246: does so because one of the commands is a @code{touch} command to update the
1247: target file.
1248:
1249: The empty target file must have some dependencies. When you ask to remake
1250: the empty target, the commands are executed if any dependency is more
1251: recent than the target; in other words, if a dependency has changed since
1252: the last time you remade the target. Here is an example:
1253:
1254: @example
1255: print: foo.c bar.c
1256: lpr -p $?
1257: touch print
1258: @end example
1259:
1260: @noindent
1261: With this rule, @samp{make print} will execute the @code{lpr} command if
1262: either source file has changed since the last @samp{make print}. The
1263: automatic variable @samp{$?} is used to print only those files that have
1264: changed (@pxref{Automatic}).
1265:
1266: @node Special Targets, Multiple Targets, Empty Targets, Rules
1267: @section Special Built-in Target Names
1268: @cindex special targets
1269:
1270: Certain names have special meanings if they appear as targets.
1271:
1272: @table @code
1273: @item .PHONY
1274: The dependencies of the special target @code{.PHONY} are considered to
1275: be phony targets. When it is time to consider such a target,
1276: @code{make} will run its commands unconditionally, regardless of
1277: whether a file with that name exists or what its last-modification
1278: time is. @xref{Phony Targets}.
1279:
1280: @item .SUFFIXES
1281: The dependencies of the special target @code{.SUFFIXES} are the list
1282: of suffixes to be used in checking for suffix rules (@pxref{Suffix
1283: Rules}).
1284:
1285: @item .DEFAULT
1286: The commands specified for @code{.DEFAULT} are used for any target for
1287: which no other commands are known (either explicitly or through an
1288: implicit rule). If @code{.DEFAULT} commands are specified, every
1289: nonexistent file mentioned as a dependency will have these commands
1290: executed on its behalf. @xref{Search Algorithm}.
1291:
1292: @item .PRECIOUS
1293: @cindex precious targets
1294: The targets which @code{.PRECIOUS} depends on are given this special
1295: treatment: if @code{make} is killed or interrupted during the
1296: execution of their commands, the target is not deleted.
1297: @xref{Interrupts}.
1298:
1299: @item .IGNORE
1300: Simply by being mentioned as a target, @code{.IGNORE} says to ignore
1301: errors in execution of commands. The dependencies and commands for
1302: @code{.IGNORE} are not meaningful.
1303:
1304: @samp{.IGNORE} exists for historical compatibility. Since
1305: @code{.IGNORE} affects every command in the makefile, it is not very
1306: useful; we recommend you use the more selective ways to ignore errors
1307: in specific commands (@pxref{Errors}).
1308:
1309: @item .SILENT
1310: Simply by being mentioned as a target, @code{.SILENT} says not to
1311: print commands before executing them. The dependencies and commands
1312: for @code{.SILENT} are not meaningful.
1313:
1314: @samp{.SILENT} exists for historical compatibility. We recommend you
1315: use the more selective ways to silence specific commands
1316: (@pxref{Echoing}).
1317: @end table
1318:
1319: An entire class of special targets have names made of the concatenation of
1320: two implicit rule suffixes (two members of the list of dependencies of
1321: @code{.SUFFIXES}). Such special targets are suffix rules, an obsolete way
1322: of defining implicit rules (but a way still widely used). In principle,
1323: any target name could be special in this way if you break it in two and add
1324: both pieces to the suffix list. In practice, suffixes normally begin with
1325: @samp{.}, so these special target names also begin with @samp{.}.
1326: @xref{Suffix Rules}.
1327:
1328: @node Multiple Targets, Multiple Rules, Special Targets, Rules
1329: @section Multiple Targets in a Rule
1330:
1331: A rule with multiple targets is equivalent to writing many rules, each with
1332: one target, and all identical aside from that. The same commands apply to
1333: all the targets, but their effects may vary because you can substitute the
1334: actual target name into the command using @samp{$@@}. The rule contributes
1335: the same dependencies to all the targets also.
1336:
1337: This is useful in two cases.
1338:
1339: @itemize @bullet
1340: @item
1341: You want just dependencies, no commands. For example:
1342:
1343: @example
1344: kbd.o commands.o files.o: command.h
1345: @end example
1346:
1347: @noindent
1348: gives an additional dependency to each of the three object files
1349: mentioned.
1350:
1351: @item
1352: Similar commands work for all the targets. The commands do not need
1353: to be absolutely identical, since the automatic variable @samp{$@@}
1354: can be used to substitute the particular target to be remade into the
1355: commands (@pxref{Automatic}). For example:
1356:
1357: @group
1358: @example
1359: bigoutput littleoutput : text.g
1360: generate text.g -$(subst output,,$@@) > $@@
1361: @end example
1362: @end group
1363:
1364: @noindent
1365: is equivalent to
1366:
1367: @example
1368: bigoutput : text.g
1369: generate text.g -big > bigoutput
1370: littleoutput : text.g
1371: generate text.g -little > littleoutput
1372: @end example
1373:
1374: @noindent
1375: Here we assume the hypothetical program @code{generate} makes two
1376: types of output, one if given @samp{-big} and one if given
1377: @samp{-little}.@refill
1378: @end itemize
1379:
1380: @ifinfo
1381: Suppose you would like to vary the dependencies according to the target,
1382: much as the variable @samp{$@@} allows you to vary the commands.
1383: You cannot do this with multiple targets in an ordinary rule, but you can
1384: do it with a @dfn{static pattern rule}. @xref{Static Pattern}.
1385: @end ifinfo
1386:
1387: @node Static Pattern, Multiple Rules, Multiple Targets, Rules
1388: @section Static Pattern Rules
1389: @cindex static pattern rules
1390: @cindex varying dependencies
1391:
1392: @dfn{Static pattern rules} are rules which specify multiple targets and
1393: construct the dependency names for each target based on the target name.
1394: They are more general than ordinary rules with multiple targets because the
1395: targets don't have to have identical dependencies. Their dependencies must
1396: be @emph{analogous}, but not necessarily @emph{identical}.
1397:
1398: @menu
1399: * Usage: Static Usage. How to use static pattern rules.
1400: * Static vs Implicit:: When are they better than implicit rules?
1401: @end menu
1402:
1403: @node Static Usage, Static vs Implicit, Static Pattern, Static Pattern
1404: @subsection Syntax of Static Pattern Rules
1405:
1406: Here is the syntax of a static pattern rule:
1407:
1408: @example
1409: @var{targets}: @var{target-pattern}: @var{dep-patterns} @dots{}
1410: @var{commands}
1411: @dots{}
1412: @end example
1413:
1414: @noindent
1415: The @var{targets} gives the list of targets that the rule applies to. The
1416: targets can contain wildcard characters, just like the targets of ordinary
1417: rules (@pxref{Wildcards}).
1418:
1419: The @var{target-pattern} and @var{dep-patterns} say how to compute the
1420: dependencies of each target. Each target is matched against the
1421: @var{target-pattern} to extract a part of the target name, called the
1422: @dfn{stem}. This stem is substituted into each of the @var{dep-patterns}
1423: to make the dependency names (one from each @var{dep-pattern}).
1424:
1425: Each pattern normally contains the character @samp{%} just once. When the
1426: @var{target-pattern} matches a target, the @samp{%} can match any part of
1427: the target name; this part is called the @dfn{stem}. The rest of the
1428: pattern must match exactly. For example, the target @file{foo.o} matches
1429: the pattern @samp{%.o}, with @samp{foo} as the stem. The targets
1430: @file{foo.c} and @file{foo.out} don't match that pattern.@refill
1431:
1432: The dependency names for each target are made by substituting the stem for
1433: the @samp{%} in each dependency pattern. For example, if one dependency
1434: pattern is @file{%.c}, then substitution of the stem @samp{foo} gives the
1435: dependency name @file{foo.c}. It is fine to write a dependency pattern that
1436: doesn't contain @samp{%}; then this dependency is the same for all targets.
1437:
1438: Here is an example, which compiles each of @file{foo.o} and @file{bar.o}
1439: from the corresponding @file{.c} file:
1440:
1441: @example
1442: objects := foo.o bar.o
1443:
1444: $(objects): %.o: %.c
1445: $(CC) -c $(CFLAGS) $< -o $@@
1446: @end example
1447:
1448: Each target specified must match the target pattern; a warning is issued
1449: for each that does not. If you have a list of files, only some of which
1450: will match the pattern, you can use the @code{filter} function to remove
1451: nonmatching filenames (@pxref{Text Functions}):
1452:
1453: @example
1454: files := foo.elc bar.o
1455:
1456: $(filter %.o,$(files)): %.o: %.c
1457: $(CC) -c $(CFLAGS) $< -o $@@
1458: $(filter %.elc,$(files)): %.elc: %.el
1459: emacs -f batch-byte-compile $<
1460: @end example
1461:
1462: @noindent
1463: Here the result of @samp{$(filter %.o,$(files))} is just @file{bar.o}, and
1464: the first static pattern rule causes it to be made from @file{bar.c}. The
1465: result of @samp{$(filter %.elc,$(files))} is @file{foo.elc}, which is
1466: made from @file{foo.el}.@refill
1467:
1468: @node Static vs Implicit,, Static Usage, Static Pattern
1469: @subsection Static Pattern Rules versus Implicit Rules
1470:
1471: A static pattern rule has much in common with an implicit rule defined as a
1472: pattern rule (@pxref{Pattern Rules}). Both have a pattern for the target
1473: and patterns for constructing the names of dependencies. The difference is
1474: in how @code{make} decides @emph{when} the rule applies.
1475:
1476: An implicit rule @emph{can} apply to any target that matches its pattern,
1477: but it @emph{does} apply only when the target has no commands otherwise
1478: specified, and only when the dependencies can be found. If more than one
1479: implicit rule appears applicable, only one applies; the choice depends on
1480: the order of rules.
1481:
1482: By contrast, a static pattern rule applies to the precise list of targets
1483: that you specify in the rule. It cannot apply to any other target and it
1484: invariably does apply to each of the targets specified. If two conflicting
1485: rules apply, and both have commands, that's an error.
1486:
1487: The static pattern rule can be better than an implicit rule for these
1488: reasons:
1489:
1490: @itemize @bullet
1491: @item
1492: You may wish to override the usual implicit rule for a few
1493: files whose names cannot be categorized syntactically but
1494: can be given in an explicit list.
1495:
1496: @item
1497: If you cannot be sure of the precise contents of the directories
1498: you are using, you may not be sure which other irrelevant files
1499: might lead @code{make} to use the wrong implicit rule. The choice
1500: might depend on the order in which the implicit rule search is done.
1501: With static pattern rules, there is no uncertainty: each rule applies
1502: to precisely the targets specified.
1503: @end itemize
1504:
1505: @node Multiple Rules, Double-Colon, Static Pattern, Rules
1506: @section Multiple Rules for One Target
1507:
1508: One file can be the target of several rules if at most one rule has commands.
1509: The other rules can only have dependencies. All the dependencies mentioned
1510: in all the rules are merged into one list of dependencies for the target.
1511: If the target is older than any dependency from any rule, the commands are
1512: executed.
1513:
1514: An extra rule with just dependencies can be used to give a few extra
1515: dependencies to many files at once. For example, one usually has a
1516: variable named @code{objects} containing a list of all the compiler output
1517: files in the system being made. An easy way to say that all of them must
1518: be recompiled if @file{config.h} changes is to write
1519:
1520: @example
1521: objects = foo.o bar.o
1522: foo.o : defs.h
1523: bar.o : defs.h test.h
1524: $(objects) : config.h
1525: @end example
1526:
1527: This could be inserted or taken out without changing the rules that really
1528: say how to make the object files, making it a convenient form to use if
1529: you wish to add the additional dependency intermittently.
1530:
1531: Another wrinkle is that the additional dependencies could be specified with
1532: a variable that you could set with a command argument to @code{make}
1533: (@pxref{Overriding}). For example,
1534:
1535: @example
1536: extradeps=
1537: $(objects) : $(extradeps)
1538: @end example
1539:
1540: @noindent
1541: means that the command @samp{make extradeps=foo.h} will consider
1542: @file{foo.h} as a dependency of each object file, but plain @samp{make}
1543: will not.
1544:
1545: If none of the explicit rules for a target has commands, then @code{make}
1546: searches for an applicable implicit rule to find some commands.
1547: @xref{Implicit}.
1548:
1549: @node Double-Colon,, Multiple Rules, Rules
1550: @section Double-Colon Rules
1551: @cindex double-colon rule
1552:
1553: @dfn{Double-colon} rules are rules written with @samp{::} instead of
1554: @samp{:} after the target names. They are handled differently from
1555: ordinary rules when the same target appears in more than one rule.
1556:
1557: When a target appears in multiple rules, all the rules must be the same
1558: type: all ordinary, or all double-colon. If they are double-colon, each of
1559: them is independent of the others. Each double-colon rule's commands are
1560: executed if the target is older than any dependencies of that rule. This
1561: can result in executing none, any or all of the double-colon rules.
1562:
1563: The double-colon rules for a target are executed in the order they appear
1564: in the makefile. However, the cases where double-colon rules really make
1565: sense are those where the order of executing the commands would not matter.
1566:
1567: Each double-colon rule should specify commands; if it does not, an
1568: implicit rule will be used if one applies. @xref{Implicit}.
1569:
1570: @node Commands, Variables, Rules, Top
1571: @chapter Writing the Commands in Rules
1572: @cindex commands
1573:
1574: The commands of a rule consist of shell command lines to be executed one by
1575: one. Each command line must start with a tab, except that the first
1576: command line may be attached to the target-and-dependencies line with a
1577: semicolon in between. Blank lines and lines of just comments may appear
1578: among the command lines; they are ignored.
1579:
1580: Users use many different shell programs, but commands in makefiles are
1581: always interpreted by @file{/bin/sh} unless the makefile specifies otherwise.
1582:
1583: Whether comments can be written on command lines, and what syntax they use,
1584: is under the control of the shell that is in use. If it is @file{/bin/sh},
1585: a @samp{#} at the start of a word starts a comment.
1586:
1587: @menu
1588: * Echoing:: Normally commands are echoed before execution,
1589: but you can control this in several ways.
1590: * Execution:: How commands are executed.
1591: * Errors:: What happens after an error in command execution.
1592: How to ignore errors in certain commands.
1593: * Interrupts:: If a command is interrupted or killed,
1594: the target may be deleted.
1595: * Recursion:: Invoking @code{make} from commands in makefiles.
1596: * Sequences:: Defining canned sequences of commands.
1597: @end menu
1598:
1599: @node Echoing, Execution, Commands, Commands
1600: @section Command Echoing
1601:
1602: @cindex echoing (of commands)
1603: @cindex silent operation
1604: @cindex @@ (in commands)
1605: @cindex -n
1606: Normally @code{make} prints each command line before it is executed.
1607: We call this @dfn{echoing} because it gives the appearance that you
1608: are typing the commands yourself.
1609:
1610: When a line starts with @samp{@@}, it is normally not echoed. The
1611: @samp{@@} is discarded before the command is passed to the shell.
1612: Typically you would use this for a command whose only effect is to
1613: print something, such as an @code{echo} command.
1614:
1615: When @code{make} is given the flag @samp{-n}, echoing is all that happens,
1616: no execution. @xref{Options}. In this case and only this case, even the
1617: commands starting with @samp{@@} are printed. This flag is useful for
1618: finding out which commands @code{make} thinks are necessary without
1619: actually doing them.
1620:
1621: @cindex -s
1622: @findex .SILENT
1623: The @samp{-s} flag to @code{make} prevents all echoing, as if all commands
1624: started with @samp{@@}. A rule in the makefile for the special target
1625: @code{.SILENT} has the same effect (@pxref{Special Targets}).
1626: @code{.SILENT} is essentially obsolete since @samp{@@} is more general.@refill
1627:
1628: @node Execution, Errors, Echoing, Commands
1629: @section Command Execution
1630: @cindex execution
1631: @cindex shell
1632:
1633: When it is time to execute commands to update a target, they are executed
1634: one at a time by making a new subshell for each line. (In practice,
1635: @code{make} may take shortcuts that do not affect the results.)
1636:
1637: This implies that shell commands such as @code{cd} that set variables local
1638: to each process will not affect the following command lines. If you want
1639: to use @code{cd} to affect the next command, put the two on a single line
1640: with a semicolon between them. Then @code{make} will consider them a
1641: single command and pass them, together, to a shell which will execute them
1642: in sequence. For example:
1643:
1644: @example
1645: foo : bar/lose
1646: cd bar; gobble lose > ../foo
1647: @end example
1648:
1649: If you would like to split a single shell command into multiple lines of
1650: text, you must use a backslash at the end of all but the last subline.
1651: Such a sequence of lines is combined into a single line, by deleting the
1652: backslash-newline sequences, before passing it to the shell. Thus, the
1653: following is equivalent to the preceding example:
1654:
1655: @group
1656: @example
1657: foo : bar/lose
1658: cd bar; \
1659: gobble lose > ../foo
1660: @end example
1661: @end group
1662:
1663: @vindex SHELL
1664: The program used as the shell is taken from the variable @code{SHELL}.
1665: By default, the program @file{/bin/sh} is used.
1666:
1667: Unlike most variables, the variable @code{SHELL} will not be set from the
1668: environment, except in a recursive @code{make}. This is because the
1669: environment variable @code{SHELL} is used to specify your personal choice
1670: of shell program for interactive use. It would be very bad for personal
1671: choices like this to affect the functioning of makefiles.
1672: @xref{Environment}.
1673:
1674: @node Errors, Interrupts, Execution, Commands
1675: @section Errors in Commands
1676:
1677: @cindex error (in commands)
1678: After each shell command returns, @code{make} looks at its exit status.
1679: If the command completed successfully, the next command line is executed in
1680: a new shell, or after the last command line is executed, the rule is finished.
1681:
1682: If there is an error (the exit status is nonzero), @code{make} gives up on
1683: the current rule, and perhaps on all rules.
1684:
1685: Sometimes it does not matter whether a command fails. For example, you
1686: may use the @code{mkdir} command to insure that a directory exists. If
1687: the directory already exists, @code{mkdir} will report an error, but you
1688: probably want @code{make} to continue regardless.
1689:
1690: @cindex - (in commands)
1691: To ignore errors in a command line, write a @samp{-} at the beginning of
1692: the line's text (after the initial tab). The @samp{-} is discarded before
1693: the command is passed to the shell for execution.
1694:
1695: @cindex -i
1696: @findex .IGNORE
1697: When @code{make} is run with the @samp{-i} flag, errors are ignored in
1698: all commands of all rules. A rule in the makefile for the special target
1699: @code{.IGNORE} has the same effect. These ways of ignoring errors are
1700: obsolete because @samp{-} is more general.
1701:
1702: When errors are to be ignored, because of either a @samp{-} or the
1703: @samp{-i} flag, @code{make} treats an error return just like success,
1704: except that it prints out a message telling you the status code the
1705: command exited with and saying that the error has been ignored.
1706:
1707: @cindex -k
1708: When an error happens that @code{make} has not been told to ignore,
1709: it implies that the current target cannot be correctly remade, and neither
1710: can any other that depends on it either directly or indirectly. No further
1711: commands will be executed for these targets, since their preconditions
1712: have not been achieved.
1713:
1714: Normally @code{make} gives up immediately in this circumstance, returning a
1715: nonzero status. However, if the @samp{-k} flag is specified, @code{make}
1716: continues to consider the other dependencies of the pending targets,
1717: remaking them if necessary, before it gives up and returns nonzero status.
1718: For example, after an error in compiling one object file, @samp{make -k}
1719: will continue compiling other object files even though it already knows
1720: that linking them will be impossible. @xref{Options}.
1721:
1722: The usual behavior assumes that your purpose is to get the specified
1723: targets up to date; once @code{make} learns that this is impossible, it
1724: might as well report the failure immediately. The @samp{-k} option says
1725: that the real purpose is to test as much as possible of the changes made in
1726: the program, perhaps to find several independent problems so that you can
1727: correct them all before the next attempt to compile. This is why Emacs's
1728: @code{compile} command passes the @samp{-k} flag by default.
1729:
1730: @node Interrupts, Recursion, Errors, Commands
1731: @section Interrupting or Killing @code{make}
1732: @cindex interrupt
1733: @cindex signal
1734: @cindex deletion of target files
1735:
1736: If @code{make} gets a fatal signal while a command is executing, it may
1737: delete the target file that the command was supposed to update. This is
1738: done if the target file's last-modification time has changed since
1739: @code{make} first checked it.
1740:
1741: The purpose of deleting the target is to make sure that it is remade from
1742: scratch when @code{make} is next run. Otherwise, a partially written file
1743: could appear to be valid, since it is more recent than the dependencies.
1744:
1745: @findex .PRECIOUS
1746: You can prevent the deletion of a target file in this way by making the
1747: special target @code{.PRECIOUS} depend on it. Before remaking a target,
1748: @code{make} checks to see whether it appears on the dependencies of
1749: @code{.PRECIOUS}, and thereby decides whether the target should be deleted
1750: if a signal happens. Some reasons why you might do this are that the
1751: target is updated in some atomic fashion or exists only to record a
1752: modification-time (its contents do not matter) or will cause trouble if it
1753: ever fails to exist.
1754:
1755: @node Recursion, Sequences, Interrupts, Commands
1756: @section Recursive Use of @code{make}
1757: @cindex recursion
1758:
1759: Recursive use of @code{make} means using @code{make} as a command in a
1760: makefile. This technique is useful when you want separate makefiles for
1761: various subsystems that compose a larger system. For example, suppose you
1762: have a subdirectory @file{subdir} which has its own makefile, and you would
1763: like the containing directory's makefile to run @code{make} on the
1764: subdirectory. You can do it by writing this:
1765:
1766: @example
1767: subsystem:
1768: cd subdir; $(MAKE)
1769: @end example
1770:
1771: @noindent
1772: or, equivalently, this (@pxref{Options}):
1773:
1774: @example
1775: subsystem:
1776: $(MAKE) -c subdir
1777: @end example
1778:
1779: You can write recursive @code{make} commands just by copying this example,
1780: but there are many things to know about how they work and why, and about
1781: how the sub-@code{make} relates to the top-level @code{make}.
1782:
1783: @menu
1784: * MAKE Variable:: Special effects of using @samp{$(MAKE)}.
1785: * Variables/Recursion:: How variables are communicated to a sub-@code{make}.
1786: * Options/Recursion:: How options are communicated to a sub-@code{make}.
1787: * -w Option:: The @samp{-w} option facilitates debugging
1788: makefiles with recursive @code{make} commands.
1789: @end menu
1790:
1791: @node MAKE Variable, Variables/Recursion, Recursion, Recursion
1792: @subsection How the @code{MAKE} Variable Works
1793: @vindex MAKE
1794:
1795: Recursive @code{make} commands should always use the variable @code{MAKE},
1796: not the explicit command name @samp{make}, as shown here:
1797:
1798: @example
1799: subsystem:
1800: cd subdir; $(MAKE)
1801: @end example
1802:
1803: The value of this variable is the file name with which @code{make} was
1804: invoked. If this file name was @file{/bin/make}, then the command executed
1805: is @samp{cd subdir; /bin/make}. If you use a special version of
1806: @code{make} to run the top-level makefile, the same special version will be
1807: executed for recursive invocations.
1808:
1809: Also, any arguments that define variable values are added to @code{MAKE},
1810: so the sub-@code{make} gets them too. Thus, if you do @samp{make
1811: CFLAGS=-O}, so that all C compilations will be optimized, the
1812: sub-@code{make} is run with @samp{cd subdir; /bin/make CFLAGS=-O}.@refill
1813:
1814: As a special feature, using the variable @code{MAKE} in the commands of a
1815: rule alters the effects of the @samp{-t}, @samp{-n} or @samp{-q} option.
1816: (@xref{Instead of Execution}.)@refill
1817:
1818: Consider the command @samp{make -t} in the above example. Following the
1819: usual definition of @samp{-t}, this would create a file named
1820: @file{subsystem} and do nothing else. What you really want it to do is run
1821: @samp{cd subdir; make -t}; but that would require executing the command,
1822: and @samp{-t} says not to execute commands.@refill
1823:
1824: The special feature makes this do what you want: whenever a rule's commands
1825: use the variable @code{MAKE}, the flags @samp{-t}, @samp{-n} or @samp{-q}
1826: do not apply to that rule. The commands of that rule are executed normally
1827: despite the presence of a flag that causes most commands not to be run.
1828: The usual @code{MAKEFLAGS} mechanism passes the flags to the
1829: sub-@code{make} (@pxref{Options/Recursion}), so your request to touch the
1830: files, or print the commands, is propagated to the subsystem.@refill
1831:
1832: @node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion
1833: @subsection Communicating Variables to a Sub-@code{make}
1834: @cindex environment and recursion
1835:
1836: Most variable values of the top-level @code{make} are passed to the
1837: sub-@code{make} through the environment. These variables are defined in
1838: the sub-@code{make} as defaults, but do not override what is specified in
1839: the sub-@code{make}'s makefile. (Variables are passed down if their names
1840: consist of letters, numbers and underscores.)
1841:
1842: The way this works is that @code{make} adds each variable and its value to
1843: the environment for running each command. (Variables whose names start
1844: with non-alphanumeric characters are left out.) The sub-@code{make}, in
1845: turn, uses the environment to initialize its table of variable values.
1846: @xref{Environment}.
1847:
1848: @vindex MAKELEVEL
1849: As a special feature, the variable @code{MAKELEVEL} is changed when it is
1850: passed down from level to level. This variable's value is a string which
1851: is the depth of the level as a decimal number. The value is @samp{0} for
1852: the top-level @code{make}; @samp{1} for a sub-@code{make}, @samp{2} for a
1853: sub-sub-@code{make}, and so on. The incrementation happens when
1854: @code{make} sets up the environment for a command.@refill
1855:
1856: The main use of @code{MAKELEVEL} is to test it in a conditional directive
1857: (@pxref{Conditionals}); this way you can write a makefile that behaves one
1858: way if run recursively and another way if run directly by you.
1859:
1860: @vindex MAKEFILES
1861: You can use the variable @code{MAKEFILES} to cause all sub-@code{make}
1862: commands to use additional makefiles. The value of @code{MAKEFILES} is a
1863: whitespace-separated list of filenames. This variable, if defined in the
1864: outer-level makefile, is passed down through the environment as usual; then
1865: it serves as a list of extra makefiles for the sub-@code{make} to read
1866: before the usual or specified ones. @xref{MAKEFILES Variable}.
1867:
1868: @node Options/Recursion, -w Option, Variables/Recursion, Recursion
1869: @subsection Communicating Options to a Sub-@code{make}
1870: @cindex options and recursion
1871:
1872: @vindex MAKEFLAGS
1873: Flags such as @samp{-s} and @samp{-k} are passed automatically to the
1874: sub-@code{make} through the variable @code{MAKEFLAGS}. This variable is
1875: set up automatically by @code{make} to contain the flag letters that
1876: @code{make} received. Thus, if you do @samp{make -ks} then
1877: @code{MAKEFLAGS} gets the value @samp{ks}.@refill
1878:
1879: As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS}
1880: in its environment. In response, it takes the flags from that value and
1881: processes them as if they had been given as arguments. @xref{Options}.
1882:
1883: The options @samp{-c}, @samp{-d}, @samp{-f}, @samp{-I}, @samp{-o}, and
1884: @samp{-p} are not put into @code{MAKEFLAGS}; these options are not passed
1885: down.@refill
1886:
1887: If you don't want to pass the other flags down, you must change the
1888: value of @code{MAKEFLAGS}, like this:
1889:
1890: @example
1891: subsystem:
1892: cd subdir; $(MAKE) MAKEFLAGS=
1893: @end example
1894:
1895: @vindex MFLAGS
1896: A similar variable @code{MFLAGS} exists also, for historical compatibility.
1897: It has the same value as @code{MAKEFLAGS} except that a hyphen is added at
1898: the beginning if it is not empty. @code{MFLAGS} was traditionally used
1899: explicitly in the recursive @code{make} command, like this:
1900:
1901: @example
1902: subsystem:
1903: cd subdir; $(MAKE) $(MFLAGS)
1904: @end example
1905:
1906: @noindent
1907: but now @code{MAKEFLAGS} makes this usage redundant.
1908:
1909: @node -w Option,, Options/Recursion, Recursion
1910: @subsection The @samp{-w} Option
1911:
1912: If you are running @code{make} over a large directory tree, the @samp{-w}
1913: option can make the output a lot easier to understand by showing each
1914: directory as it is entered and exited. For example, if @samp{make -w} is
1915: run in the directory @file{/u/gnu/make}, @code{make} will print a line of
1916: the form:@refill
1917:
1918: @example
1919: make: Entering directory `/u/gnu/make'.
1920: @end example
1921:
1922: @noindent
1923: before doing anything else, and a line of the form:
1924:
1925: @example
1926: make: Leaving directory `/u/gnu/make'.
1927: @end example
1928:
1929: @noindent
1930: when processing is completed.
1931:
1932: @node Sequences,, Recursion, Commands
1933: @section Defining Canned Command Sequences
1934: @cindex sequences of commands
1935:
1936: When the same sequence of commands is useful in making various targets, you
1937: can define it as a canned sequence with the @code{define} directive, and
1938: refer to the canned sequence from the rules for those targets. The canned
1939: sequence is actually a variable, so the name must not conflict with other
1940: variable names.
1941:
1942: Here is an example of defining a canned sequence of commands:
1943:
1944: @example
1945: define run-yacc
1946: yacc $(firstword $^)
1947: mv y.tab.c $@@
1948: endef
1949: @end example
1950:
1951: @noindent
1952: Here @code{run-yacc} is the name of the variable being defined;
1953: @code{endef} marks the end of the definition; the lines in between are the
1954: commands. The @code{define} directive does not expand variable references
1955: and function calls in the canned sequence; the @samp{$} characters,
1956: parentheses, variable names, and so on, all become part of the value of the
1957: variable you are defining. @xref{Defining}, for a complete explanation of
1958: @code{define}.
1959:
1960: The first command in this example runs Yacc on the first dependency (of
1961: whichever rule uses the canned sequence). The output file from Yacc is
1962: always named @file{y.tab.c}. The second command moves the output to the
1963: rule's target file name.
1964:
1965: To use the canned sequence, substitute the variable into the commands of a
1966: rule. You can substitute it like any other variable (@pxref{Reference}).
1967: Because variables defined by @code{define} are recursively expanded
1968: variables, all the variable references you wrote inside the @code{define}
1969: are expanded now. For example:
1970:
1971: @example
1972: foo.c : foo.y
1973: $(run-yacc)
1974: @end example
1975:
1976: @noindent
1977: @samp{foo.y} will substituted for the variable @samp{$^} when it occurs in
1978: @code{run-yacc}'s value, and @samp{foo.c} for @samp{$@@}.@refill
1979:
1980: This is a realistic example, but this particular one is not needed in
1981: practice because @code{make} has an implicit rule to figure out these
1982: commands based on the file names involved. @xref{Implicit}.
1983:
1984: @node Variables, Conditionals, Commands, Top
1985: @chapter How to Use Variables
1986: @cindex variable
1987: @cindex value
1988: @cindex recursive variable expansion
1989: @cindex simple variable expansion
1990:
1991: A @dfn{variable} is a name defined within @code{make} to represent a string
1992: of text, called the variable's @dfn{value}. These values can be
1993: substituted by explicit request into targets, dependencies, commands and
1994: other parts of the makefile.
1995:
1996: Variables can represent lists of file names, options to pass to compilers,
1997: programs to run, directories to look in for source files, directories to
1998: write output in, or anything else you can imagine.
1999:
2000: A variable name may be any sequence characters not containing @samp{:},
2001: @samp{#}, @samp{=}, leading or trailing whitespace. However,
2002: variable names containing characters other than letters, numbers and
2003: underscores should be avoided, as they may be given special meanings in the
2004: future, and they are not passed through the environment to a
2005: sub-@code{make} (@pxref{Variables/Recursion}).
2006:
2007: It is traditional to use upper case letters in variable names, but we
2008: recommend using lower case letters for variable names that serve internal
2009: purposes in the makefile, and reserving upper case for parameters that
2010: control implicit rules or for parameters that the user should override with
2011: command options (@pxref{Overriding}).
2012:
2013: @menu
2014: * Reference:: How to use the value of a variable.
2015: * Values:: All the ways variables get their values.
2016: * Flavors:: Variables come in two flavors.
2017: * Setting:: How to set a variable in the makefile.
2018: * Override Directive:: Setting a variable in the makefile
2019: even if the user has set it with a command argument.
2020: * Defining:: An alternate way to set a variable to a verbatim string.
2021: * Environment:: Variable values can come from the environment.
2022: @end menu
2023:
2024: @node Reference, Values, Variables, Variables
2025: @section Reference to Variables
2026: @cindex reference to variables
2027: @cindex $ (variable reference)
2028:
2029: To substitute a variable's value, write a dollar sign followed by the name
2030: of the variable in parentheses or braces: either @samp{$(foo)} or
2031: @samp{$@{foo@}} is a valid reference to the variable @code{foo}. This
2032: special significance of @samp{$} is why you must write @samp{$$} to have
2033: the effect of a single dollar sign in a file name or command.
2034:
2035: Variable references can be used in any context: targets, dependencies,
2036: commands, most directives, and new variable values. Here is a common kind
2037: of example, where a variable holds the names of all the object files in a
2038: program:
2039:
2040: @example
2041: objects = program.o foo.o utils.o
2042: program : $(objects)
2043: cc -o program $(objects)
2044:
2045: $(objects) : defs.h
2046: @end example
2047:
2048: Variable references work by strict textual substitution. Thus, the rule
2049:
2050: @example
2051: foo = c
2052: prog.o : prog.c
2053: $(foo)$(foo) prog.c
2054: @end example
2055:
2056: @noindent
2057: could be used to compile a C program @file{prog.c}. (Since spaces around
2058: the variable value are ignored in variable assignments, the value of
2059: @code{foo} is precisely @samp{c}.)
2060:
2061: A dollar sign followed by a character other than a dollar sign,
2062: open-parenthesis or open-brace treats that single character as the variable
2063: name. Thus, you could reference the variable @code{x} with @samp{$x}.
2064: However, this practice is strongly discouraged, except with the automatic
2065: variables (@pxref{Automatic}).
2066:
2067:
2068: @subsection Modified References
2069: @cindex modified variable reference
2070: @cindex substitution variable reference
2071:
2072: In addition to simple references, variables can be referenced in a manner
2073: which modifies the value of the reference but do not modify the value of
2074: the variable referenced. Such a reference is a @dfn{substitution reference}.
2075:
2076: A @dfn{substitution reference} is really a simplified form of the
2077: @code{patsubst} expansion function (@pxref{Functions}). It has the form
2078: @samp{$(var:a=b)} (or @samp{$@{var:a=b@}}) and is equivalent to
2079: @samp{$(patsubst %a,%b,$(var))}. This means that it replaces every
2080: @samp{a} at the end of a whitespace-separated word with a @samp{b}.
2081: For example:@refill
2082:
2083: @example
2084: foo := a.o b.o c.o
2085: bar := $(foo:.o=.c)
2086: @end example
2087:
2088: @noindent
2089: sets @samp{bar} to @samp{a.c b.c c.c}. @xref{Setting}.
2090:
2091: @subsection Recursive References
2092: @cindex recursive variable reference
2093: @cindex variable reference, recursive
2094:
2095: Recursive variable references are a complicated concept needed only for
2096: very complex makefile programming. You need not worry about them in
2097: general, except to know that making a variable with a dollar sign in its
2098: name might have strange results. However, if you are the worrisome type or
2099: are actually interested in what they do, read on.
2100:
2101: Variables may be referenced inside a variable reference. This is called
2102: a @dfn{recursive variable reference}. For example,
2103:
2104: @example
2105: x = y
2106: y = z
2107: a := $($(x))
2108: @end example
2109:
2110: @noindent
2111: defines @samp{a} as @samp{z}: the @samp{$(x)} inside @samp{$($(x))} expands
2112: to @samp{y}, so @samp{$($(x))} expands to @samp{$(y)} which in turn expands
2113: to @samp{z}.@refill
2114:
2115: Recursive variable references can get yet more recursive. For example,
2116:
2117: @example
2118: x = $(y)
2119: y = z
2120: z = Hello
2121: a := $($(x))
2122: @end example
2123:
2124: @noindent
2125: defines @samp{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))}
2126: which becomes @samp{$(z)} which becomes @samp{Hello}. This sort of
2127: recursion can go on for as many levels as you like (and can comprehend),
2128: though it's not clear that very many levels of recursion are useful.@refill
2129:
2130: Recursive variable references can also contain modified references and
2131: function invokations (@pxref{Functions}), just like any other reference.
2132: For example, using the @code{subst} function (@pxref{Text Functions}):
2133:
2134: @example
2135: x = variable1
2136: variable2 := Hello
2137: y = $(subst 1,2,$(x))
2138: z = y
2139: a := $($($(z)))
2140: @end example
2141:
2142: @noindent
2143: eventually defines @samp{a} as @samp{Hello}. It is doubtful that anyone
2144: would ever want to write a recursive reference as convoluted as this one,
2145: but it works: @samp{$($($(z)))} expands to @samp{$($(y))} which becomes
2146: @samp{$($(subst 1,2,$(x)))} which changes @samp{variable1} to
2147: @samp{variable2} in @samp{$(x)} and finally expands to @samp{$(variable2)},
2148: a simple variable reference that becomes @samp{Hello}.@refill
2149:
2150: Recursive variable references need not be as simple as @samp{$($(a))}.
2151: They can contain several variable references:
2152:
2153: @example
2154: a_dirs := dira dirb
2155: 1_dirs := dir1 dir2
2156:
2157: a_files := filea fileb
2158: 1_files := file1 file2
2159:
2160: ifeq "$(use_a)" "yes"
2161: a1 := a
2162: else
2163: a1 := 1
2164: endif
2165:
2166: ifeq "$(use_dirs)" "yes"
2167: df := dirs
2168: else
2169: df := files
2170: endif
2171:
2172: dirs := $($(a1)_$(df))
2173: @end example
2174:
2175: @noindent
2176: will give @samp{dirs} the value of @samp{a_dirs}, @samp{1_dirs},
2177: @samp{a_files} or @samp{1_files} depending on the settings of @samp{use_a}
2178: and @samp{use_dirs}.@refill
2179:
2180: Recursive variable references can also be part of a modified reference:
2181:
2182: @example
2183: a_objects := a.o b.o c.o
2184: 1_objects := 1.o 2.o 3.o
2185:
2186: sources := $($(a1)_object:.o=.c)
2187: @end example
2188:
2189: @noindent
2190: defines @samp{sources} as either @samp{a.c b.c c.c} or @samp{1.c 2.c 3.c},
2191: depending on the value of @samp{a1}.
2192:
2193: The only restriction on this sort of use of recursive variable references
2194: is that they cannot specify part of a function invokation. This is because
2195: the search for an initial word matching defined function is done before the
2196: check for a variable name containing a dollar sign. Thus,
2197:
2198: @example
2199: ifdef do_sort
2200: func := sort
2201: else
2202: func := strip
2203: endif
2204:
2205: bar := a d b g q c
2206:
2207: foo := $($(func) $(bar))
2208: @end example
2209:
2210: @noindent
2211: attempts to give @samp{foo} the value of the variable @samp{sort a d b g
2212: q c} or @samp{strip a d b g q c}, rather than giving @samp{a d b g
2213: q c} as the argument to either the @code{sort} or the @code{strip}
2214: function. This is an implementation restriction which may be removed in
2215: the future if the need arises, but this is not likely since there are not
2216: really any two functions you would want to give the same arguments.@refill
2217:
2218: Note that @dfn{recursive variable references} are quite different from
2219: @dfn{recursively expanded variables} (@pxref{Flavors}), though both are
2220: used together in complex ways when doing makefile programming.@refill
2221:
2222: @node Values, Flavors, Reference, Variables
2223: @section How Variables Get Their Values
2224:
2225: Variables can get values in several different ways:
2226:
2227: @itemize @bullet
2228: @item
2229: You can specify an overriding value when you run @code{make}.
2230: @xref{Overriding}.
2231:
2232: @item
2233: You can specify a value in the makefile, either with an assignment
2234: (@pxref{Setting}) or with a verbatim definition (@pxref{Defining}).
2235:
2236: @item
2237: Values are inherited from the environment. @xref{Environment}.
2238:
2239: @item
2240: Several @dfn{automatic} variables are given new values for each rule.
2241: @xref{Automatic}.
2242:
2243: @item
2244: Several variables have constant initial values. @xref{Implicit Variables}.
2245: @end itemize
2246:
2247: @node Flavors, Setting, Values, Variables
2248: @section The Two Flavors of Variables
2249: @cindex flavors (of variables)
2250: @cindex recursive variable expansion
2251:
2252: There are two kinds of variables in GNU @code{make}. They are
2253: distinguished by two things: how they are defined and how they are expanded.
2254:
2255: The first flavor of variable is a @dfn{recursively expanded} variable.
2256: Variables of this sort are defined by lines using @samp{=}
2257: @ifinfo
2258: (@pxref{Setting}).
2259: @end ifinfo
2260: @iftex
2261: (see the next section).
2262: @end iftex
2263: The value you specify is installed verbatim; if it contains references to
2264: other variables, these references are expanded whenever this variable is
2265: substituted (in the course of expanding some other string). When this
2266: happens, it is recursive expansion.
2267:
2268: For example,
2269:
2270: @example
2271: foo = $(bar)
2272: bar = $(ugh)
2273: ugh = Huh?
2274:
2275: all:;echo $(foo)
2276: @end example
2277:
2278: @noindent
2279: will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which
2280: expands to @samp{$(ugh)} which finally expands to @samp{Huh?}.@refill
2281:
2282: This flavor of variable is the only sort supported by other versions of
2283: @code{make}. It has its advantages and its disadvantages. An advantage
2284: (most would say) is that:
2285:
2286: @example
2287: CFLAGS = $(include_dirs) -O
2288: include_dirs = -Ifoo -Ibar
2289: @end example
2290:
2291: @noindent
2292: will do what was intended: when @samp{CFLAGS} is expanded in a command,
2293: it will expand to @samp{-Ifoo -Ibar}. A major disadvantage is that you
2294: can't append something on the end of a variable, as in
2295:
2296: @example
2297: CFLAGS = $(CFLAGS) -O
2298: @end example
2299:
2300: @noindent
2301: because it will cause an infinite loop in the variable expansion.
2302: (Actually @code{make} detects the infinite loop and reports an error.)
2303:
2304: Another disadvantage is that any functions (@pxref{Functions}) referenced
2305: in the definition will be executed every time the variable is expanded.
2306: This makes @code{make} run slower; worse, it causes the @code{wildcard}
2307: function to give unpredictable results.
2308:
2309: To avoid all the problems and inconveniences of recursively expanded
2310: variables, there is another flavor: @dfn{simply expanded} variables.
2311: Simply expanded variables are defined by lines using @samp{:=}
2312: @ifinfo
2313: (@pxref{Setting}).
2314: @end ifinfo
2315: @iftex
2316: (see the next section).
2317: @end iftex
2318: The value of a simply expanded variable is scanned once and for all,
2319: expanding any references to other variables and functions, when the
2320: variable is defined. The actual value of the simply expanded variable is
2321: the result of expanding the value you write. It does not contain any
2322: references to other variables; it contains their values @emph{as of the
2323: time this variable was defined}. Therefore,
2324:
2325: @example
2326: x := foo
2327: y := $(x) bar
2328: x := later
2329: @end example
2330:
2331: @noindent
2332: is equivalent to
2333:
2334: @example
2335: y := foo bar
2336: x := later
2337: @end example
2338:
2339: When a simply expanded variable is referenced, its value is substituted
2340: verbatim.
2341:
2342: Simply expanded variables generally make complicated makefile programming
2343: more predictable because they work like variables in most programming
2344: languages. They allow you to redefine a variable using its own value (or
2345: its value processed in some way by one of the expansion functions) and to
2346: use the expansion functions much more efficiently (@pxref{Functions}).
2347:
2348: You can also use them to introduce controlled leading or trailing spaces
2349: into variable values. Such spaces are discarded from your input before
2350: substitution of variable references and function calls; this means you can
2351: include leading or trailing spaces in a variable value by protecting them
2352: with variable references, like this:
2353:
2354: @example
2355: nullstring :=
2356: space := $(nullstring) $(nullstring)
2357: @end example
2358:
2359: @noindent
2360: Here the value of the variable @code{space} is precisely one space.
2361:
2362: @node Setting, Override Directive, Flavors, Variables
2363: @section Setting Variables
2364: @cindex setting variables
2365: @cindex =
2366: @cindex :=
2367:
2368: To set a variable from the makefile, write a line starting with the
2369: variable name followed by @samp{=} or @samp{:=}. Whatever follows the
2370: @samp{=} or @samp{:=} on the line becomes the value. For example,
2371:
2372: @example
2373: objects = main.o foo.o bar.o utils.o
2374: @end example
2375:
2376: @noindent
2377: defines a variable named @code{objects}. Spaces around the variable name
2378: are ignored, and so are spaces after the @samp{=} or at the end of the
2379: line.
2380:
2381: Variables defined with @samp{=} are @dfn{recursively expanded} variables.
2382: Variables defined with @samp{:=} are @dfn{simply expanded} variables; these
2383: definitions can contain variable references which will be expanded before
2384: the definition is made. @xref{Flavors}.
2385:
2386: There is no limit on the length of the value of a variable except the
2387: amount of swapping space on the computer. When a variable definition is
2388: long, it is a good idea to break it into several lines by inserting
2389: backslash-newline at convenient places in the definition. This will not
2390: affect the functioning of @code{make}, but it will make the makefile easier
2391: to read.
2392:
2393: Most variable names are considered to have the empty string as a value if
2394: you have never set them. Several variables have built-in initial values
2395: that are not empty, but can be set by you in the usual ways
2396: (@pxref{Implicit Variables}). Several special variables are set
2397: automatically to a new value for each rule; these are called the
2398: @dfn{automatic} variables (@pxref{Automatic}).
2399:
2400: @node Override Directive, Defining, Setting, Variables
2401: @section The @code{override} Directive
2402: @findex override
2403:
2404: If a variable has been set with a command argument (@pxref{Overriding}),
2405: then ordinary assignments in the makefile are ignored. If you want to set
2406: the variable in the makefile even though it was set with a command
2407: argument, you can use an @code{override} directive, which is a line that
2408: looks like this:
2409:
2410: @example
2411: override @var{variable} = @var{value}
2412: @end example
2413:
2414: or
2415:
2416: @example
2417: override @var{variable} := @var{value}
2418: @end example
2419:
2420: The @code{override} directive was not invented for escalation in the war
2421: between makefiles and command arguments. It was invented so you can alter
2422: and add to values that the user specifies with command arguments.
2423:
2424: For example, suppose you always want the @samp{-g} switch when you run the
2425: C compiler, but you would like to allow the user to specify the other
2426: switches with a command argument just as usual. You could use this
2427: @code{override} directive:
2428:
2429: @example
2430: override CFLAGS := $(CFLAGS) -g
2431: @end example
2432:
2433: @node Defining, Environment, Override Directive, Variables
2434: @section Defining Variables Verbatim
2435: @findex define
2436: @findex endef
2437:
2438: Another way to set the value of a variable is to use the @code{define}
2439: directive. This directive has a different syntax which allows newline
2440: characters to be included in the value, which is convenient for defining
2441: canned sequences of commands (@pxref{Sequences}).
2442:
2443: The @code{define} directive is followed on the same line the name of the
2444: variable and nothing more. The value to give the variable appears on the
2445: following lines. The end of the value is marked by a line containing just
2446: the word @code{endef}. Aside from this difference in syntax, @code{define}
2447: works just like @samp{=}; it creates a recursively-expanded variable
2448: (@pxref{Flavors}).
2449:
2450: @example
2451: define two-lines
2452: echo foo
2453: echo $(bar)
2454: endef
2455: @end example
2456:
2457: The value in an ordinary assignment cannot contain a newline; but the
2458: newlines that separate the lines of the value in a @code{define} become
2459: part of the variable's value (except for the final newline which precedes
2460: the @code{endef} and is not considered part of the value).@refill
2461:
2462: The previous example is functionally equivalent to this:
2463:
2464: @example
2465: two-lines = echo foo; echo $(bar)
2466: @end example
2467:
2468: @noindent
2469: since the shell will interpret the semicolon and the newline identically.
2470:
2471: @node Environment,, Defining, Variables
2472: @section Variables from the Environment
2473:
2474: @cindex environment
2475: Variables in @code{make} can come from the environment with which
2476: @code{make} is run. Every environment variable that @code{make} sees when
2477: it starts up is transformed into a @code{make} variable with the same name
2478: and value. But an explicit assignment in the makefile, or with a command
2479: argument, overrides the environment. (If the @samp{-e} flag is specified,
2480: then values from the environment override assignments in the makefile.
2481: @xref{Options}. But this is not recommended practice.)
2482:
2483: By setting the variable @code{CFLAGS} in your environment, you can cause
2484: all C compilations in most makefiles to use the compiler switches you
2485: prefer. This is safe for variables with standard or conventional meanings
2486: because you know that no makefile will use them for other things. (But
2487: this is not totally reliable; some makefiles set @code{CFLAGS} explicitly
2488: and therefore are not affected by the value in the environment.)
2489:
2490: When @code{make} is invoked recursively, variables defined in the outer
2491: invocation are automatically passed to inner invocations through the
2492: environment (@pxref{Recursion}). This is the main purpose of turning
2493: environment variables into @code{make} variables, and it requires no
2494: attention from you.
2495:
2496: Other use of variables from the environment is not recommended. It is not
2497: wise for makefiles to depend for their functioning on environment variables
2498: set up outside their control, since this would cause different users to get
2499: different results from the same makefile. This is against the whole
2500: purpose of most makefiles.
2501:
2502: Such problems would be especially likely with the variable @code{SHELL},
2503: which is normally present in the environment to specify the user's choice
2504: of interactive shell. It would be very undesirable for this choice to
2505: affect @code{make}. So @code{make} ignores the environment value of
2506: @code{SHELL} if the value of @code{MAKELEVEL} is zero (which is normally
2507: true except in recursive invocations of @code{make}).@refill
2508:
2509: @node Conditionals, Functions, Variables, Top
2510: @chapter Conditional Parts of Makefiles
2511:
2512: @cindex conditionals
2513: A @dfn{conditional} causes part of a makefile to be obeyed or ignored
2514: depending on the values of variables. Conditionals can compare the value
2515: of one variable with another, or the value of a variable with a constant
2516: string. Conditionals control what @code{make} actually ``sees'' in the
2517: makefile, so they @emph{cannot} be used to control shell commands at the
2518: time of execution.@refill
2519:
2520: @menu
2521: * Example: Conditional Example. An annotated example.
2522: * Syntax: Conditional Syntax. Precise rules for syntax of conditionals.
2523: * Flags: Testing Flags. Conditionals testing flags such as @samp{-t}.
2524: @end menu
2525:
2526: @node Conditional Example, Conditional Syntax, Conditionals, Conditionals
2527: @section Example of a Conditional
2528:
2529: This conditional tells @code{make} to use one set of libraries if the
2530: @code{CC} variable is @samp{gcc}, and a different set of libraries
2531: otherwise. It works by controlling which of two command lines will be used
2532: as the command for a rule. The result is that @samp{CC=gcc} as an argument
2533: to @code{make} not only changes which compiler is used but also which
2534: libraries are linked.
2535:
2536: @example
2537: libs_for_gcc = -lgnu
2538: normal_libs =
2539:
2540: foo: $(objects)
2541: ifeq ($(CC),gcc)
2542: $(CC) -o foo $(objects) $(libs_for_gcc)
2543: else
2544: $(CC) -o foo $(objects) $(normal_libs)
2545: endif
2546: @end example
2547:
2548: @noindent
2549: This conditional uses three directives: one @code{ifeq}, one @code{else}
2550: and one @code{endif}.
2551:
2552: The @code{ifeq} directive contains two arguments, separated by a comma and
2553: surrounded by parentheses. Variable substitution is performed on both
2554: arguments and then they are compared. The lines of the makefile following
2555: the @code{ifeq} are obeyed if the two arguments match; otherwise they are
2556: ignored.
2557:
2558: The @code{else} directive causes the following lines to be obeyed if the
2559: previous conditional failed. In the example above, this means that the
2560: second alternative linking command is used whenever the first alternative
2561: is not used. It is optional to have an @code{else} in a conditional.
2562:
2563: The @code{endif} directive ends the conditional. Every conditional must
2564: end with an @code{endif}. Unconditional makefile text follows.
2565:
2566: When the variable @code{CC} has the value @samp{gcc}, the above example has
2567: this effect:
2568:
2569: @example
2570: foo: $(objects)
2571: $(CC) -o foo $(objects) $(libs_for_gcc)
2572: @end example
2573:
2574: @noindent
2575: When the variable @code{CC} has any other value, this effect is this:
2576:
2577: @example
2578: foo: $(objects)
2579: $(CC) -o foo $(objects) $(normal_libs)
2580: @end example
2581:
2582: Equivalent results can be obtained in another way by conditionalizing a
2583: variable assignment and then using the variable unconditionally:
2584:
2585: @example
2586: libs_for_gcc = -lgnu
2587: normal_libs =
2588:
2589: ifeq ($(CC),gcc)
2590: libs=$(libs_for_gcc)
2591: else
2592: libs=$(normal_libs)
2593: endif
2594:
2595: foo: $(objects)
2596: $(CC) -o foo $(objects) $(libs)
2597: @end example
2598:
2599: @node Conditional Syntax, Testing Flags, Conditional Example, Conditionals
2600: @section Syntax of Conditionals
2601: @findex ifdef
2602: @findex ifeq
2603: @findex else
2604: @findex endif
2605:
2606: The syntax of a simple conditional with no @code{else} is as follows:
2607:
2608: @example
2609: @var{conditional-directive}
2610: @var{text-if-true}
2611: endif
2612: @end example
2613:
2614: @noindent
2615: The @var{text-if-true} may be any lines of text, to be considered as part
2616: of the makefile if the condition is true. If the condition is false, no
2617: text is used instead.
2618:
2619: The syntax of a complex conditional is as follows:
2620:
2621: @example
2622: @var{conditional-directive}
2623: @var{text-if-true}
2624: else
2625: @var{text-if-false}
2626: endif
2627: @end example
2628:
2629: @noindent
2630: If the condition is true, @var{text-if-true} is used; otherwise,
2631: @var{text-if-false} is used instead. The @var{text-if-false} can be any
2632: number of lines of text.
2633:
2634: Conditionals work at the textual level. The lines of the
2635: @var{text-if-true} are read as part of the makefile if the condition is
2636: true; if the condition is false, those lines are ignored completely. It
2637: follows that syntactic units of the makefile, such as rules, may safely be
2638: split across the beginning or the end of the conditional.@refill
2639:
2640: You may use an @code{include} directive within a conditional, but you may
2641: not start a conditional in one file and end it in another.
2642:
2643: The syntax of the @var{conditional-directive} is the same whether the
2644: conditional is simple or complex. There are four different directives that
2645: test different conditions. Here is a table of them:
2646:
2647: @table @code
2648: @item ifeq (@var{arg1}, @var{arg2})
2649: Expand all variable references in @var{arg1} and @var{arg2} and
2650: compare them. If they are identical, the @var{text-if-true} is
2651: effective; otherwise, the @var{text-if-false}, if any, is effective.
2652:
2653: @item ifneq (@var{arg1}, @var{arg2})
2654: Expand all variable references in @var{arg1} and @var{arg2} and
2655: compare them. If they are different, the @var{text-if-true} is
2656: effective; otherwise, the @var{text-if-false}, if any, is effective.
2657:
2658: @item ifdef @var{variable-name}
2659: If the variable @var{variable-name} has a non-empty value, the
2660: @var{text-if-true} is effective; otherwise, the @var{text-if-false},
2661: if any, is effective. Variables that have never been defined have an
2662: empty value.
2663:
2664: @item ifndef @var{variable-name}
2665: If the variable @var{variable-name} has an empty value, the
2666: @var{text-if-true} is effective; otherwise, the @var{text-if-false},
2667: if any, is effective.
2668: @end table
2669:
2670: Extra spaces are allowed and ignored at the beginning of the conditional
2671: directive line, but a tab is not allowed. (If the line begins with a tab,
2672: it will be considered a command for a rule.) Aside from this, extra spaces
2673: or tabs may be inserted with no effect anywhere except within the directive
2674: name or within an argument. A comment starting with @samp{#} may appear at
2675: the end of the line.
2676:
2677: The other two directives that play a part in a conditional are @code{else}
2678: and @code{endif}. Each of these directives is written as one word, with no
2679: arguments. Extra spaces are allowed and ignored at the beginning of the
2680: line, and spaces or tabs at the end. A comment starting with @samp{#} may
2681: appear at the end of the line.
2682:
2683: @node Testing Flags,, Conditional Syntax, Conditionals
2684: @section Conditionals that Test Flags
2685:
2686: You can write a conditional that tests @code{make} command flags such as
2687: @samp{-t} by using the variable @code{MAKEFLAGS} together with the
2688: @code{findstring} function. This is useful when @code{touch} is not
2689: enough to make a file appear up to date.
2690:
2691: The @code{findstring} function determines whether one string appears as a
2692: substring of another. If you want to test for the @samp{-t} flag,
2693: use @samp{t} as the first string and the value of @code{MAKEFLAGS} as
2694: the other.
2695:
2696: For example, here is how to arrange to use @samp{ranlib -t} to finish
2697: marking an archive file up to date:
2698:
2699: @example
2700: archive.a: @dots{}
2701: ifneq (,$(findstring t,$(MAKEFLAGS)))
2702: @@echo $(MAKE) > /dev/null
2703: touch archive.a
2704: ranlib -t archive.a
2705: else
2706: ranlib archive.a
2707: endif
2708: @end example
2709:
2710: @noindent
2711: The @code{echo} command does nothing when executed; but its presence, with
2712: a reference to the variable @code{MAKE}, marks the rule as ``recursive'' so
2713: that its commands will be executed despite use of the @samp{-t} flag.
2714: @xref{Recursion}.
2715:
2716: @node Functions, Running, Conditionals, Top
2717: @chapter Functions for Transforming Text
2718: @cindex function
2719:
2720: @dfn{Functions} allow you to do text processing in the makefile to compute
2721: the files to operate on or the commands to use. You use a function in a
2722: @dfn{function call}, where you give the name of the function and some text
2723: (the @dfn{arguments}) for the function to operate on. The result of the
2724: function's processing is substituted into the makefile at the point of the
2725: call, just as a variable might be substituted.
2726:
2727: @menu
2728: * Syntax: Function Syntax. Syntax of function calls in general.
2729: * Text Functions:: Text manipulation functions.
2730: * Foreach Function:: The @code{foreach} function.
2731: * Filename Functions:: Functions for manipulating file names.
2732: @end menu
2733:
2734: @node Function Syntax, Text Functions, Functions, Functions
2735: @section Function Call Syntax
2736: @cindex $ (function call)
2737: @cindex arguments
2738:
2739: A function call resembles a variable reference. It looks like this:
2740:
2741: @example
2742: $(@var{function} @var{arguments})
2743: @end example
2744:
2745: @noindent
2746: or like this:
2747:
2748: @example
2749: $@{@var{function} @var{arguments}@}
2750: @end example
2751:
2752: Here @var{function} is a function name; one of a short list of names that
2753: are part of @code{make}. There is no provision for defining new functions.
2754:
2755: The @var{arguments} are the arguments of the function. They are separated
2756: from the function name by one or more spaces and/or tabs, and if there is
2757: more than one argument they are separated by commas. Such whitespace and
2758: commas are not part of any argument's value. Parentheses or braces,
2759: whichever you use to surround the function call, can appear in an argument
2760: only in matching pairs; the ones that were not used to surround the
2761: function call can appear freely. If the arguments contain other function
2762: calls or variable references, it is wisest to surround them with the same
2763: delimiters used for the containing function call.
2764:
2765: The text written for each argument is processed by substitution of
2766: variables and function calls in order to produce the argument value, which
2767: is the text on which the function acts.
2768:
2769: Commas and unmatched parentheses or braces cannot appear in the text of an
2770: argument as written; leading spaces cannot appear in the text of the first
2771: argument as written. These characters can be put into the argument value
2772: by variable substitution. First define variables @code{comma} and
2773: @code{space} whose values are isolated comma and space characters, then
2774: substitute those variables where such characters are wanted, like this:
2775:
2776: @example
2777: comma:= ,
2778: space:= $(empty) $(empty)
2779: foo:= a b c
2780: bar:= $(subst $(space),$(comma),$(foo))
2781: # @r{bar is now `a,b,c'.}
2782: @end example
2783:
2784: @noindent
2785: Here the @code{subst} function replaces each space with a comma, through
2786: the value of @code{foo}, and substitutes the result.
2787:
2788: @node Text Functions, Foreach Function, Function Syntax, Functions
2789: @section Functions for String Substitution and Analysis
2790:
2791: Here are some functions that operate strings:
2792:
2793: @table @code
2794: @item $(subst @var{from},@var{to},@var{text})
2795: @findex subst
2796: Performs a textual replacement on the text @var{text}: each occurrence
2797: of @var{from} is replaced by @var{to}. The result is substituted for
2798: the function call. For example,
2799:
2800: @example
2801: $(subst ee,EE,feet on the street)
2802: @end example
2803:
2804: substitutes the string @samp{fEEt on the strEEt}.
2805:
2806: @item $(patsubst @var{pattern},@var{replacement},@var{text})
2807: @findex patsubst
2808: Finds whitespace-separated words in @var{text} that match
2809: @var{pattern} and replaces them with @var{replacement}. Here
2810: @var{pattern} may contain a @samp{%} which acts as a wildcard,
2811: matching any number of any characters within a word. If
2812: @var{replacement} also contains a @samp{%}, the @samp{%} is replaced
2813: by the text that matched the @samp{%} in @var{pattern}.@refill
2814:
2815: Whitespace between words is folded into single space characters;
2816: leading and trailing whitespace is discarded.
2817:
2818: @item $(strip @var{string})
2819: @findex strip
2820: Removes leading and trailing whitespace from @var{string} and replaces
2821: each internal sequence of one or more whitespace characters with a
2822: single space.
2823:
2824: @item $(findstring @var{find},@var{in})
2825: @findex findstring
2826: Searches @var{in} for an occurrence of @var{find}. If it occurs, the
2827: value is @var{find}; otherwise, the value is empty. You can use this
2828: function in a conditional to test for the presence of a specific
2829: substring in a given string. @xref{Testing Flags}, for a practical
2830: application of @code{findstring}.
2831:
2832: @item $(filter @var{pattern},@var{text})
2833: @findex filter
2834: Removes all whitespace-separated words in @var{text} that do @emph{not}
2835: match @var{pattern}, returning only matching words. The pattern is one
2836: using @samp{%} as used in the @code{patsubst} function. This can be used
2837: to separate out different types of strings (such as filenames) in a variable.
2838: For example:@refill
2839:
2840: @example
2841: sources := foo.c bar.c ugh.h
2842: foo: $(sources)
2843: cc $(filter %.c,$(sources)) -o foo
2844: @end example
2845:
2846: @noindent
2847: says that @file{foo} depends of @file{foo.c}, @file{bar.c} and
2848: @file{ugh.h} but only @file{foo.c} and @file{bar.c} should be specified
2849: in the command to the compiler.@refill
2850:
2851: @item $(filter-out @var{pattern},@var{text})
2852: @findex filter-out
2853: Removes all whitespace-separated words in @var{text} that @emph{do}
2854: match @var{pattern}, returning only matching words. This is the exact
2855: opposite of the @code{filter} function.@refill
2856:
2857: @item $(sort @var{list})
2858: @findex sort
2859: Sorts the words of @var{list} in lexical order, removing duplicate
2860: words. The output is a list of words separated by single spaces.
2861:
2862: @item $(word @var{n},@var{text})
2863: @findex word
2864: Returns the @var{n}th word of @var{text}. If @var{n} is bigger than
2865: the number of words in @var{text}, nothing is returned. If you give
2866: 0 as @var{n}, you will get a fatal error to remind you to quit
2867: thinking like a C programmer.
2868:
2869: @item $(words @var{text})
2870: @findex words
2871: Returns the number of words in @var{text}. Thus, @code{$(word
2872: $(words @var{text}),@var{text})} is the last word of @var{text}.@refill
2873: @end table
2874:
2875: Here is a realistic example of the use of @code{subst}. Suppose that a
2876: makefile uses the @code{VPATH} variable to specify a list of directories
2877: that @code{make} should search for dependency files. This example shows
2878: how to tell the C compiler to search for header files in the same list of
2879: directories.
2880:
2881: The value of @code{VPATH} is a list of directories separated by colons,
2882: such as @samp{src:../headers}. First, the @code{subst} function is used to
2883: change the colons to spaces:
2884:
2885: @example
2886: $(subst :, ,$(VPATH))
2887: @end example
2888:
2889: @noindent
2890: This produces @samp{src ../headers}. Then another function,
2891: @code{addprefix}, can turn each directory name into an @samp{-I} flag.
2892: These can be added to the value of the variable @code{CFLAGS}, which is
2893: passed automatically to the C compiler, like this:
2894:
2895: @example
2896: override CFLAGS:= $(CFLAGS) $(addprefix -I,$(subst :, ,$(VPATH)))
2897: @end example
2898:
2899: @noindent
2900: The effect is to append the text @samp{-Isrc -I../headers} to the
2901: previously given value of @code{CFLAGS}. The @code{override} directive is
2902: used so that the new value is assigned even if the previous value of
2903: @code{CFLAGS} was specified with a command argument (@pxref{Override
2904: Directive}).
2905:
2906: The function @code{strip} can be very useful when used in conjunction
2907: with conditionals. When comparing something with the null string
2908: @samp{""} using @code{ifeq} or @code{ifneq}, you usually want a string
2909: of just whitespace to match the null string. Thus,
2910:
2911: @example
2912: .PHONY: all
2913: ifneq "$(needs_made)" ""
2914: all: $(needs_made)
2915: else
2916: all:;@@echo 'Nothing to make!'
2917: endif
2918: @end example
2919:
2920: @noindent
2921: might fail to have the desired results. Replacing the variable reference
2922: @samp{"$(needs_made)"} with the function call @samp{"$(strip
2923: $(needs_made))"} in the @code{ifneq} directive would make it more robust.
2924:
2925: @node Foreach Function, Filename Functions, Text Functions, Functions
2926: @section The @code{foreach} Function
2927: @findex foreach
2928:
2929: The @code{foreach} function is very different from other functions. It
2930: causes one piece of text to be used repeatedly, each time with a different
2931: substitution performed on it. It resembles the @code{for} command in the
2932: shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}.
2933:
2934: The syntax of the @code{foreach} function is:
2935:
2936: @example
2937: $(foreach @var{var},@var{list},@var{text})
2938: @end example
2939:
2940: @noindent
2941: The first two arguments, @var{var} and @var{list}, are expanded before
2942: anything else is done; note that the last argument, @var{text}, is
2943: @emph{not} expanded at the same time. Then for each word of the expanded
2944: value of @var{list}, the variable named by the expanded value of @var{var}
2945: is set to that word, and @var{text} is expanded. Presumably @var{text}
2946: contains references to that variable, so the expansions will be different
2947: each time.
2948:
2949: The result is that @var{text} is expanded as many times as there are
2950: whitespace-separated words in @var{list}. The multiple expansions of
2951: @var{text} are concatenated, with spaces between them, to make the result
2952: of @code{foreach}.
2953:
2954: This simple example sets the variable @samp{files} to the list of all files
2955: in the directories in the list @samp{dirs}:
2956:
2957: @example
2958: find_files = $(wildcard $(dir)/*)
2959: dirs := a b c d
2960: files := $(foreach dir,$(dirs),$(find_files))
2961: @end example
2962:
2963: For readability, it is a good idea to put the @var{text} part of a
2964: @code{foreach} function invokation into a variable. Here we use the
2965: variable @code{find_file} this way. We make this a recursively-expanding
2966: variable by using @samp{=} to define it. This is necessary so that when
2967: its value is substituted by @code{foreach} the value is rescanned for
2968: variable references and function calls. This is what causes the
2969: @code{wildcard} function actually to be called.
2970:
2971: This example has the same result (except for setting @samp{find_files},
2972: @samp{dirs} and @samp{dir}) as the following example:
2973:
2974: @example
2975: files := $(wildcard a/* b/* c/* d/*)
2976: @end example
2977:
2978: The value of the variable @var{var} after the @code{foreach} function call
2979: is the same as the value beforehand. Other values taken from @var{list}
2980: are in effect only temporarily, during the execution of @code{foreach}.
2981: The variable @var{var} is a simply-expanded variable during the execution
2982: of @code{foreach} but is returned to the same flavor it was before the
2983: @code{foreach} when it is done. @xref{Flavors}.
2984:
2985: If @var{var} was previously undefined, then it is defined as a recursively
2986: expanded variable (@samp{=}, not @samp{:=}) during the @code{foreach} and
2987: remains so (with a null value) afterward.
2988:
2989: Because it is expanded before @code{foreach} runs, the @var{var} argument
2990: to @code{foreach} need not be a literal variable name. It can instead be a
2991: variable expression resulting in the name. Thus,
2992:
2993: @example
2994: dir := a
2995: var = $(whatsthevar)
2996: foo := dar
2997: whatsthevar := $(subst a,i,$(foo))
2998: files := $(foreach $(var),$(dirs),$(find_files))
2999: @end example
3000:
3001: @noindent
3002: is ultimately equivalent to the first example. You must take care when
3003: using complex variable expressions that result in variable names because
3004: many strange things are legal variable names, and these might not be what
3005: you intended. For example,
3006:
3007: @example
3008: files := $(foreach Es escrito en espanol!,b c ch,$(find_files))
3009: @end example
3010:
3011: @noindent
3012: might be useful if @samp{find_files} references the variable @samp{Es
3013: escrito en espanol!} (es un nombre bastante largo, no?), but it is more
3014: likely to be a mistake.
3015:
3016: @node Filename Functions,, Foreach Function, Functions
3017: @section Functions for File Names
3018:
3019: Several of the built-in expansion functions relate specifically to
3020: taking apart file names or lists of file names.
3021:
3022: Each of these functions performs a specific transformation on a file name.
3023: The argument of the function is regarded as a series of file names,
3024: separated by whitespace. (Leading and trailing whitespace is ignored.)
3025: Each file name in the series is transformed in the same way and the results
3026: are concatenated with single spaces between them.
3027:
3028: @table @code
3029: @item $(dir @var{names})
3030: @findex dir
3031: Extracts the directory-part of each file name in @var{names}. The
3032: directory-part of the file name is everything up through (and
3033: including) the last slash in it. If the file name contains no slash,
3034: the directory part is the string @samp{./}. For example,
3035:
3036: @example
3037: $(dir src/foo.c hacks)
3038: @end example
3039:
3040: @noindent
3041: produces the result @samp{src/ ./}.
3042:
3043: @item $(notdir @var{names})
3044: @findex notdir
3045: Extracts all but the directory-part of each file name in @var{names}.
3046: If the file name contains no slash, it is left unchanged. Otherwise,
3047: everything through the last slash is removed from it. A file name
3048: that ends with a slash becomes an empty string. This is unfortunate,
3049: because it means that the result does not always have the same number
3050: of whitespace-separated file names as the argument had; but we do not
3051: see any other valid alternative.
3052:
3053: For example,
3054:
3055: @example
3056: $(notdir src/foo.c hacks)
3057: @end example
3058:
3059: @noindent
3060: produces the result @samp{foo.c hacks}.
3061:
3062: @item $(suffix @var{names})
3063: @findex suffix
3064: Extracts the suffix of each file name in @var{names}. If the file name
3065: contains a period, the suffix is everything starting with the last
3066: period. Otherwise, the suffix is the empty string. This frequently
3067: means that the result will be empty when @var{names} is not, and if
3068: @var{names} contains multiple file names, the result may contain fewer
3069: file names.
3070:
3071: For example,
3072:
3073: @example
3074: $(suffix src/foo.c hacks)
3075: @end example
3076:
3077: @noindent
3078: produces the result @samp{.c}.
3079:
3080: @item $(basename @var{names})
3081: @findex basename
3082: Extracts all but the suffix of each file name in @var{names}. If the
3083: file name contains a period, the basename is everything starting up to
3084: (and not including) the last period. Otherwise, the basename is the
3085: entire file name. For example,
3086:
3087: @example
3088: $(basename src/foo.c hacks)
3089: @end example
3090:
3091: @noindent
3092: produces the result @samp{src/foo hacks}.
3093:
3094: @item $(addsuffix @var{suffix},@var{names})
3095: @findex addsuffix
3096: The argument @var{names} is regarded as a series of names, separated
3097: by whitespace; @var{suffix} is used as a unit. The value of
3098: @var{suffix} is appended to the end of each individual name and the
3099: resulting larger names are concatenated with single spaces between
3100: them. For example,
3101:
3102: @example
3103: $(addsuffix .c,foo bar)
3104: @end example
3105:
3106: @noindent
3107: produces the result @samp{foo.c bar.c}.
3108:
3109: @item $(addprefix @var{prefix},@var{names})
3110: @findex addprefix
3111: The argument @var{names} is regarded as a series of names, separated
3112: by whitespace; @var{prefix} is used as a unit. The value of
3113: @var{prefix} is appended to the front of each individual name and the
3114: resulting larger names are concatenated with single spaces between
3115: them. For example,
3116:
3117: @example
3118: $(addprefix src/,foo bar)
3119: @end example
3120:
3121: @noindent
3122: produces the result @samp{src/foo src/bar}.
3123:
3124: @item $(join @var{list1},@var{list2})
3125: @findex join
3126: Concatenates the two arguments word by word: the two first words (one
3127: from each argument) concatenated form the first word of the result, the
3128: two second words form the second word of the result, and so on. So the
3129: @var{n}th word of the result comes from the @var{n}th word of each
3130: argument. If one argument has more words that the other, the extra
3131: words are copied unchanged into the result.
3132:
3133: For example, @samp{$(join a b,.c .o)} produces @samp{a.c b.o}.
3134:
3135: Whitespace between the words in the lists is not preserved; it is
3136: replaced with a single space.
3137:
3138: This function can reverse the effect of the @code{dir} and @code{notdir}
3139: functions, after other processing has been done on the separated lists
3140: of directories and files.@refill
3141:
3142: @item $(firstword @var{names})
3143: @findex firstword
3144: The argument @var{names} is regarded as a series of names, separated
3145: by whitespace. The value is the first name in the series. The rest
3146: of the names are ignored. For example,
3147:
3148: @example
3149: $(firstword foo bar)
3150: @end example
3151:
3152: @noindent
3153: produces the result @samp{foo}. Although @code{$(firstword
3154: @var{text})} is the same as @code{$(word 1,@var{text})}, the
3155: @code{firstword} function is retained for its ease of use.@refill
3156:
3157: @item $(wildcard @var{pattern})
3158: @findex wildcard
3159: The argument @var{pattern} is a file name pattern, typically containing
3160: wildcard characters. The result of @code{wildcard} is a space-separated
3161: list of the names of existing files that match the pattern.
3162:
3163: Wildcards are expanded automatically in rules (@pxref{Wildcards}).
3164: But they are not normally expanded when a variable is set, or inside the
3165: arguments of other functions. Those occasions are when the @code{wildcard}
3166: function is useful.
3167: @end table
3168:
3169: @node Running, Implicit, Functions, Top
3170: @chapter How to Run @code{make}
3171:
3172: A makefile that says how to recompile a program can be used in more than
3173: one way. The simplest use is to recompile every file that is out of date.
3174: This is what @code{make} will do if run with no arguments.
3175:
3176: But you might want to update only some of the files; you might want to use
3177: a different compiler or different compiler options; you might want just to
3178: find out which files are out of date without changing them.
3179:
3180: By specifying arguments when you run @code{make}, you can do any of these
3181: things or many others.
3182:
3183: @menu
3184: * Makefile Arguments:: Arguments to specify which makefile to use.
3185:
3186: * Goals:: Goal arguments specify which parts of the makefile
3187: should be used.
3188:
3189: * Avoid Compilation:: How to avoid recompiling certain files.
3190:
3191: * Instead of Execution:: Mode flags specify what kind of thing to do
3192: with the commands in the makefile
3193: other than simply execute them.
3194:
3195: * Overriding:: Overriding a variable can specify an alternate
3196: compiler, or alternate flags for the compiler,
3197: or whatever else you program into the makefile.
3198:
3199: * Testing:: How to proceed past some errors, to test compilation.
3200:
3201: * Options:: Summary of all options @code{make} accepts.
3202: @end menu
3203:
3204: @node Makefile Arguments, Goals, Running, Running
3205: @section Arguments to Specify the Makefile
3206:
3207: The way to specify the name of the makefile is with the @samp{-f} option.
3208: For example, @samp{-f altmake} says to use the file @file{altmake} as
3209: the makefile.
3210:
3211: If you use the @samp{-f} flag several times (each time with a
3212: following argument), all the specified files are used jointly as
3213: makefiles.
3214:
3215: If you do not use the @samp{-f} flag, the default is to use
3216: @file{./makefile}, or, if that does not exist, @file{./Makefile}.
3217: @xref{Makefiles}.@refill
3218:
3219: @node Goals, Avoid Compilation, Makefile Arguments, Running
3220: @section Goals
3221: @cindex goal
3222:
3223: The @dfn{goals} are the targets that @code{make} should strive ultimately
3224: to update. Other targets are updated as well if they appear as
3225: dependencies of goals, or dependencies of dependencies of goals, etc.
3226:
3227: By default, the goal is the first target in the makefile (not counting
3228: targets that start with a period or that appear in included makefiles).
3229: Therefore, makefiles are usually written so that the first target is for
3230: compiling the entire program or programs they describe.
3231:
3232: You can specify a different goal or goal with arguments to @code{make}.
3233: Use the name of the goal as an argument. If you specify several goals,
3234: @code{make} processes each of them in turn, in the order you name them.
3235:
3236: Any target in the makefile may be specified as a goal (unless it starts
3237: with @samp{-} or contains an @samp{=}). Even targets not in the makefile
3238: may be specified, if @code{make} can find implicit rules that say how to
3239: make them.
3240:
3241: One use of specifying a goal is if you want to compile only a part of
3242: the program, or only one of several programs. Specify as a goal each
3243: file that you wish to remake. For example, consider a directory containing
3244: a several programs, with a makefile that starts like this:
3245:
3246: @example
3247: .PHONY: all
3248: all: size nm ld ar as
3249: @end example
3250:
3251: If you are working on the program @code{size}, you might want to say
3252: @samp{make size} so that only the files of that program are recompiled.
3253:
3254: Another use of specifying a goal is to make files that aren't normally
3255: made. For example, there may be a file of debugging output, or a version
3256: of the program that is compiled specially for testing, which has a rule
3257: in the makefile but isn't a dependency of the default goal.
3258:
3259: Another use of specifying a goal is to run the commands associated with a
3260: phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty Targets}).
3261: Many makefiles contain a phony target named @file{clean} which deletes
3262: everything except source files. Naturally, this is done only if you
3263: request it explicitly with @samp{make clean}. Here is a list of typical
3264: phony and empty target names:
3265:
3266: @table @file
3267: @item all
3268: Make all the top-level targets the makefile knows about.
3269:
3270: @item clean
3271: Delete all files that the makefile could remake.
3272:
3273: @item clobber
3274: Delete absolutely everything the makefile could remake (whereas
3275: @samp{make clean} often leaves intact some files that might take a
3276: long time to remake).
3277:
3278: @item install
3279: Copy the executable file into a directory that users typically search
3280: for commands; copy any auxiliary files that the executable uses into
3281: the directories where it will look for them.
3282:
3283: @item print
3284: Print listings of the source files that have changed.
3285:
3286: @item tar
3287: Create a tar file of the source files.
3288:
3289: @item shar
3290: Create a shell archive (shar file) of the source files.
3291: @end table
3292:
3293: @node Avoid Compilation, Instead of Execution, Goals, Running
3294: @section Avoiding Recompilation of Some Files
3295: @cindex -o
3296:
3297: Sometimes you may have changed a source file but you don't want to
3298: recompile all the files that depend on it. For example, suppose you add a
3299: macro or a declaration to a header file that many other files depend on.
3300: Being conservative, @code{make} assumes that any change in the header file
3301: requires recompilation of all dependent files, but you know that they don't
3302: need to be recompiled and you would rather not waste the time waiting.
3303:
3304: If you anticipate the problem before making the change, you can use the
3305: @samp{-t} flag. This flag tells @code{make} not to run the commands in the
3306: rules, but rather to mark the target up to date by changing its
3307: last-modification date. You would follow this procedure:
3308:
3309: @enumerate
3310: @item
3311: Use the command @samp{make} to recompile the source files that really
3312: need recompilation.
3313:
3314: @item
3315: Make the changes in the header files.
3316:
3317: @item
3318: Use the command @samp{make -t} to mark all the object files as
3319: up to date. The next time you run @code{make}, the changes in the
3320: header files will not cause any recompilation.
3321: @end enumerate
3322:
3323: If you have already changed the header file at a time when some files do
3324: need recompilation, it is too late to do this. Instead, you can use the
3325: @samp{-o @var{file}} flag, which marks a specified file as ``old''
3326: (@pxref{Options}). This means that the file itself won't be remade,
3327: and nothing else will be remade on its account. Follow this procedure:
3328:
3329: @enumerate
3330: @item
3331: Recompile the source files that need compilation for reasons independent
3332: of the particular header file, with @samp{make -o @var{headerfile}}.
3333: If several header files are involved, use a separate @samp{-o} option
3334: for each header file.
3335:
3336: @item
3337: Touch all the object files with @samp{make -t}.
3338: @end enumerate
3339:
3340: @node Instead of Execution, Overriding, Avoid Compilation, Running
3341: @section Instead of Executing the Commands
3342: @cindex -t
3343: @cindex touch
3344: @cindex -q
3345: @cindex -n
3346:
3347: The makefile tells @code{make} how to tell whether a target is up to date,
3348: and how to update each target. But updating the targets is not always
3349: what you want. Certain options specify other activities for @code{make}.
3350:
3351: @table @samp
3352: @item -t
3353: ``Touch''. The activity is to mark the targets as up to date without
3354: actually changing them. In other words, @code{make} pretends to compile
3355: the targets but does not really change their contents.
3356:
3357: @item -n
3358: ``No-op''. The activity is to print what commands would be used to make
3359: the targets up to date, but not actually execute them.
3360:
3361: @item -q
3362: ``Question''. The activity is to find out silently whether the targets
3363: are up to date already; but execute no commands in either case. In other
3364: words, neither compilation nor output will occur.
3365: @end table
3366:
3367: With the @samp{-n} flag, @code{make} prints without execution the commands
3368: that it would normally execute.
3369:
3370: With the @samp{-t} flag, @code{make} ignores the commands in the rules
3371: and uses (in effect) the command @code{touch} for each target that needs to
3372: be remade. The @code{touch} command is also printed, unless @samp{-s} or
3373: @code{.SILENT} is used. For speed, @code{make} does not actually invoke
3374: the program @code{touch}. It does the work directly.
3375:
3376: With the @samp{-q} flag, @code{make} prints nothing and executes no
3377: commands, but the exit status code it returns is zero if and only if the
3378: targets to be considered are already up to date.
3379:
3380: It is an error to use more than one of these three flags in the same
3381: invocation of @code{make}.
3382:
3383: If you are not at all interested in what @code{make} @emph{would} do,
3384: but rather in some other information about @code{make}, there are two
3385: options: the command line @samp{make -p -f /dev/null} will print the
3386: information in @code{make}'s database of variables, rules, directories
3387: and files and @samp{make -v -f /dev/null} will print information about
3388: what version of GNU @code{make} you are using. @xref{Options}.@refill
3389:
3390: @node Overriding, Testing, Instead of Execution, Running
3391: @section Overriding Variables
3392:
3393: You can override the value of a variable using an argument to @code{make}
3394: that contains a @samp{=}. The argument @samp{@var{v}=@var{x}} (or
3395: @samp{@var{v}:=@var{x}}; @pxref{Flavors}) sets the value of the variable
3396: @var{v} to @var{x}.
3397:
3398: Values specified this way override all values specified in the makefile
3399: itself; once you have set a variable with a command argument, any ordinary
3400: attempt in the makefile to change that variable is simply ignored.
3401:
3402: One way to use this facility is to pass extra flags to compilers.
3403: For example, in a properly written makefile, the variable @code{CFLAGS}
3404: is included in each command that runs the C compiler, so a file
3405: @file{foo.c} would be compiled like this:
3406:
3407: @example
3408: cc -c $(CFLAGS) foo.c
3409: @end example
3410:
3411: Thus, whatever value you set for @code{CFLAGS} affects each compilation
3412: that occurs. The makefile probably specifies the usual value for
3413: @code{CFLAGS}, like this:
3414:
3415: @example
3416: CFLAGS=-g
3417: @end example
3418:
3419: Each time you run @code{make}, you can override this value and specify a
3420: different value. For example, if you say @samp{make CFLAGS='-g -O'}, each
3421: C compilation will be done with @samp{cc -c -g -O}. (This illustrates how
3422: you can enclose spaces and other special characters in the value of a
3423: variable when you override it.)
3424:
3425: The variable @code{CFLAGS} is only one of many standard variables that
3426: exist just so that you can change them this way.
3427: @xref{Implicit Variables}, for a complete list.
3428:
3429: You can also program the makefile to look at additional variables of your
3430: own, giving the user ability to control other aspects of how the makefile
3431: works by changing the variables.
3432:
3433: There is one way that the makefile can change a variable that you have
3434: overridden. This is to use the @code{override} directive, which is a line
3435: that looks like this: @samp{override @var{variable} = @var{value}}.
3436: @xref{Override Directive}.
3437:
3438: @node Testing, Options, Overriding, Running
3439: @section Testing the Compilation of a Program
3440:
3441: Normally, when an error happens in executing a shell command, @code{make}
3442: gives up immediately, returning a nonzero status. No further commands are
3443: executed for any target. The error implies that the goal cannot be
3444: correctly remade, and @code{make} reports this as soon as it knows.
3445:
3446: When you are compiling a program that you have just changed, this is not
3447: what you want. Instead, you would rather that @code{make} try compiling
3448: every file that can be tried, to show you all the compilation errors.
3449:
3450: @cindex -k
3451: On these occasions, you should use the @samp{-k} flag. This tells
3452: @code{make} to continue to consider the other dependencies of the pending
3453: targets, remaking them if necessary, before it gives up and returns nonzero
3454: status. For example, after an error in compiling one object file,
3455: @samp{make -k} will continue compiling other object files even though it
3456: already knows that linking them will be impossible. In addition to
3457: contuing after failing shell commands, @samp{make -k} will continue as much
3458: as possible after discovering that it doesn't know how to make a target or
3459: dependency file. This will always cause an error message, but without
3460: @samp{-k}, it is a fatal error. @xref{Options}.
3461:
3462: The usual behavior of @code{make} assumes that your purpose is to get the
3463: goals up to date; once @code{make} learns that this is impossible, it might
3464: as well report the failure immediately. The @samp{-k} flag says that the
3465: real purpose is to test as much as possible of the changes made in the
3466: program, perhaps to find several independent problems so that you can
3467: correct them all before the next attempt to compile. This is why Emacs's
3468: @code{compile} command passes the @samp{-k} flag by default.
3469:
3470: @node Options,, Testing, Running
3471: @section Summary of Options
3472: @cindex options
3473: @cindex flags
3474:
3475: Here is a table of all the options @code{make} understands:
3476:
3477: @table @samp
3478: @item -b
3479: @itemx -m
3480: These options are ignored for compatibility with other versions of @code{make}.
3481:
3482: @item -c @var{dir}
3483: Change to directory @var{dir} before executing the rules. If multiple
3484: @samp{-c} options are specified, each is interpreted relative to the
3485: previous one: @samp{-c / -c etc} is equivalent to @samp{-c /etc}.
3486: This is typically used with recursive invocations of @code{make}
3487: (@pxref{Recursion}).
3488:
3489: @item -d
3490: Print debugging information in addition to normal processing. The
3491: debugging information says which files are being considered for
3492: remaking, which file-times are being compared and with what results,
3493: which files actually need to be remade, which implicit rules are
3494: considered and which are applied---everything interesting about how
3495: @code{make} decides what to do.
3496:
3497: @item -f @var{file}
3498: Use file @var{file} as a makefile. @xref{Makefiles}.
3499:
3500: @item -i
3501: Ignore all errors in commands executed to remake files.
3502: @xref{Errors}.
3503:
3504: @item -I @var{dir}
3505: Specifies a directory @var{dir} to search for included makefiles.
3506: @xref{Include}. If several @samp{-I} options are used to specify
3507: several directories, the directories are searched in the order
3508: specified.
3509:
3510: @item -k
3511: Continue as much as possible after an error. While the target that
3512: failed, and those that depend on it, cannot be remade, the other
3513: dependencies of these targets can be processed all the same.
3514: @xref{Testing}.
3515:
3516: @item -n
3517: Print the commands that would be executed, but do not execute them.
3518: @xref{Instead of Execution}.
3519:
3520: @item -o @var{file}
3521: Do not remake the file @var{file} even if it is older than its
3522: dependencies, and do not remake anything on account of changes in
3523: @var{file}. Essentially the file is treated as very old and its rules
3524: are ignored. @xref{Avoid Compilation}.
3525:
3526: @item -p
3527: Print the data base (rules and variable values) that results from
3528: reading the makefiles; then execute as usual or as otherwise
3529: specified. This also prints the version information given by
3530: the @samp{-v} switch (see below). To print the data base without
3531: trying to remake any files, use @samp{make -p -f /dev/null}.
3532:
3533: @item -q
3534: ``Question mode''. Do not run any commands, or print anything; just
3535: return an exit status that is zero if the specified targets are
3536: already up to date, nonzero otherwise. @xref{Instead of Execution}.
3537:
3538: @item -r
3539: Eliminate use of the built-in implicit rules (@pxref{Implicit}).
3540: Also clear out the default list of suffixes for suffix rules
3541: (@pxref{Suffix Rules}).
3542:
3543: @item -s
3544: Silent operation; do not print the commands as they are executed.
3545: @xref{Echoing}.
3546:
3547: @item -S
3548: Cancel the effect of the @samp{-k} option. This is never necessary
3549: except in a recursive @code{make} where @samp{-k} might be inherited
3550: from the top-level @code{make} via @code{MAKEFLAGS} (@pxref{Recursion})
3551: or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill
3552:
3553: @item -t
3554: Touch files (mark them up to date without really changing them)
3555: instead of running their commands. This is used to pretend (to fool
3556: future invocations of @code{make}) that the commands were done.
3557: @xref{Instead of Execution}.
3558:
3559: @item -v
3560: Print the version of the @code{make} program plus a copyright,
3561: list of authors and notice of (non)warranty (short).
3562: After this information is printed, processing continues normally.
3563: To get the version information without doing anything else,
3564: use @samp{make -v -f /dev/null}.
3565:
3566: @item -w
3567: Print a message containing the working directory both before and after
3568: executing the makefile; this is useful for tracking down errors from
3569: builds of large directory trees. @xref{Recursion}.
3570: @end table
3571:
3572: @node Implicit, Archives, Running, Top
3573: @chapter Using Implicit Rules
3574: @cindex implicit rule
3575:
3576: Certain standard ways of remaking target files are used very often. For
3577: example, one customary way to make an object file is from a C source file
3578: using the C compiler, @code{cc}.
3579:
3580: @dfn{Implicit rules} tell @code{make} how to use customary techniques so
3581: that you don't have to specify them in detail when you want to use them.
3582: For example, there is an implicit rule for C compilation.
3583:
3584: Implicit rules work based on file names. For example, C compilation typically
3585: takes a @file{.c} file and makes a @file{.o} file. So @code{make} applies
3586: the implicit rule when it sees this combination of file-name endings.
3587:
3588: A chain of implicit rules can apply in sequence; for example, @code{make}
3589: will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file.
3590: @iftex
3591: @xref{Chained Rules}.
3592: @end iftex
3593:
3594: The built-in implicit rules use several variables in their commands so
3595: that, by changing the values of the variables, you can change the way the
3596: implicit rule works. For example, the variable @code{CFLAGS} controls the
3597: flags given to the C compiler by the implicit rule for C compilation.
3598: @iftex
3599: @xref{Implicit Variables}.
3600: @end iftex
3601:
3602: You can define your own implicit rules by writing @dfn{pattern rules}.
3603: @iftex
3604: @xref{Pattern Rules}.
3605: @end iftex
3606:
3607: @menu
3608: * Using Implicit:: How to use an existing implicit rule
3609: to get the commands for updating a file.
3610:
3611: * Catalogue of Rules:: Catalogue of built-in implicit rules.
3612:
3613: * Implicit Variables:: By changing certain variables, you can
3614: change what the predefined implicit rules do.
3615:
3616: * Chained Rules:: Using a chain of implicit rules.
3617:
3618: * Pattern Rules:: Defining new implicit rules.
3619:
3620: * Search Algorithm:: Precise algorithm for applying implicit rules.
3621: @end menu
3622:
3623: @node Using Implicit, Catalogue of Rules, Implicit, Implicit
3624: @section Using Implicit Rules
3625:
3626: To allow @code{make} to find a customary method for updating a target file,
3627: all you have to do is refrain from specifying commands yourself. Either
3628: write a rule with no command lines, or don't write a rule at all. Then
3629: @code{make} will figure out which implicit rule to use based on which
3630: kind of source file exists.
3631:
3632: For example, suppose the makefile looks like this:
3633:
3634: @example
3635: foo : foo.o bar.o
3636: cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)
3637: @end example
3638:
3639: @noindent
3640: Because you mention @file{foo.o} but do not give a rule for it, @code{make}
3641: will automatically look for an implicit rule that tells how to update it.
3642: This happens whether or not the file @file{foo.o} currently exists.
3643:
3644: If an implicit rule is found, it supplies both commands and a dependency
3645: (the source file). You would want to write a rule for @file{foo.o} with no
3646: command lines if you need to specify additional dependencies, such as
3647: header files, that the implicit rule cannot supply.
3648:
3649: Each implicit rule has a target pattern and dependency patterns. There may
3650: be many implicit rules with the same target pattern. For example, numerous
3651: rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler;
3652: another, from a @samp{.p} file with the Pascal compiler; and so on. The rule
3653: that actually applies is the one whose dependency exists or can be made.
3654:
3655: So, if you have a file @file{foo.c}, @code{make} will run the C compiler;
3656: otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal
3657: compiler; and so on.
3658:
3659: Of course, when you write the makefile, you know which implicit rule you
3660: want @code{make} to use, and you know it will choose that one because you
3661: know which other files are supposed to exist. @xref{Catalogue of Rules},
3662: for a catalogue of all the predefined implicit rules.
3663:
3664: Above, we said an implicit rule applies if the required dependency ``exists
3665: or can be made''. A file ``can be made'' if it is mentioned explicitly in
3666: the makefile as a target or a dependency, or if an implicit rule can be
3667: recursively found for how to make it. When the implicit dependency is the
3668: result of another implicit rule, we say that @dfn{chaining} is occurring.
3669: @xref{Chained Rules}.
3670:
3671: In general, @code{make} searches for an implicit rule for each target, and
3672: for each double-colon rule, that has no commands. A file that is mentioned
3673: only as a dependency is considered a target whose rule specifies nothing,
3674: so implicit rule search happens for it. @xref{Search Algorithm}, for the
3675: details of how the search is done.
3676:
3677: @node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit
3678: @section Catalogue of Implicit Rules
3679:
3680: Here is a catalogue of predefined implicit rules which are always available
3681: unless the makefile explicitly overrides or cancels them.
3682: (@xref{Canceling Rules}, for information on canceling or overriding an
3683: implicit rule. The @samp{-r} option cancels all predefined rules.)
3684:
3685: @table @asis
3686: @item Compiling C programs
3687: @file{@var{n}.o} will be made automatically from @file{@var{n}.c}
3688: with the command @samp{$(CC) -c $(CFLAGS)}.@refill
3689:
3690: @item Compiling Pascal programs
3691: @file{@var{n}.o} will be made automatically from @file{@var{n}.p}
3692: with the command @samp{$(PC) -c $(PFLAGS)}.@refill
3693:
3694: @item Compiling Fortran, EFL and Ratfor programs
3695: @file{@var{n}.o} will be made automatically from @file{@var{n}.e},
3696: @file{@var{n}.r}, @file{@var{n}.F} or @file{@var{n}.f} by running the
3697: Fortran compiler. The precise command used is as follows:@refill
3698:
3699: @table @code
3700: @item .e
3701: @samp{$(FC) -c $(EFLAGS)}.
3702: @item .f
3703: @samp{$(FC) -c $(FFLAGS)}.
3704: @item .F
3705: @samp{$(FC) -c $(FFLAGS)}.
3706: @item .r
3707: @samp{$(FC) -c $(RFLAGS)}.
3708: @end table
3709:
3710: @item Preprocessing Fortran, EFL and Ratfor programs
3711: @file{@var{n}.f} will be made automatically from @file{@var{n}.e},
3712: @file{@var{n}.r} or @file{@var{n}.F}. This rule runs just the
3713: preprocessor to convert a Ratfor, EFL or preprocessable Fortran
3714: program into a strict Fortran program. The precise command used is as
3715: follows:@refill
3716:
3717: @table @code
3718: @item .e
3719: @samp{$(FC) -F $(EFLAGS)}.
3720: @item .F
3721: @samp{$(FC) -F $(FFLAGS)}.
3722: @item .r
3723: @samp{$(FC) -F $(RFLAGS)}.
3724: @end table
3725:
3726: @item Assembling assembler programs
3727: @file{@var{n}.o} will be made automatically from @file{@var{n}.s} by
3728: running the assembler @code{as}. The precise command used is
3729: @samp{$(AS) $(ASFLAGS)}.@refill
3730:
3731: @item Linking a single object file
3732: @file{@var{n}} will be made automatically from @file{@var{n}.o} by
3733: running the linker @code{ld} via the C compiler. The precise command
3734: used is @samp{$(CC) $(LDFLAGS) @dots{} $(LOADLIBES)}.@refill
3735:
3736: This rule does the right thing for a simple program with only one source
3737: file. It will also do the right thing if there are multiple object files
3738: (presumably coming from various other source files), the first of which has
3739: a name matching that of the executable file. Thus,
3740:
3741: @example
3742: x: y.o z.o
3743: @end example
3744:
3745: @noindent
3746: when @file{x.c}, @file{y.c} and @file{z.c} all exist will execute:
3747:
3748: @example
3749: cc -c x.c -o x.o
3750: cc -c y.c -o y.o
3751: cc -c z.c -o z.o
3752: cc x.o y.o z.o -o x
3753: rm -f x.o
3754: rm -f y.o
3755: rm -f z.o
3756: @end example
3757:
3758: @noindent
3759: In more complicated cases, you must write an explicit command for linking.
3760:
3761: @item Yacc for C programs
3762: @file{@var{n}.c} will be made automatically from @file{@var{n}.y} by
3763: running Yacc with the command @samp{$(YACC) $(YFLAGS)}.
3764:
3765: @item Yacc for Ratfor programs
3766: @file{@var{n}.r} will be made automatically from @file{@var{n}.yr} by
3767: running Yacc with the command @samp{$(YACCR) $(YFLAGS)}.
3768:
3769: @item Yacc for EFL programs
3770: @file{@var{n}.e} will be made automatically from @file{@var{n}.ye} by
3771: running Yacc with the command @samp{$(YACCE) $(YFLAGS)}.
3772:
3773: @item Lex for C programs
3774: @file{@var{n}.c} will be made automatically from @file{@var{n}.l} by
3775: by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}.
3776:
3777: @item Lex for Ratfor programs
3778: @file{@var{n}.r} will be made automatically from @file{@var{n}.l} by
3779: by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}.
3780:
3781: The traditional custom of using the same suffix @samp{.l} for all Lex
3782: files regardless of whether they produce C code or Ratfor code makes
3783: it impossible for @code{make} to determine automatically which of the
3784: two languages you are using in any particular case. If @code{make} is
3785: called upon to remake an object file from a @samp{.l} file, it must
3786: guess which compiler to use. It will guess the C compiler, because
3787: that is more common. If you are using Ratfor, make sure @code{make}
3788: knows this by mentioning @file{@var{n}.r} in the makefile.
3789:
3790: @item RCS
3791: Any file @file{@var{n}} will be extracted if necessary from an RCS
3792: file named either @file{@var{n},v} or @file{RCS/@var{n},v}. The
3793: precise command used is @samp{$(CO) $(COFLAGS)}. The variable
3794: @code{CO} has default value @samp{co}.
3795:
3796: @item SCCS
3797: Any file @file{@var{n}} will be extracted if necessary from an SCCS
3798: file named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}. The
3799: precise command used is @samp{$(GET) $(GFLAGS)}.
3800:
3801: We recommend that you avoid the use of SCCS. RCS is widely held to be
3802: superior, and is also free. By choosing free software in place of
3803: comparable (or lesser) proprietary software, you support the free software
3804: movement.
3805: @end table
3806:
3807: @node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit
3808: @section Variables Used by Implicit Rules
3809: @cindex flags for compilers
3810:
3811: The commands in built-in implicit rules make liberal use of certain
3812: predefined variables. You can redefine these variables, either in the
3813: makefile or with arguments to @code{make}, to alter how the implicit rules
3814: work without actually redefining them.
3815:
3816: For example, the command used to compile a C source file actually says
3817: @samp{$(CC) -c $(CFLAGS)}. The default values of the variables used
3818: are @samp{cc} and nothing, resulting in the command @samp{cc -c}. By
3819: redefining @samp{$(CC)} to @samp{ncc}, you could cause @samp{ncc} to
3820: be used for all C compilations performed by the implicit rule. By
3821: redefining @samp{$(CFLAGS)} to be @samp{-g}, you could pass the
3822: @samp{-g} option to each compilation. @emph{All} implicit rules that
3823: do C compilation use @samp{$(CC)} to get the program name for the
3824: compiler and @emph{all} include @samp{$(CFLAGS)} among the arguments
3825: given to the compiler.@refill
3826:
3827: The variables used in implicit rules fall into two classes: those that are
3828: names of programs (like @code{CC}) and those that contain arguments for the
3829: programs (like @code{CFLAGS}). (The ``name of a program'' may also contain
3830: some command arguments, but it must start with an actual executable program
3831: name.) If a variable value contains more than one argument, separate them
3832: with spaces.
3833:
3834: Here is a table of variables used as names of programs:
3835:
3836: @table @code
3837: @item AS
3838: @vindex AS
3839: Program for doing assembly; default @samp{as}.
3840:
3841: @item CC
3842: @vindex CC
3843: Program for compiling C programs; default @samp{cc}.
3844:
3845: @item CO
3846: @vindex CO
3847: Program for extracting a file from RCS; default @samp{co}.
3848:
3849: @item FC
3850: @vindex FC
3851: Program for compiling or preprocessing Fortran, Ratfor,
3852: and EFL programs; default @samp{f77}.
3853:
3854: @item GET
3855: @vindex GET
3856: Program for extracting a file from SCCS; default @samp{get}.
3857:
3858: @item LEX
3859: @vindex LEX
3860: Program to use to turn Lex grammars into C programs or Ratfor programs;
3861: default @samp{lex}.
3862:
3863: @item PC
3864: @vindex PC
3865: Program for compiling Pascal programs; default @samp{pc}.
3866:
3867: @item YACC
3868: @vindex YACC
3869: Program to use to turn Yacc grammars into C programs; default @samp{yacc}.
3870:
3871: @item YACCR
3872: @vindex YACCR
3873: Program to use to turn Yacc grammars into Ratfor
3874: programs; default @samp{yacc -r}.
3875:
3876: @item YACCE
3877: @vindex YACCE
3878: Program to use to turn Yacc grammars into EFL
3879: programs; default @samp{yacc -e}.
3880:
3881: @item RANLIB
3882: @vindex RANLIB
3883: Program to use to update the symbol-directory of an archive
3884: (the @file{__.SYMDEF} member); default @samp{ranlib}.
3885: @end table
3886:
3887: Here is a table of variables whose values are additional arguments for the
3888: programs above. The default values for all of these is the empty string.
3889:
3890: @table @code
3891: @item ASFLAGS
3892: @vindex ASFLAGS
3893: Extra flags to give to the assembler (when explicitly
3894: invoked on a @samp{.s} file).
3895:
3896: @item CFLAGS
3897: @vindex CFLAGS
3898: Extra flags to give to the C compiler.
3899:
3900: @item EFLAGS
3901: @vindex EFLAGS
3902: Extra flags to give to the Fortran compiler for EFL programs.
3903:
3904: @item FFLAGS
3905: @vindex FFLAGS
3906: Extra flags to give to the Fortran compiler.
3907:
3908: @item LFLAGS
3909: @vindex LFLAGS
3910: Extra flags to give to Lex.
3911:
3912: @item LDFLAGS
3913: @vindex LDFLAGS
3914: Extra flags to give to compilers when they are supposed to invoke the
3915: linker, @samp{ld} (actually the value of the variable @code{LD}).
3916:
3917: @item PFLAGS
3918: @vindex PFLAGS
3919: Extra flags to give to the Pascal compiler.
3920:
3921: @item RFLAGS
3922: @vindex RFLAGS
3923: Extra flags to give to the Fortran compiler for Ratfor programs.
3924:
3925: @item YFLAGS
3926: @vindex YFLAGS
3927: Extra flags to give to Yacc.
3928: @end table
3929:
3930: @node Chained Rules, Pattern Rules, Implicit Variables, Implicit
3931: @section Chains of Implicit Rules
3932:
3933: @cindex chains of rules
3934: Sometimes a file can be made by a sequence of implicit rules. For example,
3935: a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running
3936: first Yacc and then @code{cc}. Such a sequence is called a @dfn{chain}.
3937:
3938: If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no
3939: special searching is required: @code{make} finds that the object file can
3940: be made by C compilation from @file{@var{n}.c}; later on, when considering
3941: how to make @file{@var{n}.c}, the rule for running Yacc will be
3942: used. Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are
3943: updated.@refill
3944:
3945: @cindex intermediate file
3946: However, even if @file{@var{n}.c} does not exist and is not mentioned,
3947: @code{make} knows how to envision it as the missing link between
3948: @file{@var{n}.o} and @file{@var{n}.y}! In this case, @file{@var{n}.c} is
3949: called an @dfn{intermediate file}. Once @code{make} has decided to use the
3950: intermediate file, it is entered in the data base as if it had been
3951: mentioned in the makefile, along with the implicit rule that says how to
3952: create it.@refill
3953:
3954: Intermediate files are remade using their rules just like all other
3955: files. The difference is that the intermediate file is deleted when
3956: @code{make} is finished. Therefore, the intermediate file which did
3957: not exist before @code{make} also does not exist after @code{make}.
3958: The deletion is reported to you by printing a @samp{rm -f} command
3959: that shows what @code{make} is doing. (You can optionally define an
3960: implicit rule so as to preserve certain intermediate files. You can also
3961: list the target pattern of an implicit rule (such as @samp{%.o}) as a
3962: dependency file of the special target @code{.PRECIOUS} to preserve intermediate
3963: files whose target patterns match that file's name.)@refill
3964:
3965: A chain can involve more than two implicit rules. For example, it is
3966: possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS,
3967: Yacc and @code{cc}. Then both @file{foo.y} and @file{foo.c} are
3968: intermediate files that are deleted at the end.@refill
3969:
3970: No single implicit rule can appear more than once in a chain. This means
3971: that @code{make} will not even consider such a ridiculous thing as making
3972: @file{foo} from @file{foo.o.o} by running the linker twice. This
3973: constraint has the added benefit of preventing any infinite loop in the
3974: search for an implicit rule chain.
3975:
3976: There are some special implicit rules to optimize certain cases that would
3977: otherwise by handled by rule chains. For example, making @file{foo} from
3978: @file{foo.c} could be handled by compiling and linking with separate rules,
3979: using @file{foo.o} as an intermediate file. But what actually happens is
3980: that a special rule for this case does the compilation and linking with a
3981: single @code{cc} command. The optimized rule is used in preference to the
3982: step-by-step chain because it comes earlier in the ordering of rules.
3983:
3984: @node Pattern Rules, Last Resort, Chained Rules, Implicit
3985: @section Defining and Redefining Pattern Rules
3986:
3987: @cindex pattern rule
3988: You define an implicit rule by writing a @dfn{pattern rule}. A pattern
3989: rule looks like an ordinary rule, except that its target contains the
3990: character @samp{%} (exactly one of them). The target is considered a
3991: pattern for matching file names; the @samp{%} can match any substring,
3992: while other characters match only themselves.
3993:
3994: For example, @samp{%.c} as a pattern matches any file name that ends in
3995: @samp{.c}. @samp{s.%.c} as a pattern matches any file name that starts
3996: with @samp{s.}, ends in @samp{.c} and is at least five characters long.
3997: (There must be at least one character to match the @samp{%}.) The substring
3998: that the @samp{%} matches is called the @dfn{stem}.@refill
3999:
4000: A pattern rule must have at least one dependency that uses @samp{%}.
4001: @samp{%} in a dependency of a pattern rule stands for the same stem
4002: that was matched by the @samp{%} in the target. In order for
4003: the pattern rule to apply, its target pattern must match the file name
4004: under consideration, and its dependency patterns must name files that
4005: exist or can be made. These files become dependencies of the target.
4006:
4007: There may also be dependencies that do not use @samp{%}; such a dependency
4008: attaches to every file made by this pattern rule. These unvarying
4009: dependencies are rarely useful.
4010:
4011: The order in which pattern rules appear in the makefile is important
4012: because the rules are considered in that order. Of equally applicable
4013: rules, the first one found is used. The rules you write take precedence
4014: over those that are built in. Note, however, that a rule whose
4015: dependencies actually exist or are mentioned always takes priority over a
4016: rule with dependencies that must be made by chaining other implicit rules.
4017:
4018: @menu
4019: * Examples: Pattern Examples. Real examples of pattern rule definitions.
4020:
4021: * Vars: Automatic. The automatic variables enable the commands
4022: in pattern rules to act on the right files.
4023:
4024: * Matching: Pattern Match. Details of how patterns match.
4025:
4026: * Match-Anything Rules:: Precautions in defining a rules that can
4027: match any target file whatever.
4028:
4029: * Canceling Rules:: Overriding or canceling built-in rules.
4030:
4031: * Last Resort:: How to define a last-resort rule
4032: that applies to any target that no other
4033: rule applies to.
4034:
4035: * Suffix Rules:: The old-fashioned way to define implicit rules.
4036: @end menu
4037:
4038: @node Pattern Examples, Automatic, Pattern Rules, Pattern Rules
4039: @subsection Pattern Rule Examples
4040:
4041: Here are some examples of pattern rules actually predefined in
4042: @code{make}. First, the rule that compiles @samp{.c} files into @samp{.o}
4043: files:@refill
4044:
4045: @example
4046: %.o : %.c
4047: $(CC) -c $(CFLAGS) $< -o $@@
4048: @end example
4049:
4050: @noindent
4051: defines a rule that can make any file @file{@var{x}.o} from
4052: @file{@var{x}.c}. The command uses the automatic variables @samp{$@@} and
4053: @samp{$<} to substitute the names of the target file and the source file
4054: as they are in each case where the rule apply (@pxref{Automatic}).@refill
4055:
4056: Here is a second built-in rule:
4057:
4058: @example
4059: % :: RCS/%,v
4060: $(CO) $(COFLAGS) $<
4061: @end example
4062:
4063: @noindent
4064: defines a rule that can make any file @file{@var{x}} whatever from a
4065: corresponding file @file{@var{x},v} in the subdirectory @file{RCS}. Since
4066: the target is @samp{%}, this rule will apply to any file whatever, provided
4067: the appropriate dependency file exists. The double colon makes the rule
4068: @dfn{terminal}, which means that its dependency may not be an intermediate
4069: file (@pxref{Match-Anything Rules}).@refill
4070:
4071: @node Automatic, Pattern Match, Pattern Examples, Pattern Rules
4072: @subsection Automatic Variables
4073: @cindex automatic variables
4074:
4075: Suppose you are writing a pattern rule to compile a @samp{.c} file into a
4076: @samp{.o} file: how do you write the @samp{cc} command so that it operates
4077: on the right source file name? You can't write the name in the command,
4078: because the name is different each time the implicit rule is applied.
4079:
4080: What you do is use a special feature of @code{make}, the @dfn{automatic
4081: variables}. These variables have values computed afresh for each rule that
4082: is executed, based on the target and dependencies of the rule. In this
4083: example, you would use @samp{$@@} for the object file name and @samp{$<}
4084: for the source file name.
4085:
4086: Here is a table of automatic variables:
4087:
4088: @table @code
4089: @item $@@
4090: The file name of the target of the rule. If the target is an archive
4091: member, then @samp{$@@} is the name of the archive file.
4092:
4093: @item $%
4094: The target member name, when the target is an archive member. For
4095: example, if the target is @file{foo.a(bar.o)} then @samp{$%} is
4096: @file{bar.o} and @samp{$@@} is @file{foo.a}. @samp{$%} is empty
4097: when the target is not an archive member.
4098:
4099: @item $<
4100: The name of the first dependency.
4101:
4102: @item $?
4103: The names of all the dependencies that are newer than the target, with
4104: spaces between them.
4105:
4106: @item $^
4107: The names of all the dependencies, with spaces between them.
4108:
4109: @item $*
4110: The stem with which an implicit rule matches (@pxref{Pattern Match}).
4111: If the target is @file{dir/a.foo.b} and the target pattern is
4112: @file{a.%.b} then the stem is @file{dir/foo}. The stem is useful for
4113: constructing names of related files.@refill
4114: @end table
4115:
4116: @samp{$?} is useful even in explicit rules when you wish to operate on only
4117: the dependencies that have changed. For example, suppose that an archive
4118: named @file{lib} is supposed to contain copies of several object files.
4119: This rule copies just the changed object files into the archive:
4120:
4121: @example
4122: lib: foo.o bar.o lose.o win.o
4123: ar c lib $?
4124: @end example
4125:
4126: Of the variables listed above, four have values that are single file names.
4127: These four have variants that get just the file's directory name or just
4128: the file name within the directory. The variant variables' names are
4129: formed by appending @samp{D} or @samp{F}, respectively. These variants are
4130: semi-obsolete in GNU @code{make} since the functions @code{dir} and
4131: @code{notdir} can be used to get an equivalent effect (@pxref{Filename
4132: Functions}). Here is a table of the variants:@refill
4133:
4134: @table @samp
4135: @item $(@@D)
4136: The directory part of the file name of the target. If the value of
4137: @samp{$@@} is @file{dir/foo.o} then @samp{$(@@D)} is @file{dir/}.
4138: This value is @file{./} if @samp{$@@} does not contain a slash.
4139: @samp{$(@@D)} is equivalent to @samp{$(dir $@@)}.@refill
4140:
4141: @item $(@@F)
4142: The file-within-directory part of the file name of the target. If the
4143: value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is
4144: @file{foo.o}. @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}.
4145:
4146: @item $($/)
4147: The same as @code{$(@@F)}, for compatibility with some other versions
4148: of @code{make}.
4149:
4150: @item $(%D)
4151: @itemx $(%F)
4152: The directory part and the file-within-directory part of the archive
4153: member name.
4154:
4155: @item $(*D)
4156: @itemx $(*F)
4157: The directory part and the file-within-directory part of the stem;
4158: @file{dir/} in this example.
4159:
4160: @item $(<D)
4161: @itemx $(<F)
4162: The directory part and the file-within-directory part of the first
4163: implicit dependency.
4164: @end table
4165:
4166: @node Pattern Match, Match-Anything Rules, Automatic, Pattern Rules
4167: @subsection How Patterns Match
4168:
4169: @cindex stem
4170: A target pattern is composed of a @samp{%} between a prefix and a suffix,
4171: either of which may be empty. The pattern matches a file name only if the
4172: file name starts with the prefix and ends with the suffix, without overlap.
4173: The text between the prefix and the suffix is called the @dfn{stem}. Thus,
4174: when the pattern @samp{%.o} matches the file name @file{test.o}, the stem
4175: is @samp{test}. The pattern rule dependencies are turned into actual file
4176: names by substituting the stem for the character @samp{%}. Thus, if in the
4177: same example one of the dependencies is written as @samp{%.c}, it expands
4178: to @samp{test.c}.@refill
4179:
4180: When the target pattern does not contain a slash (and usually it does not),
4181: directory names in the file names are removed from the file name before it
4182: is compared with the target prefix and suffix. The directory names, along
4183: with the slash that ends them, are added back to the stem. Thus,
4184: @samp{e%t} does match the file name @file{src/eat}, with @samp{src/a} as
4185: the stem. When dependencies are turned into file names, the directories
4186: from the stem are added at the front, while the rest of the stem is
4187: substituted for the @samp{%}. The stem @samp{src/a} with a dependency
4188: pattern @samp{c%r} gives the file name @file{src/car}.@refill
4189:
4190: @node Match-Anything Rules, Canceling Rules, Pattern Match, Pattern Rules
4191: @subsection Match-Anything Pattern Rules
4192:
4193: @cindex match-anything rule
4194: @cindex terminal rule
4195: When a pattern rule's target is just @samp{%}, it matches any filename
4196: whatever. We call these rules @dfn{match-anything} rules. They are very
4197: useful, but it can take a lot of time for @code{make} to think about them,
4198: because it must consider every such rule for each file name listed either
4199: as a target or as a dependency.
4200:
4201: Suppose the makefile mentions @file{foo.c}. For this target, @code{make}
4202: would have to consider making it by linking an object file @file{foo.c.o},
4203: or by C compilation-and-linking in one step from @file{foo.c.c}, or by
4204: Pascal compilation-and-linking from @file{foo.c.p}, and many other
4205: possibilities. We know these possibilities are ridiculous since
4206: @file{foo.c} is a C source file, not an executable.@refill
4207:
4208: If @code{make} did consider these possibilities, it would ultimately reject
4209: them, because files such as @file{foo.c.o}, @file{foo.c.p}, etc. would not
4210: exist. But these possibilities are so numerous that @code{make} would run
4211: very slowly if it had to consider them.@refill
4212:
4213: To gain speed, we have put various constraints on the way @code{make}
4214: considers match-anything rules. There are two different constraints that
4215: can be applied, and each time you define a match-anything rule you must
4216: choose one or the other for that rule.
4217:
4218: One choice is to mark the match-anything rule as @dfn{terminal} by defining
4219: it with a double colon. When a rule is terminal, it does not apply
4220: unless its dependencies actually exist. Dependencies that could be made
4221: with other implicit rules are not good enough.
4222:
4223: For example, the built-in implicit rules for extracting sources from RCS
4224: and SCCS files are terminal; as a result, if the file @file{foo.c,v} does
4225: not exist, @code{make} will not even consider trying to make it as an
4226: intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}.
4227: RCS and SCCS files are generally ultimate source files, which should not be
4228: remade from any other files; therefore, @code{make} can save time by not
4229: looking for ways to remake them.@refill
4230:
4231: If you do not mark the match-anything rule as terminal, then it is
4232: nonterminal. A nonterminal match-anything rule cannot apply to a file name
4233: that indicates a specific type of data. A file name indicates a specific
4234: type of data if some non-match-anything implicit rule target matches it.
4235:
4236: For example, the file name @file{foo.c} matches the target for the pattern
4237: rule @samp{%.c : %.y} (the rule to run Yacc). Regardless of whether this
4238: rule is actually applicable (which happens only if there is a file
4239: @file{foo.y}), the fact that its target matches is enough to prevent
4240: consideration of any nonterminal match-everything rules for the file
4241: @file{foo.c}. Thus, @code{make} will not even consider trying to make
4242: @file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c},
4243: @file{foo.c.p}, etc.@refill
4244:
4245: The motivation for this constraint is that nonterminal match-everything
4246: rules are used for making files containing specific types of data (such as
4247: executable files) and a file name with a recognized suffix indicates a
4248: specific different type of data (such as a C source file).
4249:
4250: Special built-in dummy pattern rules are provided solely to recognize
4251: certain file names so that nonterminal match-everything rules won't be
4252: considered. These dummy rules have no dependencies and no commands, and
4253: they are ignored for all other purposes. For example, the built-in
4254: implicit rule
4255:
4256: @example
4257: %.p :
4258: @end example
4259:
4260: @noindent
4261: exists to make sure that Pascal source files such as @file{foo.p} match a
4262: specific target pattern and thereby prevent time from being wasted looking
4263: for @file{foo.p.o} or @file{foo.p.c}.
4264:
4265: @node Canceling Rules,, Match-Anything Rules, Pattern Rules
4266: @subsection Canceling Implicit Rules
4267:
4268: You can override a built-in implicit rule by defining a new pattern rule
4269: with the same target and dependencies, but different commands. When the
4270: new rule is defined, the built-in one is replaced. The new rule's position
4271: in the sequence of implicit rules is determined by where you write the new
4272: rule.
4273:
4274: You can cancel a built-in implicit rule by defining a pattern rule with the
4275: same target and dependencies, but no commands. For example, the following
4276: would cancel the rule that runs the assembler:
4277:
4278: @example
4279: %.o : %.s
4280: @end example
4281:
4282: @node Last Resort, Suffix Rules, Pattern Rules, Implicit
4283: @section Defining Last-Resort Default Rules
4284:
4285: @findex .DEFAULT
4286: You can define a last-resort implicit rule by writing a rule for the target
4287: @code{.DEFAULT}. Such a rule's commands are used for all targets and
4288: dependencies that have no commands of their own and for which no other
4289: implicit rule applies. Naturally, there is no @code{.DEFAULT} rule unless
4290: you write one.
4291:
4292: For example, when testing a makefile, you might not care if the source
4293: files contain real data, only that they exist. Then you might do this:
4294:
4295: @example
4296: .DEFAULT:
4297: touch $@@
4298: @end example
4299:
4300: @noindent
4301: to cause all the source files needed (as dependencies) to be created
4302: silently.
4303:
4304: @node Suffix Rules, Search Algorithm, Last Resort, Implicit
4305: @section Old-Fashioned Suffix Rules
4306: @cindex suffix rules
4307:
4308: @dfn{Suffix rules} are the old-fashioned way of defining implicit rules for
4309: @code{make}. Suffix rules are obsolete because pattern rules are more
4310: general and clearer. They are supported in GNU @code{make} for
4311: compatibility with old makefiles. They come in two kinds:
4312: @dfn{double-suffix} and @dfn{single-suffix}.@refill
4313:
4314: A double-suffix rule is defined by a pair of suffixes: the target suffix
4315: and the source suffix. It matches any file whose name ends with the target
4316: suffix. The corresponding implicit dependency is to the file name made by
4317: replacing the target suffix with the source suffix. A two-suffix rule
4318: whose target and source suffixes are @samp{.o} and @samp{.c} is equivalent
4319: to the pattern rule @samp{%.o : %.c}.
4320:
4321: A single-suffix rule is defined by a single suffix, which is the source
4322: suffix. It matches any file name, and the corresponding implicit
4323: dependency name is made by appending the source suffix. A single-suffix
4324: rule whose source suffix is @samp{.c} is equivalent to the pattern rule
4325: @samp{% : %.c}.
4326:
4327: Suffix rule definitions are recognized by comparing each rule's target
4328: against a defined list of known suffixes. When @code{make} sees a rule
4329: whose target is a known suffix, this rule is considered a single-suffix
4330: rule. When @code{make} sees a rule whose target is two known suffixes
4331: concatenated, this rule is taken as a double-suffix rule.
4332:
4333: For example, @samp{.c} and @samp{.o} are both on the default list of known
4334: suffixes. Therefore, if you define a rule whose target is @samp{.c.o},
4335: @code{make} takes it to be a double-suffix rule with source suffix
4336: @samp{.c} and target suffix @samp{.o}. For example, here is the old
4337: fashioned way to define the rule for compiling a C source:@refill
4338:
4339: @example
4340: .c.o:
4341: $(CC) -c $(CFLAGS) -o $@@ $<
4342: @end example
4343:
4344: @findex .SUFFIXES
4345: The known suffixes are simply the names of the dependencies of the special
4346: target @code{.SUFFIXES}. You can add your own suffixes by writing a rule
4347: for @code{.SUFFIXES} that adds more dependencies, as in
4348:
4349: @example
4350: .SUFFIXES: .hack .win
4351: @end example
4352:
4353: @noindent
4354: which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes.
4355:
4356: If you wish to eliminate the default known suffixes instead of just adding
4357: to them, write a rule for @code{.SUFFIXES} with no dependencies. By
4358: special dispensation, this eliminates all existing dependencies of
4359: @code{.SUFFIXES}. You can then write another rule to add the suffixes you
4360: want. For example,
4361:
4362: @example
4363: .SUFFIXES: # @r{Delete the default suffixes}
4364: .SUFFIXES: .c .o .h # @r{Define our suffix list}
4365: @end example
4366:
4367: The @samp{-r} flag causes the default list of suffixes to be empty.
4368:
4369: @node Search Algorithm,, Last Resort, Implicit
4370: @section Implicit Rule Search Algorithm
4371:
4372: Here is the procedure @code{make} uses for searching for an implicit rule
4373: for a target @var{t}. This procedure is followed for each double-colon
4374: rule with no commands, for each target of ordinary rules none of which have
4375: commands, and for each dependency that is not the target of any rule. It
4376: is also followed recursively for dependencies that come from implicit
4377: rules, in the search for a chain of rules.
4378:
4379: Suffix rules are not mentioned in this algorithm because suffix rules are
4380: converted to equivalent pattern rules after the makefiles have been read
4381: in.
4382:
4383: For an archive member target of the form
4384: @samp{@var{archive}(@var{member})}, the following algorithm is run twice,
4385: first using @samp{(@var{member})} as the target @var{t}, and second using
4386: the entire target if the first run found no rule.@refill
4387:
4388: @enumerate
4389: @item
4390: Split @var{t} into a directory part, called @var{d}, and the rest,
4391: called @var{n}. For example, if @var{t} is @samp{src/foo.o}, then
4392: @var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill
4393:
4394: @item
4395: Make a list of the pattern rules whose target matches @var{t} or
4396: @var{n}. If the target pattern contains a slash, it is matched
4397: against @var{t}; otherwise, against @var{n}.
4398:
4399: @item
4400: If any rule in that list is @emph{not} a match-anything rule, then
4401: remove all nonterminal match-anything rules from the list.
4402:
4403: @item
4404: Remove any rules with no dependencies from the list.
4405:
4406: @item
4407: For each pattern rule in the list:
4408:
4409: @enumerate
4410: @item
4411: Find the stem @var{s}: the part of @var{t} or @var{n} that the
4412: @samp{%} in the target pattern matches.@refill
4413:
4414: @item
4415: Compute the dependency names by substituting @var{s} for @samp{%}; if
4416: the target pattern does not contain a slash, @var{d} is appended to
4417: the front of each dependency name.
4418:
4419: @item
4420: Test whether all the dependencies exist or ought to exist. (If a
4421: file name mentioned in the makefile as a target or as an explicit
4422: dependency then we say it ought to exist.)
4423:
4424: If all dependencies exist or ought to exist, then this rule applies.
4425: @end enumerate
4426:
4427: @item
4428: If no pattern rule has been found so far, try harder. For
4429: each pattern rule in the list:
4430:
4431: @enumerate
4432: @item
4433: If the rule is a terminal match-anything rule, ignore it and go
4434: on to the next rule.
4435:
4436: @item
4437: Compute the dependency names as before.
4438:
4439: @item
4440: Test whether all the dependencies exist or ought to exist.
4441:
4442: @item
4443: For each dependency that does not exist, follow this algorithm
4444: recursively to see if the dependency can be made by an implicit
4445: rule.
4446:
4447: @item
4448: If all dependencies exist, ought to exist, or can be made by
4449: implicit rules, then this rule applies.
4450: @end enumerate
4451:
4452: @item
4453: If no rule has been found so far, this target cannot be made by an
4454: implicit rule. Return failure.
4455:
4456: @item
4457: If no implicit rule applies, the rule for @code{.DEFAULT}, if any,
4458: applies. In that case, give @var{t} the same commands that
4459: @code{.DEFAULT} has. Otherwise, there are no commands for @var{t}.
4460: @end enumerate
4461:
4462: When the commands of a pattern rule are executed for @var{t}, the automatic
4463: variables @samp{$@@}, @samp{$*} and @samp{$<} are set as follows:
4464:
4465: @table @samp
4466: @item $@@
4467: @var{t}
4468: @item $*
4469: If the target pattern contains a slash, this is @var{s}; otherwise, it
4470: is @var{d}@var{s}.
4471: @item $<
4472: The name of the first dependency that came via the implicit rule.
4473: @end table
4474:
4475: For @code{.DEFAULT} commands, as for non-implicit commands, @samp{$*}
4476: and @samp{$<} are empty. @samp{$@@} is @var{t}, as always.
4477:
4478: @node Archives, Features, Implicit, Top
4479: @chapter Using @code{make} to Update Archive Files
4480: @cindex archive
4481:
4482: @dfn{Archive files} are files containing named subfiles called
4483: @dfn{members}; they are maintained with the program @code{ar} and their
4484: main use is as subroutine libraries for linking.
4485:
4486: @menu
4487: * Members: Archive Members. How to name an archive member
4488: as a target or dependency.
4489: * Update: Archive Update. An implicit rule can update
4490: most archive member targets just right.
4491: * Symbols: Archive Symbols. Another implicit rule runs @code{ranlib}
4492: to update the special member @file{__.SYMDEF}.
4493: @end menu
4494:
4495: @node Archive Members, Archive Update, Archives, Archives
4496: @section Archive Members as Targets
4497: @cindex archive member targets
4498:
4499: An individual member of an archive file can be used as a target or
4500: dependency in @code{make}. The archive file must already exist, but the
4501: member need not exist. You specify the member named @var{member} in
4502: archive file @var{archive} as follows:
4503:
4504: @example
4505: @var{archive}(@var{member})
4506: @end example
4507:
4508: @noindent
4509: This construct is available only in targets and dependencies, not in
4510: commands! Most programs that you might use in commands do not support this
4511: syntax and cannot act directly on archive members. Only @code{ar} and
4512: other programs specifically designed to operate on archives can do so.
4513: Therefore, valid commands to update an archive member target probably must
4514: use @code{ar}. For example, this rule says to create a member
4515: @file{hack.o} in archive @file{foolib} by copying the file @file{hack.o}:
4516:
4517: @example
4518: foolib(hack.o) : hack.o
4519: ar r foolib hack.o
4520: @end example
4521:
4522: In fact, nearly all archive member targets are updated in just this way
4523: and there is an implicit rule to do it for you.
4524:
4525: @node Archive Update, Archive Symbols, Archive Members, Archives
4526: @section Implicit Rule for Archive Member Targets
4527:
4528: Recall that a target that looks like @file{@var{a}(@var{m})} stands for the
4529: member named @var{m} in the archive file @var{a}.
4530:
4531: When @code{make} looks for an implicit rule for such a target, as a special
4532: feature it considers implicit rules that match @file{(@var{m})}, as well as
4533: those that match the actual target @file{@var{a}(@var{m})}.
4534:
4535: This causes one special rule whose target is @file{(%)} to match. This
4536: rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m}
4537: into the archive. For example, it will update the archive member target
4538: @file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the
4539: archive @file{foo.a} as a member named @file{bar.o}.
4540:
4541: When this rule is chained with others, the result is very powerful. Thus,
4542: @samp{make "foo.a(bar.o)"} in the presence of a file @file{bar.c} is enough
4543: to cause the following commands to be run, even without a makefile:
4544:
4545: @example
4546: cc -c bar.c -o bar.o
4547: ar r foo.a bar.o
4548: rm -f bar.o
4549: @end example
4550:
4551: @noindent
4552: Here the file @file{bar.o} has been envisioned as an intermediate file.
4553:
4554: @node Archive Symbols,, Archive Update, Archives
4555: @subsection Updating Archive Symbol Directories
4556: @cindex __.SYMDEF
4557:
4558: An archive file that is used as a library usually contains a special member
4559: named @file{__.SYMDEF} that contains a directory of the external symbol
4560: names defined by all the other members. After you update any other
4561: members, you need to update @file{__.SYMDEF} so that it will summarize the
4562: other members properly. This is done by running the @code{ranlib} program:
4563:
4564: @example
4565: ranlib @var{archivefile}
4566: @end example
4567:
4568: Normally you would put this command in the rule for the archive file,
4569: and make all the members of the archive file dependents of that rule.
4570: For example,
4571:
4572: @example
4573: libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{}
4574: ranlib libfoo.a
4575: @end example
4576:
4577: @noindent
4578: The effect of this is to update archive members @file{x.o}, @file{y.o},
4579: etc., and then update the symbol directory member @file{__.SYMDEF} by
4580: running @code{ranlib}. The rules for updating the members are not shown
4581: here; most likely you can omit them and use the implicit rule which copies
4582: files into the archive, as described in the preceding section.
4583:
4584: @node Features, Missing, Archives, Top
4585: @chapter Features of GNU @code{make}
4586:
4587: Here is a summary of the features of GNU @code{make}, for comparison
4588: with and credit to other versions of @code{make}. We consider the features
4589: of @code{make} in BSD 4.2 systems as a baseline.
4590:
4591: Many features come from the version of @code{make} in System V:
4592:
4593: @itemize @bullet
4594: @item
4595: The @code{VPATH} variable and its special meaning. @xref{Directory
4596: Search}. This feature exists in System V @code{make}, but is undocumented.
4597: It is documented in 4.3 BSD @code{make} (which says it mimics System V's
4598: @code{VPATH} feature).@refill
4599:
4600: @item
4601: Included makefiles. @xref{Include}.
4602:
4603: @item
4604: Variables are read from and communicated via the environment.
4605: @xref{Environment}.
4606:
4607: @item
4608: Options passed through the variable @code{MAKEFLAGS} to recursive
4609: invocations of @code{make}. @xref{Options/Recursion}.
4610:
4611: @item
4612: The automatic variable @code{$%} is set to the member name
4613: in an archive reference. @xref{Automatic}.
4614:
4615: @item
4616: The automatic variables @code{$@@}, @code{$*}, @code{$<} and @code{$%}
4617: have corresponding forms like @code{$(@@F)} and @code{$(@@D)}.
4618: @xref{Automatic}.@refill
4619:
4620: @item
4621: Substitution variable references. @xref{Reference}.
4622:
4623: @item
4624: The command-line options @samp{-b} and @samp{-m}, accepted and ignored.
4625:
4626: @item
4627: Execution of recursive commands to run @code{make} via the variable
4628: @code{MAKE} even if @samp{-n}, @samp{-q} or @samp{-t} is specified.
4629: @xref{Recursion}.
4630:
4631: @item
4632: Support for suffix @samp{.a} in suffix rules. In GNU @code{make},
4633: this is actually implemented by changing with one pattern rule for
4634: installing members in an archive. @xref{Chained Rules}.@refill
4635:
4636: @item
4637: The arrangement of lines and backslash-newline combinations in
4638: commands is retained when the commands are printed, so they appear as
4639: they do in the makefile, except for the stripping of initial
4640: whitespace.
4641: @end itemize
4642:
4643: Some features were inspired by a version of @code{make} whose identity we
4644: don't recall:
4645:
4646: @itemize @bullet
4647: @item
4648: Pattern rules using @samp{%}. @xref{Pattern Rules}.
4649:
4650: @item
4651: The automatic variable @code{$^} containing a list of all dependencies
4652: of the current target. @xref{Automatic}.
4653: @end itemize
4654:
4655: The remaining features are inventions new in GNU @code{make}:
4656:
4657: @itemize @bullet
4658: @item
4659: The @samp{-v} option to print version and copyright information.
4660:
4661: @item
4662: Simply-expanded variables. @xref{Flavors}.
4663:
4664: @item
4665: Passing command-line variable assignments automatically through the
4666: variable @code{MAKE} to recursive @code{make} invocations.
4667: @xref{Recursion}.
4668:
4669: @item
4670: The @samp{-c} command option to change directory. @xref{Options}.
4671:
4672: @item
4673: Verbatim variable definitions made with @code{define}. @xref{Defining}.
4674:
4675: @item
4676: Phony targets declared with the special target @code{.PHONY}.
4677: @xref{Phony Targets}.
4678:
4679: @item
4680: Text manipulation by calling functions. @xref{Functions}.
4681:
4682: @item
4683: The @samp{-o} option to pretend a file's modification-time is old.
4684: @xref{Avoid Compilation}.
4685:
4686: @item
4687: Conditional execution. @xref{Conditionals}.
4688:
4689: @item
4690: Included makefiles never determine the default goal.
4691:
4692: @item
4693: The included makefile search path. @xref{Include}.
4694:
4695: @item
4696: Specifying extra makefiles to read. @xref{MAKEFILES Variable}.
4697:
4698: @item
4699: Stripping leading sequences of @samp{./} from file names, so that
4700: @file{./@var{file}} and @file{@var{file}} are considered to be the
4701: same file.
4702:
4703: @item
4704: Special search method for library dependencies written in the form
4705: @samp{-l@var{name}}. @xref{Libraries/Search}.
4706:
4707: @item
4708: Allowing suffixes for suffix rules (@pxref{Suffix Rules}) to contain
4709: any characters. In other version of @code{make}, they must begin with
4710: @samp{.} and not contain any @samp{/} characters.
4711:
4712: @item
4713: The variable @code{MAKELEVEL} which keeps track of the current level
4714: of @code{make} recursion. @xref{Recursion}.
4715:
4716: @item
4717: Rule chaining and implicit intermediate files. @xref{Chained Rules}.
4718:
4719: @item
4720: Static pattern rules. @xref{Static Pattern}.
4721:
4722: @item
4723: Selective @code{vpath} search. @xref{Directory Search}.
4724:
4725: @item
4726: Recursive variable references. @xref{Reference}.
4727: @end itemize
4728:
4729: @node Missing, Concept Index, Features, Top
4730: @chapter Missing Features in GNU @code{make}
4731:
4732: The @code{make} programs in various other systems support a few features
4733: that are not implemented in GNU @code{make}.
4734:
4735: @itemize @bullet
4736: @item
4737: A target of the form @samp{@var{file}((@var{entry}))} stands for a member
4738: of archive file @var{file}. The member is chosen, not by name, but by
4739: being an object file which defines the linker symbol @var{entry}.@refill
4740:
4741: This feature was not put into GNU @code{make} because of the
4742: nonmodularity of putting knowledge into @code{make} of the internal
4743: format of archive file symbol directories. @xref{Archive Symbols}.
4744:
4745: @item
4746: Suffixes (used in suffix rules) that end with the character @samp{~}
4747: have a special meaning; they refer to the SCCS file that corresponds
4748: to the file one would get without the @samp{~}. For example, the
4749: suffix rule @samp{.c~.o} would make the file @file{@var{n}.o} file from
4750: the SCCS file @file{s.@var{n}.c}. For complete coverage, a whole
4751: series of such suffix rules is required. @xref{Suffix Rules}.@refill
4752:
4753: In GNU @code{make}, this entire series of cases is handled by two
4754: pattern rules for extraction from SCCS, in combination with the
4755: general feature of rule chaining. @xref{Chained Rules}.
4756:
4757: @item
4758: In System V @code{make}, the string @samp{$$@@} has the strange meaning
4759: that, in the dependencies of a rule with multiple targets, it stands
4760: for the particular target that is being processed.
4761:
4762: This is not defined in GNU @code{make} because @samp{$$} should always
4763: stand for an ordinary @samp{$}.
4764:
4765: It is possible to get this functionality through the use of static pattern
4766: rules (@pxref{Static Pattern}). The System V @code{make} rule:
4767:
4768: @example
4769: $(targets): $$@@.o lib.a
4770: @end example
4771:
4772: @noindent
4773: can be replaced with the GNU @code{make} static pattern rule:
4774:
4775: @example
4776: $(targets): %: %.o lib.a
4777: @end example
4778:
4779: @item
4780: In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search
4781: (@pxref{Directory Search}) have their names changed inside command strings.
4782: We feel it is much cleaner to always use automatic variables and thus
4783: obviate the need for this feature. We are still debating whether to
4784: implement this for the sake of compatibility or to leave it out to avoid
4785: such terrible ugliness.@refill
4786: @end itemize
4787:
4788: @node Concept Index, Name Index, Missing, Top
4789: @unnumbered Index of Concepts
4790:
4791: @printindex cp
4792:
4793: @node Name Index,, Concept Index, Top
4794: @unnumbered Index of Functions, Directives and Variables
4795:
4796: @printindex fn
4797:
4798: @contents
4799: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.