1\input texinfo @c -*- Texinfo -*- 2@c %**start of header 3@setfilename make.info 4 5@include version.texi 6@set EDITION 0.70 7@set RCSID $Id: make.texi,v 1.45 2006/04/01 06:36:40 psmith Exp $ 8 9@settitle GNU @code{make} 10@setchapternewpage odd 11@c Combine the variable and function indices: 12@syncodeindex vr fn 13@c Combine the program and concept indices: 14@syncodeindex pg cp 15@c FSF publishers: format makebook.texi instead of using this file directly. 16@c ISBN provided by Lisa M. Opus Goldstein <opus@gnu.org>, 5 May 2004 17@set ISBN 1-882114-83-5 18@c %**end of header 19 20@copying 21This file documents the GNU @code{make} utility, which determines 22automatically which pieces of a large program need to be recompiled, 23and issues the commands to recompile them. 24 25This is Edition @value{EDITION}, last updated @value{UPDATED}, 26of @cite{The GNU Make Manual}, for GNU @code{make} version @value{VERSION}. 27 28Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 291996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006 30Free Software Foundation, Inc. 31 32@quotation 33Permission is granted to copy, distribute and/or modify this document 34under the terms of the GNU Free Documentation License, Version 1.2 or 35any later version published by the Free Software Foundation; with no 36Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' 37and with the Back-Cover Texts as in (a) below. A copy of the 38license is included in the section entitled ``GNU Free Documentation 39License.'' 40 41(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify 42this GNU Manual, like GNU software. Copies published by the Free 43Software Foundation raise funds for GNU development.'' 44@end quotation 45@end copying 46 47@c finalout 48 49@c ISPELL CHECK: done, 10 June 1993 --roland 50@c ISPELL CHECK: done, 2000-06-25 --Martin Buchholz 51 52 53@dircategory GNU Packages 54@direntry 55* Make: (make). Remake files automatically. 56@end direntry 57 58@iftex 59@shorttitlepage GNU Make 60@end iftex 61@titlepage 62@title GNU Make 63@subtitle A Program for Directing Recompilation 64@subtitle GNU @code{make} Version @value{VERSION} 65@subtitle @value{UPDATED-MONTH} 66@author Richard M. Stallman, Roland McGrath, Paul D. Smith 67@page 68@vskip 0pt plus 1filll 69@insertcopying 70@sp 2 71Published by the Free Software Foundation @* 7251 Franklin St. -- Fifth Floor @* 73Boston, MA 02110-1301 USA @* 74ISBN @value{ISBN} @* 75@sp 2 76Cover art by Etienne Suvasa. 77@end titlepage 78 79@summarycontents 80@contents 81 82@ifnottex 83@node Top, Overview, (dir), (dir) 84@top GNU @code{make} 85 86@insertcopying 87@end ifnottex 88 89@menu 90* Overview:: Overview of @code{make}. 91* Introduction:: An introduction to @code{make}. 92* Makefiles:: Makefiles tell @code{make} what to do. 93* Rules:: Rules describe when a file must be remade. 94* Commands:: Commands say how to remake a file. 95* Using Variables:: You can use variables to avoid repetition. 96* Conditionals:: Use or ignore parts of the makefile based 97 on the values of variables. 98* Functions:: Many powerful ways to manipulate text. 99* Invoking make: Running. How to invoke @code{make} on the command line. 100* Implicit Rules:: Use implicit rules to treat many files alike, 101 based on their file names. 102* Archives:: How @code{make} can update library archives. 103* Features:: Features GNU @code{make} has over other @code{make}s. 104* Missing:: What GNU @code{make} lacks from other @code{make}s. 105* Makefile Conventions:: Conventions for writing makefiles for 106 GNU programs. 107* Quick Reference:: A quick reference for experienced users. 108* Error Messages:: A list of common errors generated by @code{make}. 109* Complex Makefile:: A real example of a straightforward, 110 but nontrivial, makefile. 111 112* GNU Free Documentation License:: License for copying this manual 113* Concept Index:: Index of Concepts 114* Name Index:: Index of Functions, Variables, & Directives 115 116@detailmenu 117 --- The Detailed Node Listing --- 118 119Overview of @code{make} 120 121* Preparing:: Preparing and Running Make 122* Reading:: On Reading this Text 123* Bugs:: Problems and Bugs 124 125An Introduction to Makefiles 126 127* Rule Introduction:: What a rule looks like. 128* Simple Makefile:: A Simple Makefile 129* How Make Works:: How @code{make} Processes This Makefile 130* Variables Simplify:: Variables Make Makefiles Simpler 131* make Deduces:: Letting @code{make} Deduce the Commands 132* Combine By Prerequisite:: Another Style of Makefile 133* Cleanup:: Rules for Cleaning the Directory 134 135Writing Makefiles 136 137* Makefile Contents:: What makefiles contain. 138* Makefile Names:: How to name your makefile. 139* Include:: How one makefile can use another makefile. 140* MAKEFILES Variable:: The environment can specify extra makefiles. 141* MAKEFILE_LIST Variable:: Discover which makefiles have been read. 142* Special Variables:: Other special variables. 143* Remaking Makefiles:: How makefiles get remade. 144* Overriding Makefiles:: How to override part of one makefile 145 with another makefile. 146* Reading Makefiles:: How makefiles are parsed. 147* Secondary Expansion:: How and when secondary expansion is performed. 148 149Writing Rules 150 151* Rule Example:: An example explained. 152* Rule Syntax:: General syntax explained. 153* Prerequisite Types:: There are two types of prerequisites. 154* Wildcards:: Using wildcard characters such as `*'. 155* Directory Search:: Searching other directories for source files. 156* Phony Targets:: Using a target that is not a real file's name. 157* Force Targets:: You can use a target without commands 158 or prerequisites to mark other targets 159 as phony. 160* Empty Targets:: When only the date matters and the 161 files are empty. 162* Special Targets:: Targets with special built-in meanings. 163* Multiple Targets:: When to make use of several targets in a rule. 164* Multiple Rules:: How to use several rules with the same target. 165* Static Pattern:: Static pattern rules apply to multiple targets 166 and can vary the prerequisites according to 167 the target name. 168* Double-Colon:: How to use a special kind of rule to allow 169 several independent rules for one target. 170* Automatic Prerequisites:: How to automatically generate rules giving 171 prerequisites from source files themselves. 172 173Using Wildcard Characters in File Names 174 175* Wildcard Examples:: Several examples 176* Wildcard Pitfall:: Problems to avoid. 177* Wildcard Function:: How to cause wildcard expansion where 178 it does not normally take place. 179 180Searching Directories for Prerequisites 181 182* General Search:: Specifying a search path that applies 183 to every prerequisite. 184* Selective Search:: Specifying a search path 185 for a specified class of names. 186* Search Algorithm:: When and how search paths are applied. 187* Commands/Search:: How to write shell commands that work together 188 with search paths. 189* Implicit/Search:: How search paths affect implicit rules. 190* Libraries/Search:: Directory search for link libraries. 191 192Static Pattern Rules 193 194* Static Usage:: The syntax of static pattern rules. 195* Static versus Implicit:: When are they better than implicit rules? 196 197Writing the Commands in Rules 198 199* Command Syntax:: Command syntax features and pitfalls. 200* Echoing:: How to control when commands are echoed. 201* Execution:: How commands are executed. 202* Parallel:: How commands can be executed in parallel. 203* Errors:: What happens after a command execution error. 204* Interrupts:: What happens when a command is interrupted. 205* Recursion:: Invoking @code{make} from makefiles. 206* Sequences:: Defining canned sequences of commands. 207* Empty Commands:: Defining useful, do-nothing commands. 208 209Command Syntax 210 211* Splitting Lines:: Breaking long command lines for readability. 212* Variables in Commands:: Using @code{make} variables in commands. 213 214Command Execution 215 216* Choosing the Shell:: How @code{make} chooses the shell used 217 to run commands. 218 219Recursive Use of @code{make} 220 221* MAKE Variable:: The special effects of using @samp{$(MAKE)}. 222* Variables/Recursion:: How to communicate variables to a sub-@code{make}. 223* Options/Recursion:: How to communicate options to a sub-@code{make}. 224* -w Option:: How the @samp{-w} or @samp{--print-directory} option 225 helps debug use of recursive @code{make} commands. 226 227How to Use Variables 228 229* Reference:: How to use the value of a variable. 230* Flavors:: Variables come in two flavors. 231* Advanced:: Advanced features for referencing a variable. 232* Values:: All the ways variables get their values. 233* Setting:: How to set a variable in the makefile. 234* Appending:: How to append more text to the old value 235 of a variable. 236* Override Directive:: How to set a variable in the makefile even if 237 the user has set it with a command argument. 238* Defining:: An alternate way to set a variable 239 to a verbatim string. 240* Environment:: Variable values can come from the environment. 241* Target-specific:: Variable values can be defined on a per-target 242 basis. 243* Pattern-specific:: Target-specific variable values can be applied 244 to a group of targets that match a pattern. 245 246Advanced Features for Reference to Variables 247 248* Substitution Refs:: Referencing a variable with 249 substitutions on the value. 250* Computed Names:: Computing the name of the variable to refer to. 251 252Conditional Parts of Makefiles 253 254* Conditional Example:: Example of a conditional 255* Conditional Syntax:: The syntax of conditionals. 256* Testing Flags:: Conditionals that test flags. 257 258Functions for Transforming Text 259 260* Syntax of Functions:: How to write a function call. 261* Text Functions:: General-purpose text manipulation functions. 262* File Name Functions:: Functions for manipulating file names. 263* Conditional Functions:: Functions that implement conditions. 264* Foreach Function:: Repeat some text with controlled variation. 265* Call Function:: Expand a user-defined function. 266* Value Function:: Return the un-expanded value of a variable. 267* Eval Function:: Evaluate the arguments as makefile syntax. 268* Origin Function:: Find where a variable got its value. 269* Flavor Function:: Find out the flavor of a variable. 270* Shell Function:: Substitute the output of a shell command. 271* Make Control Functions:: Functions that control how make runs. 272 273How to Run @code{make} 274 275* Makefile Arguments:: How to specify which makefile to use. 276* Goals:: How to use goal arguments to specify which 277 parts of the makefile to use. 278* Instead of Execution:: How to use mode flags to specify what 279 kind of thing to do with the commands 280 in the makefile other than simply 281 execute them. 282* Avoiding Compilation:: How to avoid recompiling certain files. 283* Overriding:: How to override a variable to specify 284 an alternate compiler and other things. 285* Testing:: How to proceed past some errors, to 286 test compilation. 287* Options Summary:: Summary of Options 288 289Using Implicit Rules 290 291* Using Implicit:: How to use an existing implicit rule 292 to get the commands for updating a file. 293* Catalogue of Rules:: A list of built-in implicit rules. 294* Implicit Variables:: How to change what predefined rules do. 295* Chained Rules:: How to use a chain of implicit rules. 296* Pattern Rules:: How to define new implicit rules. 297* Last Resort:: How to define commands for rules which 298 cannot find any. 299* Suffix Rules:: The old-fashioned style of implicit rule. 300* Implicit Rule Search:: The precise algorithm for applying 301 implicit rules. 302 303Defining and Redefining Pattern Rules 304 305* Pattern Intro:: An introduction to pattern rules. 306* Pattern Examples:: Examples of pattern rules. 307* Automatic Variables:: How to use automatic variables in the 308 commands of implicit rules. 309* Pattern Match:: How patterns match. 310* Match-Anything Rules:: Precautions you should take prior to 311 defining rules that can match any 312 target file whatever. 313* Canceling Rules:: How to override or cancel built-in rules. 314 315Using @code{make} to Update Archive Files 316 317* Archive Members:: Archive members as targets. 318* Archive Update:: The implicit rule for archive member targets. 319* Archive Pitfalls:: Dangers to watch out for when using archives. 320* Archive Suffix Rules:: You can write a special kind of suffix rule 321 for updating archives. 322 323Implicit Rule for Archive Member Targets 324 325* Archive Symbols:: How to update archive symbol directories. 326 327@end detailmenu 328@end menu 329 330@node Overview, Introduction, Top, Top 331@comment node-name, next, previous, up 332@chapter Overview of @code{make} 333 334The @code{make} utility automatically determines which pieces of a large 335program need to be recompiled, and issues commands to recompile them. 336This manual describes GNU @code{make}, which was implemented by Richard 337Stallman and Roland McGrath. Development since Version 3.76 has been 338handled by Paul D. Smith. 339 340GNU @code{make} conforms to section 6.2 of @cite{IEEE Standard 3411003.2-1992} (POSIX.2). 342@cindex POSIX 343@cindex IEEE Standard 1003.2 344@cindex standards conformance 345 346Our examples show C programs, since they are most common, but you can use 347@code{make} with any programming language whose compiler can be run with a 348shell command. Indeed, @code{make} is not limited to programs. You can 349use it to describe any task where some files must be updated automatically 350from others whenever the others change. 351 352@menu 353* Preparing:: Preparing and Running Make 354* Reading:: On Reading this Text 355* Bugs:: Problems and Bugs 356@end menu 357 358@node Preparing, Reading, Overview, Overview 359@ifnottex 360@heading Preparing and Running Make 361@end ifnottex 362 363To prepare to use @code{make}, you must write a file called 364the @dfn{makefile} that describes the relationships among files 365in your program and provides commands for updating each file. 366In a program, typically, the executable file is updated from object 367files, which are in turn made by compiling source files.@refill 368 369Once a suitable makefile exists, each time you change some source files, 370this simple shell command: 371 372@example 373make 374@end example 375 376@noindent 377suffices to perform all necessary recompilations. The @code{make} program 378uses the makefile data base and the last-modification times of the files to 379decide which of the files need to be updated. For each of those files, it 380issues the commands recorded in the data base. 381 382You can provide command line arguments to @code{make} to control which 383files should be recompiled, or how. @xref{Running, ,How to Run 384@code{make}}. 385 386@node Reading, Bugs, Preparing, Overview 387@section How to Read This Manual 388 389If you are new to @code{make}, or are looking for a general 390introduction, read the first few sections of each chapter, skipping the 391later sections. In each chapter, the first few sections contain 392introductory or general information and the later sections contain 393specialized or technical information. 394@ifnottex 395The exception is the second chapter, @ref{Introduction, ,An 396Introduction to Makefiles}, all of which is introductory. 397@end ifnottex 398@iftex 399The exception is @ref{Introduction, ,An Introduction to Makefiles}, 400all of which is introductory. 401@end iftex 402 403If you are familiar with other @code{make} programs, see @ref{Features, 404,Features of GNU @code{make}}, which lists the enhancements GNU 405@code{make} has, and @ref{Missing, ,Incompatibilities and Missing 406Features}, which explains the few things GNU @code{make} lacks that 407others have. 408 409For a quick summary, see @ref{Options Summary}, @ref{Quick Reference}, 410and @ref{Special Targets}. 411 412@node Bugs, , Reading, Overview 413@section Problems and Bugs 414@cindex reporting bugs 415@cindex bugs, reporting 416@cindex problems and bugs, reporting 417 418If you have problems with GNU @code{make} or think you've found a bug, 419please report it to the developers; we cannot promise to do anything but 420we might well want to fix it. 421 422Before reporting a bug, make sure you've actually found a real bug. 423Carefully reread the documentation and see if it really says you can do 424what you're trying to do. If it's not clear whether you should be able 425to do something or not, report that too; it's a bug in the 426documentation! 427 428Before reporting a bug or trying to fix it yourself, try to isolate it 429to the smallest possible makefile that reproduces the problem. Then 430send us the makefile and the exact results @code{make} gave you, 431including any error or warning messages. Please don't paraphrase 432these messages: it's best to cut and paste them into your report. 433When generating this small makefile, be sure to not use any non-free 434or unusual tools in your commands: you can almost always emulate what 435such a tool would do with simple shell commands. Finally, be sure to 436explain what you expected to occur; this will help us decide whether 437the problem was really in the documentation. 438 439Once you have a precise problem you can report it in one of two ways. 440Either send electronic mail to: 441 442@example 443 bug-make@@gnu.org 444@end example 445 446@noindent 447or use our Web-based project management tool, at: 448 449@example 450 http://savannah.gnu.org/projects/make/ 451@end example 452 453@noindent 454In addition to the information above, please be careful to include the 455version number of @code{make} you are using. You can get this 456information with the command @samp{make --version}. Be sure also to 457include the type of machine and operating system you are using. One 458way to obtain this information is by looking at the final lines of 459output from the command @samp{make --help}. 460 461@node Introduction, Makefiles, Overview, Top 462@comment node-name, next, previous, up 463@chapter An Introduction to Makefiles 464 465You need a file called a @dfn{makefile} to tell @code{make} what to do. 466Most often, the makefile tells @code{make} how to compile and link a 467program. 468@cindex makefile 469 470In this chapter, we will discuss a simple makefile that describes how to 471compile and link a text editor which consists of eight C source files 472and three header files. The makefile can also tell @code{make} how to 473run miscellaneous commands when explicitly asked (for example, to remove 474certain files as a clean-up operation). To see a more complex example 475of a makefile, see @ref{Complex Makefile}. 476 477When @code{make} recompiles the editor, each changed C source file 478must be recompiled. If a header file has changed, each C source file 479that includes the header file must be recompiled to be safe. Each 480compilation produces an object file corresponding to the source file. 481Finally, if any source file has been recompiled, all the object files, 482whether newly made or saved from previous compilations, must be linked 483together to produce the new executable editor. 484@cindex recompilation 485@cindex editor 486 487@menu 488* Rule Introduction:: What a rule looks like. 489* Simple Makefile:: A Simple Makefile 490* How Make Works:: How @code{make} Processes This Makefile 491* Variables Simplify:: Variables Make Makefiles Simpler 492* make Deduces:: Letting @code{make} Deduce the Commands 493* Combine By Prerequisite:: Another Style of Makefile 494* Cleanup:: Rules for Cleaning the Directory 495@end menu 496 497@node Rule Introduction, Simple Makefile, Introduction, Introduction 498@comment node-name, next, previous, up 499@section What a Rule Looks Like 500@cindex rule, introduction to 501@cindex makefile rule parts 502@cindex parts of makefile rule 503 504A simple makefile consists of ``rules'' with the following shape: 505 506@cindex targets, introduction to 507@cindex prerequisites, introduction to 508@cindex commands, introduction to 509@example 510@group 511@var{target} @dots{} : @var{prerequisites} @dots{} 512 @var{command} 513 @dots{} 514 @dots{} 515@end group 516@end example 517 518A @dfn{target} is usually the name of a file that is generated by a 519program; examples of targets are executable or object files. A target 520can also be the name of an action to carry out, such as @samp{clean} 521(@pxref{Phony Targets}). 522 523A @dfn{prerequisite} is a file that is used as input to create the 524target. A target often depends on several files. 525 526@cindex tabs in rules 527A @dfn{command} is an action that @code{make} carries out. 528A rule may have more than one command, each on its own line. 529@strong{Please note:} you need to put a tab character at the beginning of 530every command line! This is an obscurity that catches the unwary. 531 532Usually a command is in a rule with prerequisites and serves to create a 533target file if any of the prerequisites change. However, the rule that 534specifies commands for the target need not have prerequisites. For 535example, the rule containing the delete command associated with the 536target @samp{clean} does not have prerequisites. 537 538A @dfn{rule}, then, explains how and when to remake certain files 539which are the targets of the particular rule. @code{make} carries out 540the commands on the prerequisites to create or update the target. A 541rule can also explain how and when to carry out an action. 542@xref{Rules, , Writing Rules}. 543 544A makefile may contain other text besides rules, but a simple makefile 545need only contain rules. Rules may look somewhat more complicated 546than shown in this template, but all fit the pattern more or less. 547 548@node Simple Makefile, How Make Works, Rule Introduction, Introduction 549@section A Simple Makefile 550@cindex simple makefile 551@cindex makefile, simple 552 553Here is a straightforward makefile that describes the way an 554executable file called @code{edit} depends on eight object files 555which, in turn, depend on eight C source and three header files. 556 557In this example, all the C files include @file{defs.h}, but only those 558defining editing commands include @file{command.h}, and only low 559level files that change the editor buffer include @file{buffer.h}. 560 561@example 562@group 563edit : main.o kbd.o command.o display.o \ 564 insert.o search.o files.o utils.o 565 cc -o edit main.o kbd.o command.o display.o \ 566 insert.o search.o files.o utils.o 567 568main.o : main.c defs.h 569 cc -c main.c 570kbd.o : kbd.c defs.h command.h 571 cc -c kbd.c 572command.o : command.c defs.h command.h 573 cc -c command.c 574display.o : display.c defs.h buffer.h 575 cc -c display.c 576insert.o : insert.c defs.h buffer.h 577 cc -c insert.c 578search.o : search.c defs.h buffer.h 579 cc -c search.c 580files.o : files.c defs.h buffer.h command.h 581 cc -c files.c 582utils.o : utils.c defs.h 583 cc -c utils.c 584clean : 585 rm edit main.o kbd.o command.o display.o \ 586 insert.o search.o files.o utils.o 587@end group 588@end example 589 590@noindent 591We split each long line into two lines using backslash-newline; this is 592like using one long line, but is easier to read. 593@cindex continuation lines 594@cindex @code{\} (backslash), for continuation lines 595@cindex backslash (@code{\}), for continuation lines 596@cindex quoting newline, in makefile 597@cindex newline, quoting, in makefile 598 599To use this makefile to create the executable file called @file{edit}, 600type: 601 602@example 603make 604@end example 605 606To use this makefile to delete the executable file and all the object 607files from the directory, type: 608 609@example 610make clean 611@end example 612 613In the example makefile, the targets include the executable file 614@samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}. The 615prerequisites are files such as @samp{main.c} and @samp{defs.h}. 616In fact, each @samp{.o} file is both a target and a prerequisite. 617Commands include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}. 618 619When a target is a file, it needs to be recompiled or relinked if any 620of its prerequisites change. In addition, any prerequisites that are 621themselves automatically generated should be updated first. In this 622example, @file{edit} depends on each of the eight object files; the 623object file @file{main.o} depends on the source file @file{main.c} and 624on the header file @file{defs.h}. 625 626A shell command follows each line that contains a target and 627prerequisites. These shell commands say how to update the target file. 628A tab character must come at the beginning of every command line to 629distinguish command lines from other lines in the makefile. (Bear in 630mind that @code{make} does not know anything about how the commands 631work. It is up to you to supply commands that will update the target 632file properly. All @code{make} does is execute the commands in the rule 633you have specified when the target file needs to be updated.) 634@cindex shell command 635 636The target @samp{clean} is not a file, but merely the name of an 637action. Since you 638normally 639do not want to carry out the actions in this rule, @samp{clean} is not a prerequisite of any other rule. 640Consequently, @code{make} never does anything with it unless you tell 641it specifically. Note that this rule not only is not a prerequisite, it 642also does not have any prerequisites, so the only purpose of the rule 643is to run the specified commands. Targets that do not refer to files 644but are just actions are called @dfn{phony targets}. @xref{Phony 645Targets}, for information about this kind of target. @xref{Errors, , 646Errors in Commands}, to see how to cause @code{make} to ignore errors 647from @code{rm} or any other command. 648@cindex @code{clean} target 649@cindex @code{rm} (shell command) 650 651@node How Make Works, Variables Simplify, Simple Makefile, Introduction 652@comment node-name, next, previous, up 653@section How @code{make} Processes a Makefile 654@cindex processing a makefile 655@cindex makefile, how @code{make} processes 656 657By default, @code{make} starts with the first target (not targets whose 658names start with @samp{.}). This is called the @dfn{default goal}. 659(@dfn{Goals} are the targets that @code{make} strives ultimately to 660update. You can override this behavior using the command line 661(@pxref{Goals, , Arguments to Specify the Goals}) or with the 662@code{.DEFAULT_GOAL} special variable (@pxref{Special Variables, , 663Other Special Variables}). 664@cindex default goal 665@cindex goal, default 666@cindex goal 667 668In the simple example of the previous section, the default goal is to 669update the executable program @file{edit}; therefore, we put that rule 670first. 671 672Thus, when you give the command: 673 674@example 675make 676@end example 677 678@noindent 679@code{make} reads the makefile in the current directory and begins by 680processing the first rule. In the example, this rule is for relinking 681@file{edit}; but before @code{make} can fully process this rule, it 682must process the rules for the files that @file{edit} depends on, 683which in this case are the object files. Each of these files is 684processed according to its own rule. These rules say to update each 685@samp{.o} file by compiling its source file. The recompilation must 686be done if the source file, or any of the header files named as 687prerequisites, is more recent than the object file, or if the object 688file does not exist. 689 690The other rules are processed because their targets appear as 691prerequisites of the goal. If some other rule is not depended on by the 692goal (or anything it depends on, etc.), that rule is not processed, 693unless you tell @code{make} to do so (with a command such as 694@w{@code{make clean}}). 695 696Before recompiling an object file, @code{make} considers updating its 697prerequisites, the source file and header files. This makefile does not 698specify anything to be done for them---the @samp{.c} and @samp{.h} files 699are not the targets of any rules---so @code{make} does nothing for these 700files. But @code{make} would update automatically generated C programs, 701such as those made by Bison or Yacc, by their own rules at this time. 702 703After recompiling whichever object files need it, @code{make} decides 704whether to relink @file{edit}. This must be done if the file 705@file{edit} does not exist, or if any of the object files are newer than 706it. If an object file was just recompiled, it is now newer than 707@file{edit}, so @file{edit} is relinked. 708@cindex relinking 709 710Thus, if we change the file @file{insert.c} and run @code{make}, 711@code{make} will compile that file to update @file{insert.o}, and then 712link @file{edit}. If we change the file @file{command.h} and run 713@code{make}, @code{make} will recompile the object files @file{kbd.o}, 714@file{command.o} and @file{files.o} and then link the file @file{edit}. 715 716@node Variables Simplify, make Deduces, How Make Works, Introduction 717@section Variables Make Makefiles Simpler 718@cindex variables 719@cindex simplifying with variables 720 721In our example, we had to list all the object files twice in the rule for 722@file{edit} (repeated here): 723 724@example 725@group 726edit : main.o kbd.o command.o display.o \ 727 insert.o search.o files.o utils.o 728 cc -o edit main.o kbd.o command.o display.o \ 729 insert.o search.o files.o utils.o 730@end group 731@end example 732 733@cindex @code{objects} 734Such duplication is error-prone; if a new object file is added to the 735system, we might add it to one list and forget the other. We can eliminate 736the risk and simplify the makefile by using a variable. @dfn{Variables} 737allow a text string to be defined once and substituted in multiple places 738later (@pxref{Using Variables, ,How to Use Variables}). 739 740@cindex @code{OBJECTS} 741@cindex @code{objs} 742@cindex @code{OBJS} 743@cindex @code{obj} 744@cindex @code{OBJ} 745It is standard practice for every makefile to have a variable named 746@code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj}, 747or @code{OBJ} which is a list of all object file names. We would 748define such a variable @code{objects} with a line like this in the 749makefile:@refill 750 751@example 752@group 753objects = main.o kbd.o command.o display.o \ 754 insert.o search.o files.o utils.o 755@end group 756@end example 757 758@noindent 759Then, each place we want to put a list of the object file names, we can 760substitute the variable's value by writing @samp{$(objects)} 761(@pxref{Using Variables, ,How to Use Variables}). 762 763Here is how the complete simple makefile looks when you use a variable 764for the object files: 765 766@example 767@group 768objects = main.o kbd.o command.o display.o \ 769 insert.o search.o files.o utils.o 770 771edit : $(objects) 772 cc -o edit $(objects) 773main.o : main.c defs.h 774 cc -c main.c 775kbd.o : kbd.c defs.h command.h 776 cc -c kbd.c 777command.o : command.c defs.h command.h 778 cc -c command.c 779display.o : display.c defs.h buffer.h 780 cc -c display.c 781insert.o : insert.c defs.h buffer.h 782 cc -c insert.c 783search.o : search.c defs.h buffer.h 784 cc -c search.c 785files.o : files.c defs.h buffer.h command.h 786 cc -c files.c 787utils.o : utils.c defs.h 788 cc -c utils.c 789clean : 790 rm edit $(objects) 791@end group 792@end example 793 794@node make Deduces, Combine By Prerequisite, Variables Simplify, Introduction 795@section Letting @code{make} Deduce the Commands 796@cindex deducing commands (implicit rules) 797@cindex implicit rule, introduction to 798@cindex rule, implicit, introduction to 799 800It is not necessary to spell out the commands for compiling the individual 801C source files, because @code{make} can figure them out: it has an 802@dfn{implicit rule} for updating a @samp{.o} file from a correspondingly 803named @samp{.c} file using a @samp{cc -c} command. For example, it will 804use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into 805@file{main.o}. We can therefore omit the commands from the rules for the 806object files. @xref{Implicit Rules, ,Using Implicit Rules}.@refill 807 808When a @samp{.c} file is used automatically in this way, it is also 809automatically added to the list of prerequisites. We can therefore omit 810the @samp{.c} files from the prerequisites, provided we omit the commands. 811 812Here is the entire example, with both of these changes, and a variable 813@code{objects} as suggested above: 814 815@example 816@group 817objects = main.o kbd.o command.o display.o \ 818 insert.o search.o files.o utils.o 819 820edit : $(objects) 821 cc -o edit $(objects) 822 823main.o : defs.h 824kbd.o : defs.h command.h 825command.o : defs.h command.h 826display.o : defs.h buffer.h 827insert.o : defs.h buffer.h 828search.o : defs.h buffer.h 829files.o : defs.h buffer.h command.h 830utils.o : defs.h 831 832.PHONY : clean 833clean : 834 rm edit $(objects) 835@end group 836@end example 837 838@noindent 839This is how we would write the makefile in actual practice. (The 840complications associated with @samp{clean} are described elsewhere. 841See @ref{Phony Targets}, and @ref{Errors, ,Errors in Commands}.) 842 843Because implicit rules are so convenient, they are important. You 844will see them used frequently.@refill 845 846@node Combine By Prerequisite, Cleanup, make Deduces, Introduction 847@section Another Style of Makefile 848@cindex combining rules by prerequisite 849 850When the objects of a makefile are created only by implicit rules, an 851alternative style of makefile is possible. In this style of makefile, 852you group entries by their prerequisites instead of by their targets. 853Here is what one looks like: 854 855@example 856@group 857objects = main.o kbd.o command.o display.o \ 858 insert.o search.o files.o utils.o 859 860edit : $(objects) 861 cc -o edit $(objects) 862 863$(objects) : defs.h 864kbd.o command.o files.o : command.h 865display.o insert.o search.o files.o : buffer.h 866@end group 867@end example 868 869@noindent 870Here @file{defs.h} is given as a prerequisite of all the object files; 871@file{command.h} and @file{buffer.h} are prerequisites of the specific 872object files listed for them. 873 874Whether this is better is a matter of taste: it is more compact, but some 875people dislike it because they find it clearer to put all the information 876about each target in one place. 877 878@node Cleanup, , Combine By Prerequisite, Introduction 879@section Rules for Cleaning the Directory 880@cindex cleaning up 881@cindex removing, to clean up 882 883Compiling a program is not the only thing you might want to write rules 884for. Makefiles commonly tell how to do a few other things besides 885compiling a program: for example, how to delete all the object files 886and executables so that the directory is @samp{clean}. 887 888@cindex @code{clean} target 889Here is how we 890could write a @code{make} rule for cleaning our example editor: 891 892@example 893@group 894clean: 895 rm edit $(objects) 896@end group 897@end example 898 899In practice, we might want to write the rule in a somewhat more 900complicated manner to handle unanticipated situations. We would do this: 901 902@example 903@group 904.PHONY : clean 905clean : 906 -rm edit $(objects) 907@end group 908@end example 909 910@noindent 911This prevents @code{make} from getting confused by an actual file 912called @file{clean} and causes it to continue in spite of errors from 913@code{rm}. (See @ref{Phony Targets}, and @ref{Errors, ,Errors in 914Commands}.) 915 916@noindent 917A rule such as this should not be placed at the beginning of the 918makefile, because we do not want it to run by default! Thus, in the 919example makefile, we want the rule for @code{edit}, which recompiles 920the editor, to remain the default goal. 921 922Since @code{clean} is not a prerequisite of @code{edit}, this rule will not 923run at all if we give the command @samp{make} with no arguments. In 924order to make the rule run, we have to type @samp{make clean}. 925@xref{Running, ,How to Run @code{make}}. 926 927@node Makefiles, Rules, Introduction, Top 928@chapter Writing Makefiles 929 930@cindex makefile, how to write 931The information that tells @code{make} how to recompile a system comes from 932reading a data base called the @dfn{makefile}. 933 934@menu 935* Makefile Contents:: What makefiles contain. 936* Makefile Names:: How to name your makefile. 937* Include:: How one makefile can use another makefile. 938* MAKEFILES Variable:: The environment can specify extra makefiles. 939* MAKEFILE_LIST Variable:: Discover which makefiles have been read. 940* Special Variables:: Other special variables. 941* Remaking Makefiles:: How makefiles get remade. 942* Overriding Makefiles:: How to override part of one makefile 943 with another makefile. 944* Reading Makefiles:: How makefiles are parsed. 945* Secondary Expansion:: How and when secondary expansion is performed. 946@end menu 947 948@node Makefile Contents, Makefile Names, Makefiles, Makefiles 949@section What Makefiles Contain 950 951Makefiles contain five kinds of things: @dfn{explicit rules}, 952@dfn{implicit rules}, @dfn{variable definitions}, @dfn{directives}, 953and @dfn{comments}. Rules, variables, and directives are described at 954length in later chapters.@refill 955 956@itemize @bullet 957@cindex rule, explicit, definition of 958@cindex explicit rule, definition of 959@item 960An @dfn{explicit rule} says when and how to remake one or more files, 961called the rule's @dfn{targets}. It lists the other files that the 962targets depend on, called the @dfn{prerequisites} of the target, and 963may also give commands to use to create or update the targets. 964@xref{Rules, ,Writing Rules}. 965 966@cindex rule, implicit, definition of 967@cindex implicit rule, definition of 968@item 969An @dfn{implicit rule} says when and how to remake a class of files 970based on their names. It describes how a target may depend on a file 971with a name similar to the target and gives commands to create or 972update such a target. @xref{Implicit Rules, ,Using Implicit Rules}. 973 974@cindex variable definition 975@item 976A @dfn{variable definition} is a line that specifies a text string 977value for a variable that can be substituted into the text later. The 978simple makefile example shows a variable definition for @code{objects} 979as a list of all object files (@pxref{Variables Simplify, , Variables 980Make Makefiles Simpler}). 981 982@cindex directive 983@item 984A @dfn{directive} is a command for @code{make} to do something special while 985reading the makefile. These include: 986 987@itemize @bullet 988@item 989Reading another makefile (@pxref{Include, ,Including Other Makefiles}). 990 991@item 992Deciding (based on the values of variables) whether to use or 993ignore a part of the makefile (@pxref{Conditionals, ,Conditional Parts of Makefiles}). 994 995@item 996Defining a variable from a verbatim string containing multiple lines 997(@pxref{Defining, ,Defining Variables Verbatim}). 998@end itemize 999 1000@cindex comments, in makefile 1001@cindex @code{#} (comments), in makefile 1002@item 1003@samp{#} in a line of a makefile starts a @dfn{comment}. It and the 1004rest of the line are ignored, except that a trailing backslash not 1005escaped by another backslash will continue the comment across multiple 1006lines. A line containing just a comment (with perhaps spaces before 1007it) is effectively blank, and is ignored. If you want a literal 1008@code{#}, escape it with a backslash (e.g., @code{\#}). Comments may 1009appear on any line in the makefile, although they are treated 1010specially in certain situations. 1011 1012Within a command script (if the line begins with a TAB character) the 1013entire line is passed to the shell, just as with any other line that 1014begins with a TAB. The shell decides how to interpret the text: 1015whether or not this is a comment is up to the shell. 1016 1017Within a @code{define} directive, comments are not ignored during the 1018definition of the variable, but rather kept intact in the value of the 1019variable. When the variable is expanded they will either be treated 1020as @code{make} comments or as command script text, depending on the 1021context in which the variable is evaluated. 1022@end itemize 1023 1024@node Makefile Names, Include, Makefile Contents, Makefiles 1025@section What Name to Give Your Makefile 1026@cindex makefile name 1027@cindex name of makefile 1028@cindex default makefile name 1029@cindex file name of makefile 1030 1031@c following paragraph rewritten to avoid overfull hbox 1032By default, when @code{make} looks for the makefile, it tries the 1033following names, in order: @file{GNUmakefile}, @file{makefile} 1034and @file{Makefile}.@refill 1035@findex Makefile 1036@findex GNUmakefile 1037@findex makefile 1038 1039@cindex @code{README} 1040Normally you should call your makefile either @file{makefile} or 1041@file{Makefile}. (We recommend @file{Makefile} because it appears 1042prominently near the beginning of a directory listing, right near other 1043important files such as @file{README}.) The first name checked, 1044@file{GNUmakefile}, is not recommended for most makefiles. You should 1045use this name if you have a makefile that is specific to GNU 1046@code{make}, and will not be understood by other versions of 1047@code{make}. Other @code{make} programs look for @file{makefile} and 1048@file{Makefile}, but not @file{GNUmakefile}. 1049 1050If @code{make} finds none of these names, it does not use any makefile. 1051Then you must specify a goal with a command argument, and @code{make} 1052will attempt to figure out how to remake it using only its built-in 1053implicit rules. @xref{Implicit Rules, ,Using Implicit Rules}. 1054 1055@cindex @code{-f} 1056@cindex @code{--file} 1057@cindex @code{--makefile} 1058If you want to use a nonstandard name for your makefile, you can specify 1059the makefile name with the @samp{-f} or @samp{--file} option. The 1060arguments @w{@samp{-f @var{name}}} or @w{@samp{--file=@var{name}}} tell 1061@code{make} to read the file @var{name} as the makefile. If you use 1062more than one @samp{-f} or @samp{--file} option, you can specify several 1063makefiles. All the makefiles are effectively concatenated in the order 1064specified. The default makefile names @file{GNUmakefile}, 1065@file{makefile} and @file{Makefile} are not checked automatically if you 1066specify @samp{-f} or @samp{--file}.@refill 1067@cindex specifying makefile name 1068@cindex makefile name, how to specify 1069@cindex name of makefile, how to specify 1070@cindex file name of makefile, how to specify 1071 1072@node Include, MAKEFILES Variable, Makefile Names, Makefiles 1073@section Including Other Makefiles 1074@cindex including other makefiles 1075@cindex makefile, including 1076 1077@findex include 1078The @code{include} directive tells @code{make} to suspend reading the 1079current makefile and read one or more other makefiles before continuing. 1080The directive is a line in the makefile that looks like this: 1081 1082@example 1083include @var{filenames}@dots{} 1084@end example 1085 1086@noindent 1087@var{filenames} can contain shell file name patterns. If 1088@var{filenames} is empty, nothing is included and no error is printed. 1089@cindex shell file name pattern (in @code{include}) 1090@cindex shell wildcards (in @code{include}) 1091@cindex wildcard, in @code{include} 1092 1093Extra spaces are allowed and ignored at the beginning of the line, but 1094a tab is not allowed. (If the line begins with a tab, it will be 1095considered a command line.) Whitespace is required between 1096@code{include} and the file names, and between file names; extra 1097whitespace is ignored there and at the end of the directive. A 1098comment starting with @samp{#} is allowed at the end of the line. If 1099the file names contain any variable or function references, they are 1100expanded. @xref{Using Variables, ,How to Use Variables}. 1101 1102For example, if you have three @file{.mk} files, @file{a.mk}, 1103@file{b.mk}, and @file{c.mk}, and @code{$(bar)} expands to 1104@code{bish bash}, then the following expression 1105 1106@example 1107include foo *.mk $(bar) 1108@end example 1109 1110is equivalent to 1111 1112@example 1113include foo a.mk b.mk c.mk bish bash 1114@end example 1115 1116When @code{make} processes an @code{include} directive, it suspends 1117reading of the containing makefile and reads from each listed file in 1118turn. When that is finished, @code{make} resumes reading the 1119makefile in which the directive appears. 1120 1121One occasion for using @code{include} directives is when several programs, 1122handled by individual makefiles in various directories, need to use a 1123common set of variable definitions 1124(@pxref{Setting, ,Setting Variables}) or pattern rules 1125(@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}). 1126 1127Another such occasion is when you want to generate prerequisites from 1128source files automatically; the prerequisites can be put in a file that 1129is included by the main makefile. This practice is generally cleaner 1130than that of somehow appending the prerequisites to the end of the main 1131makefile as has been traditionally done with other versions of 1132@code{make}. @xref{Automatic Prerequisites}. 1133@cindex prerequisites, automatic generation 1134@cindex automatic generation of prerequisites 1135@cindex generating prerequisites automatically 1136 1137@cindex @code{-I} 1138@cindex @code{--include-dir} 1139@cindex included makefiles, default directories 1140@cindex default directories for included makefiles 1141@findex /usr/gnu/include 1142@findex /usr/local/include 1143@findex /usr/include 1144If the specified name does not start with a slash, and the file is not 1145found in the current directory, several other directories are searched. 1146First, any directories you have specified with the @samp{-I} or 1147@samp{--include-dir} option are searched 1148(@pxref{Options Summary, ,Summary of Options}). 1149Then the following directories (if they exist) 1150are searched, in this order: 1151@file{@var{prefix}/include} (normally @file{/usr/local/include} 1152@footnote{GNU Make compiled for MS-DOS and MS-Windows behaves as if 1153@var{prefix} has been defined to be the root of the DJGPP tree 1154hierarchy.}) 1155@file{/usr/gnu/include}, 1156@file{/usr/local/include}, @file{/usr/include}. 1157 1158If an included makefile cannot be found in any of these directories, a 1159warning message is generated, but it is not an immediately fatal error; 1160processing of the makefile containing the @code{include} continues. 1161Once it has finished reading makefiles, @code{make} will try to remake 1162any that are out of date or don't exist. 1163@xref{Remaking Makefiles, ,How Makefiles Are Remade}. 1164Only after it has tried to find a way to remake a makefile and failed, 1165will @code{make} diagnose the missing makefile as a fatal error. 1166 1167If you want @code{make} to simply ignore a makefile which does not exist 1168and cannot be remade, with no error message, use the @w{@code{-include}} 1169directive instead of @code{include}, like this: 1170 1171@example 1172-include @var{filenames}@dots{} 1173@end example 1174 1175This acts like @code{include} in every way except that there is no 1176error (not even a warning) if any of the @var{filenames} do not exist. 1177For compatibility with some other @code{make} implementations, 1178@code{sinclude} is another name for @w{@code{-include}}. 1179 1180@node MAKEFILES Variable, MAKEFILE_LIST Variable, Include, Makefiles 1181@section The Variable @code{MAKEFILES} 1182@cindex makefile, and @code{MAKEFILES} variable 1183@cindex including (@code{MAKEFILES} variable) 1184 1185@vindex MAKEFILES 1186If the environment variable @code{MAKEFILES} is defined, @code{make} 1187considers its value as a list of names (separated by whitespace) of 1188additional makefiles to be read before the others. This works much like 1189the @code{include} directive: various directories are searched for those 1190files (@pxref{Include, ,Including Other Makefiles}). In addition, the 1191default goal is never taken from one of these makefiles and it is not an 1192error if the files listed in @code{MAKEFILES} are not found.@refill 1193 1194@cindex recursion, and @code{MAKEFILES} variable 1195The main use of @code{MAKEFILES} is in communication between recursive 1196invocations of @code{make} (@pxref{Recursion, ,Recursive Use of 1197@code{make}}). It usually is not desirable to set the environment 1198variable before a top-level invocation of @code{make}, because it is 1199usually better not to mess with a makefile from outside. However, if 1200you are running @code{make} without a specific makefile, a makefile in 1201@code{MAKEFILES} can do useful things to help the built-in implicit 1202rules work better, such as defining search paths (@pxref{Directory Search}). 1203 1204Some users are tempted to set @code{MAKEFILES} in the environment 1205automatically on login, and program makefiles to expect this to be done. 1206This is a very bad idea, because such makefiles will fail to work if run by 1207anyone else. It is much better to write explicit @code{include} directives 1208in the makefiles. @xref{Include, , Including Other Makefiles}. 1209 1210@node MAKEFILE_LIST Variable, Special Variables, MAKEFILES Variable, Makefiles 1211@comment node-name, next, previous, up 1212@section The Variable @code{MAKEFILE_LIST} 1213@cindex makefiles, and @code{MAKEFILE_LIST} variable 1214@cindex including (@code{MAKEFILE_LIST} variable) 1215@vindex MAKEFILE_LIST 1216 1217As @code{make} reads various makefiles, including any obtained from the 1218@code{MAKEFILES} variable, the command line, the default files, or 1219from @code{include} directives, their names will be automatically 1220appended to the @code{MAKEFILE_LIST} variable. They are added right 1221before @code{make} begins to parse them. 1222 1223This means that if the first thing a makefile does is examine the last 1224word in this variable, it will be the name of the current makefile. 1225Once the current makefile has used @code{include}, however, the last 1226word will be the just-included makefile. 1227 1228If a makefile named @code{Makefile} has this content: 1229 1230@example 1231@group 1232name1 := $(lastword $(MAKEFILE_LIST)) 1233 1234include inc.mk 1235 1236name2 := $(lastword $(MAKEFILE_LIST)) 1237 1238all: 1239 @@echo name1 = $(name1) 1240 @@echo name2 = $(name2) 1241@end group 1242@end example 1243 1244@noindent 1245then you would expect to see this output: 1246 1247@example 1248@group 1249name1 = Makefile 1250name2 = inc.mk 1251@end group 1252@end example 1253 1254@xref{Text Functions}, for more information on the @code{word} and 1255@code{words} functions used above. @xref{Flavors, The Two Flavors of 1256Variables}, for more information on simply-expanded (@code{:=}) 1257variable definitions. 1258 1259@node Special Variables, Remaking Makefiles, MAKEFILE_LIST Variable, Makefiles 1260@comment node-name, next, previous, up 1261@section Other Special Variables 1262@cindex makefiles, and special variables 1263@cindex special variables 1264 1265GNU @code{make} also supports other special variables. Unless 1266otherwise documented here, these values lose their special properties 1267if they are set by a makefile or on the command line. 1268 1269@table @code 1270 1271@vindex .DEFAULT_GOAL @r{(define default goal)} 1272@item .DEFAULT_GOAL 1273Sets the default goal to be used if no targets were specified on the 1274command line (@pxref{Goals, , Arguments to Specify the Goals}). The 1275@code{.DEFAULT_GOAL} variable allows you to discover the current 1276default goal, restart the default goal selection algorithm by clearing 1277its value, or to explicitly set the default goal. The following 1278example illustrates these cases: 1279 1280@example 1281@group 1282# Query the default goal. 1283ifeq ($(.DEFAULT_GOAL),) 1284 $(warning no default goal is set) 1285endif 1286 1287.PHONY: foo 1288foo: ; @@echo $@@ 1289 1290$(warning default goal is $(.DEFAULT_GOAL)) 1291 1292# Reset the default goal. 1293.DEFAULT_GOAL := 1294 1295.PHONY: bar 1296bar: ; @@echo $@@ 1297 1298$(warning default goal is $(.DEFAULT_GOAL)) 1299 1300# Set our own. 1301.DEFAULT_GOAL := foo 1302@end group 1303@end example 1304 1305This makefile prints: 1306 1307@example 1308@group 1309no default goal is set 1310default goal is foo 1311default goal is bar 1312foo 1313@end group 1314@end example 1315 1316Note that assigning more than one target name to @code{.DEFAULT_GOAL} is 1317illegal and will result in an error. 1318 1319@vindex MAKE_RESTARTS @r{(number of times @code{make} has restarted)} 1320@item MAKE_RESTARTS 1321This variable is set only if this instance of @code{make} has 1322restarted (@pxref{Remaking Makefiles, , How Makefiles Are Remade}): it 1323will contain the number of times this instance has restarted. Note 1324this is not the same as recursion (counted by the @code{MAKELEVEL} 1325variable). You should not set, modify, or export this variable. 1326 1327@vindex .VARIABLES @r{(list of variables)} 1328@item .VARIABLES 1329Expands to a list of the @emph{names} of all global variables defined 1330so far. This includes variables which have empty values, as well as 1331built-in variables (@pxref{Implicit Variables, , Variables Used by 1332Implicit Rules}), but does not include any variables which are only 1333defined in a target-specific context. Note that any value you assign 1334to this variable will be ignored; it will always return its special 1335value. 1336 1337@c @vindex .TARGETS @r{(list of targets)} 1338@c @item .TARGETS 1339@c The second special variable is @code{.TARGETS}. When expanded, the 1340@c value consists of a list of all targets defined in all makefiles read 1341@c up until that point. Note it's not enough for a file to be simply 1342@c mentioned in the makefile to be listed in this variable, even if it 1343@c would match an implicit rule and become an ``implicit target''. The 1344@c file must appear as a target, on the left-hand side of a ``:'', to be 1345@c considered a target for the purposes of this variable. 1346 1347@vindex .FEATURES @r{(list of supported features)} 1348@item .FEATURES 1349Expands to a list of special features supported by this version of 1350@code{make}. Possible values include: 1351 1352@table @samp 1353 1354@item archives 1355Supports @code{ar} (archive) files using special filename syntax. 1356@xref{Archives, ,Using @code{make} to Update Archive Files}. 1357 1358@item check-symlink 1359Supports the @code{-L} (@code{--check-symlink-times}) flag. 1360@xref{Options Summary, ,Summary of Options}. 1361 1362@item else-if 1363Supports ``else if'' non-nested conditionals. @xref{Conditional 1364Syntax, ,Syntax of Conditionals}. 1365 1366@item jobserver 1367Supports ``job server'' enhanced parallel builds. @xref{Parallel, 1368,Parallel Execution}. 1369 1370@item second-expansion 1371Supports secondary expansion of prerequisite lists. 1372 1373@item order-only 1374Supports order-only prerequisites. @xref{Prerequisite Types, ,Types 1375of Prerequisites}. 1376 1377@item target-specific 1378Supports target-specific and pattern-specific variable assignments. 1379@xref{Target-specific, ,Target-specific Variable Values}. 1380 1381@end table 1382 1383@vindex .INCLUDE_DIRS @r{(list of include directories)} 1384@item .INCLUDE_DIRS 1385Expands to a list of directories that @code{make} searches for 1386included makefiles (@pxref{Include, , Including Other Makefiles}). 1387 1388@end table 1389 1390@node Remaking Makefiles, Overriding Makefiles, Special Variables, Makefiles 1391@section How Makefiles Are Remade 1392 1393@cindex updating makefiles 1394@cindex remaking makefiles 1395@cindex makefile, remaking of 1396Sometimes makefiles can be remade from other files, such as RCS or SCCS 1397files. If a makefile can be remade from other files, you probably want 1398@code{make} to get an up-to-date version of the makefile to read in. 1399 1400To this end, after reading in all makefiles, @code{make} will consider 1401each as a goal target and attempt to update it. If a makefile has a 1402rule which says how to update it (found either in that very makefile or 1403in another one) or if an implicit rule applies to it (@pxref{Implicit 1404Rules, ,Using Implicit Rules}), it will be updated if necessary. After 1405all makefiles have been checked, if any have actually been changed, 1406@code{make} starts with a clean slate and reads all the makefiles over 1407again. (It will also attempt to update each of them over again, but 1408normally this will not change them again, since they are already up to 1409date.)@refill 1410 1411If you know that one or more of your makefiles cannot be remade and you 1412want to keep @code{make} from performing an implicit rule search on 1413them, perhaps for efficiency reasons, you can use any normal method of 1414preventing implicit rule lookup to do so. For example, you can write an 1415explicit rule with the makefile as the target, and an empty command 1416string (@pxref{Empty Commands, ,Using Empty Commands}). 1417 1418If the makefiles specify a double-colon rule to remake a file with 1419commands but no prerequisites, that file will always be remade 1420(@pxref{Double-Colon}). In the case of makefiles, a makefile that has a 1421double-colon rule with commands but no prerequisites will be remade every 1422time @code{make} is run, and then again after @code{make} starts over 1423and reads the makefiles in again. This would cause an infinite loop: 1424@code{make} would constantly remake the makefile, and never do anything 1425else. So, to avoid this, @code{make} will @strong{not} attempt to 1426remake makefiles which are specified as targets of a double-colon rule 1427with commands but no prerequisites.@refill 1428 1429If you do not specify any makefiles to be read with @samp{-f} or 1430@samp{--file} options, @code{make} will try the default makefile names; 1431@pxref{Makefile Names, ,What Name to Give Your Makefile}. Unlike 1432makefiles explicitly requested with @samp{-f} or @samp{--file} options, 1433@code{make} is not certain that these makefiles should exist. However, 1434if a default makefile does not exist but can be created by running 1435@code{make} rules, you probably want the rules to be run so that the 1436makefile can be used. 1437 1438Therefore, if none of the default makefiles exists, @code{make} will try 1439to make each of them in the same order in which they are searched for 1440(@pxref{Makefile Names, ,What Name to Give Your Makefile}) 1441until it succeeds in making one, or it runs out of names to try. Note 1442that it is not an error if @code{make} cannot find or make any makefile; 1443a makefile is not always necessary.@refill 1444 1445When you use the @samp{-t} or @samp{--touch} option 1446(@pxref{Instead of Execution, ,Instead of Executing the Commands}), 1447you would not want to use an out-of-date makefile to decide which 1448targets to touch. So the @samp{-t} option has no effect on updating 1449makefiles; they are really updated even if @samp{-t} is specified. 1450Likewise, @samp{-q} (or @samp{--question}) and @samp{-n} (or 1451@samp{--just-print}) do not prevent updating of makefiles, because an 1452out-of-date makefile would result in the wrong output for other targets. 1453Thus, @samp{make -f mfile -n foo} will update @file{mfile}, read it in, 1454and then print the commands to update @file{foo} and its prerequisites 1455without running them. The commands printed for @file{foo} will be those 1456specified in the updated contents of @file{mfile}. 1457 1458However, on occasion you might actually wish to prevent updating of even 1459the makefiles. You can do this by specifying the makefiles as goals in 1460the command line as well as specifying them as makefiles. When the 1461makefile name is specified explicitly as a goal, the options @samp{-t} 1462and so on do apply to them. 1463 1464Thus, @samp{make -f mfile -n mfile foo} would read the makefile 1465@file{mfile}, print the commands needed to update it without actually 1466running them, and then print the commands needed to update @file{foo} 1467without running them. The commands for @file{foo} will be those 1468specified by the existing contents of @file{mfile}. 1469 1470@node Overriding Makefiles, Reading Makefiles, Remaking Makefiles, Makefiles 1471@section Overriding Part of Another Makefile 1472 1473@cindex overriding makefiles 1474@cindex makefile, overriding 1475Sometimes it is useful to have a makefile that is mostly just like 1476another makefile. You can often use the @samp{include} directive to 1477include one in the other, and add more targets or variable definitions. 1478However, if the two makefiles give different commands for the same 1479target, @code{make} will not let you just do this. But there is another way. 1480 1481@cindex match-anything rule, used to override 1482In the containing makefile (the one that wants to include the other), 1483you can use a match-anything pattern rule to say that to remake any 1484target that cannot be made from the information in the containing 1485makefile, @code{make} should look in another makefile. 1486@xref{Pattern Rules}, for more information on pattern rules. 1487 1488For example, if you have a makefile called @file{Makefile} that says how 1489to make the target @samp{foo} (and other targets), you can write a 1490makefile called @file{GNUmakefile} that contains: 1491 1492@example 1493foo: 1494 frobnicate > foo 1495 1496%: force 1497 @@$(MAKE) -f Makefile $@@ 1498force: ; 1499@end example 1500 1501If you say @samp{make foo}, @code{make} will find @file{GNUmakefile}, 1502read it, and see that to make @file{foo}, it needs to run the command 1503@samp{frobnicate > foo}. If you say @samp{make bar}, @code{make} will 1504find no way to make @file{bar} in @file{GNUmakefile}, so it will use the 1505commands from the pattern rule: @samp{make -f Makefile bar}. If 1506@file{Makefile} provides a rule for updating @file{bar}, @code{make} 1507will apply the rule. And likewise for any other target that 1508@file{GNUmakefile} does not say how to make. 1509 1510The way this works is that the pattern rule has a pattern of just 1511@samp{%}, so it matches any target whatever. The rule specifies a 1512prerequisite @file{force}, to guarantee that the commands will be run even 1513if the target file already exists. We give @file{force} target empty 1514commands to prevent @code{make} from searching for an implicit rule to 1515build it---otherwise it would apply the same match-anything rule to 1516@file{force} itself and create a prerequisite loop! 1517 1518@node Reading Makefiles, Secondary Expansion, Overriding Makefiles, Makefiles 1519@section How @code{make} Reads a Makefile 1520@cindex reading makefiles 1521@cindex makefile, parsing 1522 1523GNU @code{make} does its work in two distinct phases. During the first 1524phase it reads all the makefiles, included makefiles, etc. and 1525internalizes all the variables and their values, implicit and explicit 1526rules, and constructs a dependency graph of all the targets and their 1527prerequisites. During the second phase, @code{make} uses these internal 1528structures to determine what targets will need to be rebuilt and to 1529invoke the rules necessary to do so. 1530 1531It's important to understand this two-phase approach because it has a 1532direct impact on how variable and function expansion happens; this is 1533often a source of some confusion when writing makefiles. Here we will 1534present a summary of the phases in which expansion happens for different 1535constructs within the makefile. We say that expansion is 1536@dfn{immediate} if it happens during the first phase: in this case 1537@code{make} will expand any variables or functions in that section of a 1538construct as the makefile is parsed. We say that expansion is 1539@dfn{deferred} if expansion is not performed immediately. Expansion of 1540deferred construct is not performed until either the construct appears 1541later in an immediate context, or until the second phase. 1542 1543You may not be familiar with some of these constructs yet. You can 1544reference this section as you become familiar with them, in later 1545chapters. 1546 1547@subheading Variable Assignment 1548@cindex +=, expansion 1549@cindex =, expansion 1550@cindex ?=, expansion 1551@cindex +=, expansion 1552@cindex define, expansion 1553 1554Variable definitions are parsed as follows: 1555 1556@example 1557@var{immediate} = @var{deferred} 1558@var{immediate} ?= @var{deferred} 1559@var{immediate} := @var{immediate} 1560@var{immediate} += @var{deferred} or @var{immediate} 1561 1562define @var{immediate} 1563 @var{deferred} 1564endef 1565@end example 1566 1567For the append operator, @samp{+=}, the right-hand side is considered 1568immediate if the variable was previously set as a simple variable 1569(@samp{:=}), and deferred otherwise. 1570 1571@subheading Conditional Statements 1572@cindex ifdef, expansion 1573@cindex ifeq, expansion 1574@cindex ifndef, expansion 1575@cindex ifneq, expansion 1576 1577All instances of conditional syntax are parsed immediately, in their 1578entirety; this includes the @code{ifdef}, @code{ifeq}, @code{ifndef}, 1579and @code{ifneq} forms. Of course this means that automatic variables 1580cannot be used in conditional statements, as automatic variables are 1581not set until the command script for that rule is invoked. If you 1582need to use automatic variables in a conditional you @emph{must} use 1583shell conditional syntax, in your command script proper, for these 1584tests, not @code{make} conditionals. 1585 1586@subheading Rule Definition 1587@cindex target, expansion 1588@cindex prerequisite, expansion 1589@cindex implicit rule, expansion 1590@cindex pattern rule, expansion 1591@cindex explicit rule, expansion 1592 1593A rule is always expanded the same way, regardless of the form: 1594 1595@example 1596@var{immediate} : @var{immediate} ; @var{deferred} 1597 @var{deferred} 1598@end example 1599 1600That is, the target and prerequisite sections are expanded immediately, 1601and the commands used to construct the target are always deferred. This 1602general rule is true for explicit rules, pattern rules, suffix rules, 1603static pattern rules, and simple prerequisite definitions. 1604 1605@node Secondary Expansion, , Reading Makefiles, Makefiles 1606@section Secondary Expansion 1607@cindex secondary expansion 1608@cindex expansion, secondary 1609 1610@findex .SECONDEXPANSION 1611In the previous section we learned that GNU @code{make} works in two 1612distinct phases: a read-in phase and a target-update phase 1613(@pxref{Reading Makefiles, , How @code{make} Reads a Makefile}). GNU 1614make also has the ability to enable a @emph{second expansion} of the 1615prerequisites (only) for some or all targets defined in the makefile. 1616In order for this second expansion to occur, the special target 1617@code{.SECONDEXPANSION} must be defined before the first prerequisite 1618list that makes use of this feature. 1619 1620If that special target is defined then in between the two phases 1621mentioned above, right at the end of the read-in phase, all the 1622prerequisites of the targets defined after the special target are 1623expanded a @emph{second time}. In most circumstances this secondary 1624expansion will have no effect, since all variable and function 1625references will have been expanded during the initial parsing of the 1626makefiles. In order to take advantage of the secondary expansion 1627phase of the parser, then, it's necessary to @emph{escape} the 1628variable or function reference in the makefile. In this case the 1629first expansion merely un-escapes the reference but doesn't expand it, 1630and expansion is left to the secondary expansion phase. For example, 1631consider this makefile: 1632 1633@example 1634.SECONDEXPANSION: 1635ONEVAR = onefile 1636TWOVAR = twofile 1637myfile: $(ONEVAR) $$(TWOVAR) 1638@end example 1639 1640After the first expansion phase the prerequisites list of the 1641@file{myfile} target will be @code{onefile} and @code{$(TWOVAR)}; the 1642first (unescaped) variable reference to @var{ONEVAR} is expanded, 1643while the second (escaped) variable reference is simply unescaped, 1644without being recognized as a variable reference. Now during the 1645secondary expansion the first word is expanded again but since it 1646contains no variable or function references it remains the static 1647value @file{onefile}, while the second word is now a normal reference 1648to the variable @var{TWOVAR}, which is expanded to the value 1649@file{twofile}. The final result is that there are two prerequisites, 1650@file{onefile} and @file{twofile}. 1651 1652Obviously, this is not a very interesting case since the same result 1653could more easily have been achieved simply by having both variables 1654appear, unescaped, in the prerequisites list. One difference becomes 1655apparent if the variables are reset; consider this example: 1656 1657@example 1658.SECONDEXPANSION: 1659AVAR = top 1660onefile: $(AVAR) 1661twofile: $$(AVAR) 1662AVAR = bottom 1663@end example 1664 1665Here the prerequisite of @file{onefile} will be expanded immediately, 1666and resolve to the value @file{top}, while the prerequisite of 1667@file{twofile} will not be full expanded until the secondary expansion 1668and yield a value of @file{bottom}. 1669 1670This is marginally more exciting, but the true power of this feature 1671only becomes apparent when you discover that secondary expansions 1672always take place within the scope of the automatic variables for that 1673target. This means that you can use variables such as @code{$@@}, 1674@code{$*}, etc. during the second expansion and they will have their 1675expected values, just as in the command script. All you have to do is 1676defer the expansion by escaping the @code{$}. Also, secondary 1677expansion occurs for both explicit and implicit (pattern) rules. 1678Knowing this, the possible uses for this feature increase 1679dramatically. For example: 1680 1681@example 1682.SECONDEXPANSION: 1683main_OBJS := main.o try.o test.o 1684lib_OBJS := lib.o api.o 1685 1686main lib: $$($$@@_OBJS) 1687@end example 1688 1689Here, after the initial expansion the prerequisites of both the 1690@file{main} and @file{lib} targets will be @code{$($@@_OBJS)}. During 1691the secondary expansion, the @code{$@@} variable is set to the name of 1692the target and so the expansion for the @file{main} target will yield 1693@code{$(main_OBJS)}, or @code{main.o try.o test.o}, while the 1694secondary expansion for the @file{lib} target will yield 1695@code{$(lib_OBJS)}, or @code{lib.o api.o}. 1696 1697You can also mix functions here, as long as they are properly escaped: 1698 1699@example 1700main_SRCS := main.c try.c test.c 1701lib_SRCS := lib.c api.c 1702 1703.SECONDEXPANSION: 1704main lib: $$(patsubst %.c,%.o,$$($$@@_SRCS)) 1705@end example 1706 1707This version allows users to specify source files rather than object 1708files, but gives the same resulting prerequisites list as the previous 1709example. 1710 1711Evaluation of automatic variables during the secondary expansion 1712phase, especially of the target name variable @code{$$@@}, behaves 1713similarly to evaluation within command scripts. However, there are 1714some subtle differences and ``corner cases'' which come into play for 1715the different types of rule definitions that @code{make} understands. 1716The subtleties of using the different automatic variables are 1717described below. 1718 1719@subheading Secondary Expansion of Explicit Rules 1720@cindex secondary expansion and explicit rules 1721@cindex explicit rules, secondary expansion of 1722 1723During the secondary expansion of explicit rules, @code{$$@@} and 1724@code{$$%} evaluate, respectively, to the file name of the target and, 1725when the target is an archive member, the target member name. The 1726@code{$$<} variable evaluates to the first prerequisite in the first 1727rule for this target. @code{$$^} and @code{$$+} evaluate to the list 1728of all prerequisites of rules @emph{that have already appeared} for 1729the same target (@code{$$+} with repetitions and @code{$$^} 1730without). The following example will help illustrate these behaviors: 1731 1732@example 1733.SECONDEXPANSION: 1734 1735foo: foo.1 bar.1 $$< $$^ $$+ # line #1 1736 1737foo: foo.2 bar.2 $$< $$^ $$+ # line #2 1738 1739foo: foo.3 bar.3 $$< $$^ $$+ # line #3 1740@end example 1741 1742In the first prerequisite list, all three variables (@code{$$<}, 1743@code{$$^}, and @code{$$+}) expand to the empty string. In the 1744second, they will have values @code{foo.1}, @code{foo.1 bar.1}, and 1745@code{foo.1 bar.1} respectively. In the third they will have values 1746@code{foo.1}, @code{foo.1 bar.1 foo.2 bar.2}, and @code{foo.1 bar.1 1747foo.2 bar.2} respectively. 1748 1749Rules undergo secondary expansion in makefile order, except that 1750the rule with the command script is always evaluated last. 1751 1752The variables @code{$$?} and @code{$$*} are not available and expand 1753to the empty string. 1754 1755@subheading Secondary Expansion of Static Pattern Rules 1756@cindex secondary expansion and static pattern rules 1757@cindex static pattern rules, secondary expansion of 1758 1759Rules for secondary expansion of static pattern rules are identical to 1760those for explicit rules, above, with one exception: for static 1761pattern rules the @code{$$*} variable is set to the pattern stem. As 1762with explicit rules, @code{$$?} is not available and expands to the 1763empty string. 1764 1765@subheading Secondary Expansion of Implicit Rules 1766@cindex secondary expansion and implicit rules 1767@cindex implicit rules, secondary expansion of 1768 1769As @code{make} searches for an implicit rule, it substitutes the stem 1770and then performs secondary expansion for every rule with a matching 1771target pattern. The value of the automatic variables is derived in 1772the same fashion as for static pattern rules. As an example: 1773 1774@example 1775.SECONDEXPANSION: 1776 1777foo: bar 1778 1779foo foz: fo%: bo% 1780 1781%oo: $$< $$^ $$+ $$* 1782@end example 1783 1784When the implicit rule is tried for target @file{foo}, @code{$$<} 1785expands to @file{bar}, @code{$$^} expands to @file{bar boo}, 1786@code{$$+} also expands to @file{bar boo}, and @code{$$*} expands to 1787@file{f}. 1788 1789Note that the directory prefix (D), as described in @ref{Implicit Rule 1790Search, ,Implicit Rule Search Algorithm}, is appended (after 1791expansion) to all the patterns in the prerequisites list. As an 1792example: 1793 1794@example 1795.SECONDEXPANSION: 1796 1797/tmp/foo.o: 1798 1799%.o: $$(addsuffix /%.c,foo bar) foo.h 1800@end example 1801 1802The prerequisite list after the secondary expansion and directory 1803prefix reconstruction will be @file{/tmp/foo/foo.c /tmp/var/bar/foo.c 1804foo.h}. If you are not interested in this reconstruction, you can use 1805@code{$$*} instead of @code{%} in the prerequisites list. 1806 1807@node Rules, Commands, Makefiles, Top 1808@chapter Writing Rules 1809@cindex writing rules 1810@cindex rule, how to write 1811@cindex target 1812@cindex prerequisite 1813 1814A @dfn{rule} appears in the makefile and says when and how to remake 1815certain files, called the rule's @dfn{targets} (most often only one per rule). 1816It lists the other files that are the @dfn{prerequisites} of the target, and 1817@dfn{commands} to use to create or update the target. 1818 1819@cindex default goal 1820@cindex goal, default 1821The order of rules is not significant, except for determining the 1822@dfn{default goal}: the target for @code{make} to consider, if you do 1823not otherwise specify one. The default goal is the target of the first 1824rule in the first makefile. If the first rule has multiple targets, 1825only the first target is taken as the default. There are two 1826exceptions: a target starting with a period is not a default unless it 1827contains one or more slashes, @samp{/}, as well; and, a target that 1828defines a pattern rule has no effect on the default goal. 1829(@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.) 1830 1831Therefore, we usually write the makefile so that the first rule is the 1832one for compiling the entire program or all the programs described by 1833the makefile (often with a target called @samp{all}). 1834@xref{Goals, ,Arguments to Specify the Goals}. 1835 1836@menu 1837* Rule Example:: An example explained. 1838* Rule Syntax:: General syntax explained. 1839* Prerequisite Types:: There are two types of prerequisites. 1840* Wildcards:: Using wildcard characters such as `*'. 1841* Directory Search:: Searching other directories for source files. 1842* Phony Targets:: Using a target that is not a real file's name. 1843* Force Targets:: You can use a target without commands 1844 or prerequisites to mark other targets 1845 as phony. 1846* Empty Targets:: When only the date matters and the 1847 files are empty. 1848* Special Targets:: Targets with special built-in meanings. 1849* Multiple Targets:: When to make use of several targets in a rule. 1850* Multiple Rules:: How to use several rules with the same target. 1851* Static Pattern:: Static pattern rules apply to multiple targets 1852 and can vary the prerequisites according to 1853 the target name. 1854* Double-Colon:: How to use a special kind of rule to allow 1855 several independent rules for one target. 1856* Automatic Prerequisites:: How to automatically generate rules giving 1857 prerequisites from source files themselves. 1858@end menu 1859 1860@ifnottex 1861@node Rule Example, Rule Syntax, Rules, Rules 1862@section Rule Example 1863 1864Here is an example of a rule: 1865 1866@example 1867foo.o : foo.c defs.h # module for twiddling the frobs 1868 cc -c -g foo.c 1869@end example 1870 1871Its target is @file{foo.o} and its prerequisites are @file{foo.c} and 1872@file{defs.h}. It has one command, which is @samp{cc -c -g foo.c}. 1873The command line starts with a tab to identify it as a command. 1874 1875This rule says two things: 1876 1877@itemize @bullet 1878@item 1879How to decide whether @file{foo.o} is out of date: it is out of date 1880if it does not exist, or if either @file{foo.c} or @file{defs.h} is 1881more recent than it. 1882 1883@item 1884How to update the file @file{foo.o}: by running @code{cc} as stated. 1885The command does not explicitly mention @file{defs.h}, but we presume 1886that @file{foo.c} includes it, and that that is why @file{defs.h} was 1887added to the prerequisites. 1888@end itemize 1889@end ifnottex 1890 1891@node Rule Syntax, Prerequisite Types, Rule Example, Rules 1892@section Rule Syntax 1893 1894@cindex rule syntax 1895@cindex syntax of rules 1896In general, a rule looks like this: 1897 1898@example 1899@var{targets} : @var{prerequisites} 1900 @var{command} 1901 @dots{} 1902@end example 1903 1904@noindent 1905or like this: 1906 1907@example 1908@var{targets} : @var{prerequisites} ; @var{command} 1909 @var{command} 1910 @dots{} 1911@end example 1912 1913@cindex targets 1914@cindex rule targets 1915The @var{targets} are file names, separated by spaces. Wildcard 1916characters may be used (@pxref{Wildcards, ,Using Wildcard Characters 1917in File Names}) and a name of the form @file{@var{a}(@var{m})} 1918represents member @var{m} in archive file @var{a} 1919(@pxref{Archive Members, ,Archive Members as Targets}). 1920Usually there is only one 1921target per rule, but occasionally there is a reason to have more 1922(@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill 1923 1924@cindex commands 1925@cindex tab character (in commands) 1926The @var{command} lines start with a tab character. The first command may 1927appear on the line after the prerequisites, with a tab character, or may 1928appear on the same line, with a semicolon. Either way, the effect is the 1929same. There are other differences in the syntax of command lines. 1930@xref{Commands, ,Writing the Commands in Rules}. 1931 1932@cindex dollar sign (@code{$}), in rules 1933@cindex @code{$}, in rules 1934@cindex rules, and @code{$} 1935Because dollar signs are used to start @code{make} variable 1936references, if you really want a dollar sign in a target or 1937prerequisite you must write two of them, @samp{$$} (@pxref{Using 1938Variables, ,How to Use Variables}). If you have enabled secondary 1939expansion (@pxref{Secondary Expansion}) and you want a literal dollar 1940sign in the prerequisites lise, you must actually write @emph{four} 1941dollar signs (@samp{$$$$}). 1942 1943You may split a long line by inserting a backslash followed by a 1944newline, but this is not required, as @code{make} places no limit on 1945the length of a line in a makefile. 1946 1947A rule tells @code{make} two things: when the targets are out of date, 1948and how to update them when necessary. 1949 1950@cindex prerequisites 1951@cindex rule prerequisites 1952The criterion for being out of date is specified in terms of the 1953@var{prerequisites}, which consist of file names separated by spaces. 1954(Wildcards and archive members (@pxref{Archives}) are allowed here too.) 1955A target is out of date if it does not exist or if it is older than any 1956of the prerequisites (by comparison of last-modification times). The 1957idea is that the contents of the target file are computed based on 1958information in the prerequisites, so if any of the prerequisites changes, 1959the contents of the existing target file are no longer necessarily 1960valid. 1961 1962How to update is specified by @var{commands}. These are lines to be 1963executed by the shell (normally @samp{sh}), but with some extra features 1964(@pxref{Commands, ,Writing the Commands in Rules}). 1965 1966@node Prerequisite Types, Wildcards, Rule Syntax, Rules 1967@comment node-name, next, previous, up 1968@section Types of Prerequisites 1969@cindex prerequisite types 1970@cindex types of prerequisites 1971 1972@cindex prerequisites, normal 1973@cindex normal prerequisites 1974@cindex prerequisites, order-only 1975@cindex order-only prerequisites 1976There are actually two different types of prerequisites understood by 1977GNU @code{make}: normal prerequisites such as described in the 1978previous section, and @dfn{order-only} prerequisites. A normal 1979prerequisite makes two statements: first, it imposes an order of 1980execution of build commands: any commands necessary to build any of a 1981target's prerequisites will be fully executed before any commands 1982necessary to build the target. Second, it imposes a dependency 1983relationship: if any prerequisite is newer than the target, then the 1984target is considered out-of-date and must be rebuilt. 1985 1986Normally, this is exactly what you want: if a target's prerequisite is 1987updated, then the target should also be updated. 1988 1989Occasionally, however, you have a situation where you want to impose a 1990specific ordering on the rules to be invoked @emph{without} forcing 1991the target to be updated if one of those rules is executed. In that 1992case, you want to define @dfn{order-only} prerequisites. Order-only 1993prerequisites can be specified by placing a pipe symbol (@code{|}) 1994in the prerequisites list: any prerequisites to the left of the pipe 1995symbol are normal; any prerequisites to the right are order-only: 1996 1997@example 1998@var{targets} : @var{normal-prerequisites} | @var{order-only-prerequisites} 1999@end example 2000 2001The normal prerequisites section may of course be empty. Also, you 2002may still declare multiple lines of prerequisites for the same target: 2003they are appended appropriately. Note that if you declare the same 2004file to be both a normal and an order-only prerequisite, the normal 2005prerequisite takes precedence (since they are a strict superset of the 2006behavior of an order-only prerequisite). 2007 2008@node Wildcards, Directory Search, Prerequisite Types, Rules 2009@section Using Wildcard Characters in File Names 2010@cindex wildcard 2011@cindex file name with wildcards 2012@cindex globbing (wildcards) 2013 2014@cindex @code{*} (wildcard character) 2015@cindex @code{?} (wildcard character) 2016@cindex @code{[@dots{}]} (wildcard characters) 2017A single file name can specify many files using @dfn{wildcard characters}. 2018The wildcard characters in @code{make} are @samp{*}, @samp{?} and 2019@samp{[@dots{}]}, the same as in the Bourne shell. For example, @file{*.c} 2020specifies a list of all the files (in the working directory) whose names 2021end in @samp{.c}.@refill 2022 2023@cindex @code{~} (tilde) 2024@cindex tilde (@code{~}) 2025@cindex home directory 2026The character @samp{~} at the beginning of a file name also has special 2027significance. If alone, or followed by a slash, it represents your home 2028directory. For example @file{~/bin} expands to @file{/home/you/bin}. 2029If the @samp{~} is followed by a word, the string represents the home 2030directory of the user named by that word. For example @file{~john/bin} 2031expands to @file{/home/john/bin}. On systems which don't have a home 2032directory for each user (such as MS-DOS or MS-Windows), this 2033functionality can be simulated by setting the environment variable 2034@var{HOME}.@refill 2035 2036Wildcard expansion is performed by @code{make} automatically in 2037targets and in prerequisites. In commands the shell is responsible 2038for wildcard expansion. In other contexts, wildcard expansion happens 2039only if you request it explicitly with the @code{wildcard} function. 2040 2041The special significance of a wildcard character can be turned off by 2042preceding it with a backslash. Thus, @file{foo\*bar} would refer to a 2043specific file whose name consists of @samp{foo}, an asterisk, and 2044@samp{bar}.@refill 2045 2046@menu 2047* Wildcard Examples:: Several examples 2048* Wildcard Pitfall:: Problems to avoid. 2049* Wildcard Function:: How to cause wildcard expansion where 2050 it does not normally take place. 2051@end menu 2052 2053@node Wildcard Examples, Wildcard Pitfall, Wildcards, Wildcards 2054@subsection Wildcard Examples 2055 2056Wildcards can be used in the commands of a rule, where they are expanded 2057by the shell. For example, here is a rule to delete all the object files: 2058 2059@example 2060@group 2061clean: 2062 rm -f *.o 2063@end group 2064@end example 2065@cindex @code{rm} (shell command) 2066 2067Wildcards are also useful in the prerequisites of a rule. With the 2068following rule in the makefile, @samp{make print} will print all the 2069@samp{.c} files that have changed since the last time you printed them: 2070 2071@example 2072print: *.c 2073 lpr -p $? 2074 touch print 2075@end example 2076 2077@cindex @code{print} target 2078@cindex @code{lpr} (shell command) 2079@cindex @code{touch} (shell command) 2080@noindent 2081This rule uses @file{print} as an empty target file; see @ref{Empty 2082Targets, ,Empty Target Files to Record Events}. (The automatic variable 2083@samp{$?} is used to print only those files that have changed; see 2084@ref{Automatic Variables}.)@refill 2085 2086Wildcard expansion does not happen when you define a variable. Thus, if 2087you write this: 2088 2089@example 2090objects = *.o 2091@end example 2092 2093@noindent 2094then the value of the variable @code{objects} is the actual string 2095@samp{*.o}. However, if you use the value of @code{objects} in a target, 2096prerequisite or command, wildcard expansion will take place at that time. 2097To set @code{objects} to the expansion, instead use: 2098 2099@example 2100objects := $(wildcard *.o) 2101@end example 2102 2103@noindent 2104@xref{Wildcard Function}. 2105 2106@node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards 2107@subsection Pitfalls of Using Wildcards 2108@cindex wildcard pitfalls 2109@cindex pitfalls of wildcards 2110@cindex mistakes with wildcards 2111@cindex errors with wildcards 2112@cindex problems with wildcards 2113 2114Now here is an example of a naive way of using wildcard expansion, that 2115does not do what you would intend. Suppose you would like to say that the 2116executable file @file{foo} is made from all the object files in the 2117directory, and you write this: 2118 2119@example 2120objects = *.o 2121 2122foo : $(objects) 2123 cc -o foo $(CFLAGS) $(objects) 2124@end example 2125 2126@noindent 2127The value of @code{objects} is the actual string @samp{*.o}. Wildcard 2128expansion happens in the rule for @file{foo}, so that each @emph{existing} 2129@samp{.o} file becomes a prerequisite of @file{foo} and will be recompiled if 2130necessary. 2131 2132But what if you delete all the @samp{.o} files? When a wildcard matches 2133no files, it is left as it is, so then @file{foo} will depend on the 2134oddly-named file @file{*.o}. Since no such file is likely to exist, 2135@code{make} will give you an error saying it cannot figure out how to 2136make @file{*.o}. This is not what you want! 2137 2138Actually it is possible to obtain the desired result with wildcard 2139expansion, but you need more sophisticated techniques, including the 2140@code{wildcard} function and string substitution. 2141@ifnottex 2142@xref{Wildcard Function, ,The Function @code{wildcard}}. 2143@end ifnottex 2144@iftex 2145These are described in the following section. 2146@end iftex 2147 2148@cindex wildcards and MS-DOS/MS-Windows backslashes 2149@cindex backslashes in pathnames and wildcard expansion 2150 2151Microsoft operating systems (MS-DOS and MS-Windows) use backslashes to 2152separate directories in pathnames, like so: 2153 2154@example 2155 c:\foo\bar\baz.c 2156@end example 2157 2158This is equivalent to the Unix-style @file{c:/foo/bar/baz.c} (the 2159@file{c:} part is the so-called drive letter). When @code{make} runs on 2160these systems, it supports backslashes as well as the Unix-style forward 2161slashes in pathnames. However, this support does @emph{not} include the 2162wildcard expansion, where backslash is a quote character. Therefore, 2163you @emph{must} use Unix-style slashes in these cases. 2164 2165 2166@node Wildcard Function, , Wildcard Pitfall, Wildcards 2167@subsection The Function @code{wildcard} 2168@findex wildcard 2169 2170Wildcard expansion happens automatically in rules. But wildcard expansion 2171does not normally take place when a variable is set, or inside the 2172arguments of a function. If you want to do wildcard expansion in such 2173places, you need to use the @code{wildcard} function, like this: 2174 2175@example 2176$(wildcard @var{pattern}@dots{}) 2177@end example 2178 2179@noindent 2180This string, used anywhere in a makefile, is replaced by a 2181space-separated list of names of existing files that match one of the 2182given file name patterns. If no existing file name matches a pattern, 2183then that pattern is omitted from the output of the @code{wildcard} 2184function. Note that this is different from how unmatched wildcards 2185behave in rules, where they are used verbatim rather than ignored 2186(@pxref{Wildcard Pitfall}). 2187 2188One use of the @code{wildcard} function is to get a list of all the C source 2189files in a directory, like this: 2190 2191@example 2192$(wildcard *.c) 2193@end example 2194 2195We can change the list of C source files into a list of object files by 2196replacing the @samp{.c} suffix with @samp{.o} in the result, like this: 2197 2198@example 2199$(patsubst %.c,%.o,$(wildcard *.c)) 2200@end example 2201 2202@noindent 2203(Here we have used another function, @code{patsubst}. 2204@xref{Text Functions, ,Functions for String Substitution and Analysis}.)@refill 2205 2206Thus, a makefile to compile all C source files in the directory and then 2207link them together could be written as follows: 2208 2209@example 2210objects := $(patsubst %.c,%.o,$(wildcard *.c)) 2211 2212foo : $(objects) 2213 cc -o foo $(objects) 2214@end example 2215 2216@noindent 2217(This takes advantage of the implicit rule for compiling C programs, so 2218there is no need to write explicit rules for compiling the files. 2219@xref{Flavors, ,The Two Flavors of Variables}, for an explanation of 2220@samp{:=}, which is a variant of @samp{=}.) 2221 2222@node Directory Search, Phony Targets, Wildcards, Rules 2223@section Searching Directories for Prerequisites 2224@vindex VPATH 2225@findex vpath 2226@cindex vpath 2227@cindex search path for prerequisites (@code{VPATH}) 2228@cindex directory search (@code{VPATH}) 2229 2230For large systems, it is often desirable to put sources in a separate 2231directory from the binaries. The @dfn{directory search} features of 2232@code{make} facilitate this by searching several directories 2233automatically to find a prerequisite. When you redistribute the files 2234among directories, you do not need to change the individual rules, 2235just the search paths. 2236 2237@menu 2238* General Search:: Specifying a search path that applies 2239 to every prerequisite. 2240* Selective Search:: Specifying a search path 2241 for a specified class of names. 2242* Search Algorithm:: When and how search paths are applied. 2243* Commands/Search:: How to write shell commands that work together 2244 with search paths. 2245* Implicit/Search:: How search paths affect implicit rules. 2246* Libraries/Search:: Directory search for link libraries. 2247@end menu 2248 2249@node General Search, Selective Search, Directory Search, Directory Search 2250@subsection @code{VPATH}: Search Path for All Prerequisites 2251@vindex VPATH 2252 2253The value of the @code{make} variable @code{VPATH} specifies a list of 2254directories that @code{make} should search. Most often, the 2255directories are expected to contain prerequisite files that are not in the 2256current directory; however, @code{make} uses @code{VPATH} as a search 2257list for both prerequisites and targets of rules. 2258 2259Thus, if a file that is listed as a target or prerequisite does not exist 2260in the current directory, @code{make} searches the directories listed in 2261@code{VPATH} for a file with that name. If a file is found in one of 2262them, that file may become the prerequisite (see below). Rules may then 2263specify the names of files in the prerequisite list as if they all 2264existed in the current directory. @xref{Commands/Search, ,Writing Shell 2265Commands with Directory Search}. 2266 2267In the @code{VPATH} variable, directory names are separated by colons or 2268blanks. The order in which directories are listed is the order followed 2269by @code{make} in its search. (On MS-DOS and MS-Windows, semi-colons 2270are used as separators of directory names in @code{VPATH}, since the 2271colon can be used in the pathname itself, after the drive letter.) 2272 2273For example, 2274 2275@example 2276VPATH = src:../headers 2277@end example 2278 2279@noindent 2280specifies a path containing two directories, @file{src} and 2281@file{../headers}, which @code{make} searches in that order. 2282 2283With this value of @code{VPATH}, the following rule, 2284 2285@example 2286foo.o : foo.c 2287@end example 2288 2289@noindent 2290is interpreted as if it were written like this: 2291 2292@example 2293foo.o : src/foo.c 2294@end example 2295 2296@noindent 2297assuming the file @file{foo.c} does not exist in the current directory but 2298is found in the directory @file{src}. 2299 2300@node Selective Search, Search Algorithm, General Search, Directory Search 2301@subsection The @code{vpath} Directive 2302@findex vpath 2303 2304Similar to the @code{VPATH} variable, but more selective, is the 2305@code{vpath} directive (note lower case), which allows you to specify a 2306search path for a particular class of file names: those that match a 2307particular pattern. Thus you can supply certain search directories for 2308one class of file names and other directories (or none) for other file 2309names. 2310 2311There are three forms of the @code{vpath} directive: 2312 2313@table @code 2314@item vpath @var{pattern} @var{directories} 2315Specify the search path @var{directories} for file names that match 2316@var{pattern}. 2317 2318The search path, @var{directories}, is a list of directories to be 2319searched, separated by colons (semi-colons on MS-DOS and MS-Windows) or 2320blanks, just like the search path used in the @code{VPATH} variable. 2321 2322@item vpath @var{pattern} 2323Clear out the search path associated with @var{pattern}. 2324 2325@c Extra blank line makes sure this gets two lines. 2326@item vpath 2327 2328Clear all search paths previously specified with @code{vpath} directives. 2329@end table 2330 2331A @code{vpath} pattern is a string containing a @samp{%} character. The 2332string must match the file name of a prerequisite that is being searched 2333for, the @samp{%} character matching any sequence of zero or more 2334characters (as in pattern rules; @pxref{Pattern Rules, ,Defining and 2335Redefining Pattern Rules}). For example, @code{%.h} matches files that 2336end in @code{.h}. (If there is no @samp{%}, the pattern must match the 2337prerequisite exactly, which is not useful very often.) 2338 2339@cindex @code{%}, quoting in @code{vpath} 2340@cindex @code{%}, quoting with @code{\} (backslash) 2341@cindex @code{\} (backslash), to quote @code{%} 2342@cindex backslash (@code{\}), to quote @code{%} 2343@cindex quoting @code{%}, in @code{vpath} 2344@samp{%} characters in a @code{vpath} directive's pattern can be quoted 2345with preceding backslashes (@samp{\}). Backslashes that would otherwise 2346quote @samp{%} characters can be quoted with more backslashes. 2347Backslashes that quote @samp{%} characters or other backslashes are 2348removed from the pattern before it is compared to file names. Backslashes 2349that are not in danger of quoting @samp{%} characters go unmolested.@refill 2350 2351When a prerequisite fails to exist in the current directory, if the 2352@var{pattern} in a @code{vpath} directive matches the name of the 2353prerequisite file, then the @var{directories} in that directive are searched 2354just like (and before) the directories in the @code{VPATH} variable. 2355 2356For example, 2357 2358@example 2359vpath %.h ../headers 2360@end example 2361 2362@noindent 2363tells @code{make} to look for any prerequisite whose name ends in @file{.h} 2364in the directory @file{../headers} if the file is not found in the current 2365directory. 2366 2367If several @code{vpath} patterns match the prerequisite file's name, then 2368@code{make} processes each matching @code{vpath} directive one by one, 2369searching all the directories mentioned in each directive. @code{make} 2370handles multiple @code{vpath} directives in the order in which they 2371appear in the makefile; multiple directives with the same pattern are 2372independent of each other. 2373 2374@need 750 2375Thus, 2376 2377@example 2378@group 2379vpath %.c foo 2380vpath % blish 2381vpath %.c bar 2382@end group 2383@end example 2384 2385@noindent 2386will look for a file ending in @samp{.c} in @file{foo}, then 2387@file{blish}, then @file{bar}, while 2388 2389@example 2390@group 2391vpath %.c foo:bar 2392vpath % blish 2393@end group 2394@end example 2395 2396@noindent 2397will look for a file ending in @samp{.c} in @file{foo}, then 2398@file{bar}, then @file{blish}. 2399 2400@node Search Algorithm, Commands/Search, Selective Search, Directory Search 2401@subsection How Directory Searches are Performed 2402@cindex algorithm for directory search 2403@cindex directory search algorithm 2404 2405When a prerequisite is found through directory search, regardless of type 2406(general or selective), the pathname located may not be the one that 2407@code{make} actually provides you in the prerequisite list. Sometimes 2408the path discovered through directory search is thrown away. 2409 2410The algorithm @code{make} uses to decide whether to keep or abandon a 2411path found via directory search is as follows: 2412 2413@enumerate 2414@item 2415If a target file does not exist at the path specified in the makefile, 2416directory search is performed. 2417 2418@item 2419If the directory search is successful, that path is kept and this file 2420is tentatively stored as the target. 2421 2422@item 2423All prerequisites of this target are examined using this same method. 2424 2425@item 2426After processing the prerequisites, the target may or may not need to be 2427rebuilt: 2428 2429@enumerate a 2430@item 2431If the target does @emph{not} need to be rebuilt, the path to the file 2432found during directory search is used for any prerequisite lists which 2433contain this target. In short, if @code{make} doesn't need to rebuild 2434the target then you use the path found via directory search. 2435 2436@item 2437If the target @emph{does} need to be rebuilt (is out-of-date), the 2438pathname found during directory search is @emph{thrown away}, and the 2439target is rebuilt using the file name specified in the makefile. In 2440short, if @code{make} must rebuild, then the target is rebuilt locally, 2441not in the directory found via directory search. 2442@end enumerate 2443@end enumerate 2444 2445This algorithm may seem complex, but in practice it is quite often 2446exactly what you want. 2447 2448@cindex traditional directory search (GPATH) 2449@cindex directory search, traditional (GPATH) 2450Other versions of @code{make} use a simpler algorithm: if the file does 2451not exist, and it is found via directory search, then that pathname is 2452always used whether or not the target needs to be built. Thus, if the 2453target is rebuilt it is created at the pathname discovered during 2454directory search. 2455 2456@vindex GPATH 2457If, in fact, this is the behavior you want for some or all of your 2458directories, you can use the @code{GPATH} variable to indicate this to 2459@code{make}. 2460 2461@code{GPATH} has the same syntax and format as @code{VPATH} (that is, a 2462space- or colon-delimited list of pathnames). If an out-of-date target 2463is found by directory search in a directory that also appears in 2464@code{GPATH}, then that pathname is not thrown away. The target is 2465rebuilt using the expanded path. 2466 2467@node Commands/Search, Implicit/Search, Search Algorithm, Directory Search 2468@subsection Writing Shell Commands with Directory Search 2469@cindex shell command, and directory search 2470@cindex directory search (@code{VPATH}), and shell commands 2471 2472When a prerequisite is found in another directory through directory search, 2473this cannot change the commands of the rule; they will execute as written. 2474Therefore, you must write the commands with care so that they will look for 2475the prerequisite in the directory where @code{make} finds it. 2476 2477This is done with the @dfn{automatic variables} such as @samp{$^} 2478(@pxref{Automatic Variables}). 2479For instance, the value of @samp{$^} is a 2480list of all the prerequisites of the rule, including the names of 2481the directories in which they were found, and the value of 2482@samp{$@@} is the target. Thus:@refill 2483 2484@example 2485foo.o : foo.c 2486 cc -c $(CFLAGS) $^ -o $@@ 2487@end example 2488 2489@noindent 2490(The variable @code{CFLAGS} exists so you can specify flags for C 2491compilation by implicit rules; we use it here for consistency so it will 2492affect all C compilations uniformly; 2493@pxref{Implicit Variables, ,Variables Used by Implicit Rules}.) 2494 2495Often the prerequisites include header files as well, which you do not 2496want to mention in the commands. The automatic variable @samp{$<} is 2497just the first prerequisite: 2498 2499@example 2500VPATH = src:../headers 2501foo.o : foo.c defs.h hack.h 2502 cc -c $(CFLAGS) $< -o $@@ 2503@end example 2504 2505@node Implicit/Search, Libraries/Search, Commands/Search, Directory Search 2506@subsection Directory Search and Implicit Rules 2507@cindex @code{VPATH}, and implicit rules 2508@cindex directory search (@code{VPATH}), and implicit rules 2509@cindex search path for prerequisites (@code{VPATH}), and implicit rules 2510@cindex implicit rule, and directory search 2511@cindex implicit rule, and @code{VPATH} 2512@cindex rule, implicit, and directory search 2513@cindex rule, implicit, and @code{VPATH} 2514 2515The search through the directories specified in @code{VPATH} or with 2516@code{vpath} also happens during consideration of implicit rules 2517(@pxref{Implicit Rules, ,Using Implicit Rules}). 2518 2519For example, when a file @file{foo.o} has no explicit rule, @code{make} 2520considers implicit rules, such as the built-in rule to compile 2521@file{foo.c} if that file exists. If such a file is lacking in the 2522current directory, the appropriate directories are searched for it. If 2523@file{foo.c} exists (or is mentioned in the makefile) in any of the 2524directories, the implicit rule for C compilation is applied. 2525 2526The commands of implicit rules normally use automatic variables as a 2527matter of necessity; consequently they will use the file names found by 2528directory search with no extra effort. 2529 2530@node Libraries/Search, , Implicit/Search, Directory Search 2531@subsection Directory Search for Link Libraries 2532@cindex link libraries, and directory search 2533@cindex libraries for linking, directory search 2534@cindex directory search (@code{VPATH}), and link libraries 2535@cindex @code{VPATH}, and link libraries 2536@cindex search path for prerequisites (@code{VPATH}), and link libraries 2537@cindex @code{-l} (library search) 2538@cindex link libraries, patterns matching 2539@cindex @code{.LIBPATTERNS}, and link libraries 2540@vindex .LIBPATTERNS 2541 2542Directory search applies in a special way to libraries used with the 2543linker. This special feature comes into play when you write a prerequisite 2544whose name is of the form @samp{-l@var{name}}. (You can tell something 2545strange is going on here because the prerequisite is normally the name of a 2546file, and the @emph{file name} of a library generally looks like 2547@file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill 2548 2549When a prerequisite's name has the form @samp{-l@var{name}}, @code{make} 2550handles it specially by searching for the file @file{lib@var{name}.so} in 2551the current directory, in directories specified by matching @code{vpath} 2552search paths and the @code{VPATH} search path, and then in the 2553directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib} 2554(normally @file{/usr/local/lib}, but MS-DOS/MS-Windows versions of 2555@code{make} behave as if @var{prefix} is defined to be the root of the 2556DJGPP installation tree). 2557 2558If that file is not found, then the file @file{lib@var{name}.a} is 2559searched for, in the same directories as above. 2560 2561For example, if there is a @file{/usr/lib/libcurses.a} library on your 2562system (and no @file{/usr/lib/libcurses.so} file), then 2563 2564@example 2565@group 2566foo : foo.c -lcurses 2567 cc $^ -o $@@ 2568@end group 2569@end example 2570 2571@noindent 2572would cause the command @samp{cc foo.c /usr/lib/libcurses.a -o foo} to 2573be executed when @file{foo} is older than @file{foo.c} or than 2574@file{/usr/lib/libcurses.a}.@refill 2575 2576Although the default set of files to be searched for is 2577@file{lib@var{name}.so} and @file{lib@var{name}.a}, this is customizable 2578via the @code{.LIBPATTERNS} variable. Each word in the value of this 2579variable is a pattern string. When a prerequisite like 2580@samp{-l@var{name}} is seen, @code{make} will replace the percent in 2581each pattern in the list with @var{name} and perform the above directory 2582searches using that library filename. If no library is found, the next 2583word in the list will be used. 2584 2585The default value for @code{.LIBPATTERNS} is @samp{lib%.so lib%.a}, 2586which provides the default behavior described above. 2587 2588You can turn off link library expansion completely by setting this 2589variable to an empty value. 2590 2591@node Phony Targets, Force Targets, Directory Search, Rules 2592@section Phony Targets 2593@cindex phony targets 2594@cindex targets, phony 2595@cindex targets without a file 2596 2597A phony target is one that is not really the name of a file. It is just a 2598name for some commands to be executed when you make an explicit request. 2599There are two reasons to use a phony target: to avoid a conflict with 2600a file of the same name, and to improve performance. 2601 2602If you write a rule whose commands will not create the target file, the 2603commands will be executed every time the target comes up for remaking. 2604Here is an example: 2605 2606@example 2607@group 2608clean: 2609 rm *.o temp 2610@end group 2611@end example 2612 2613@noindent 2614Because the @code{rm} command does not create a file named @file{clean}, 2615probably no such file will ever exist. Therefore, the @code{rm} command 2616will be executed every time you say @samp{make clean}. 2617@cindex @code{rm} (shell command) 2618 2619@findex .PHONY 2620The phony target will cease to work if anything ever does create a file 2621named @file{clean} in this directory. Since it has no prerequisites, the 2622file @file{clean} would inevitably be considered up to date, and its 2623commands would not be executed. To avoid this problem, you can explicitly 2624declare the target to be phony, using the special target @code{.PHONY} 2625(@pxref{Special Targets, ,Special Built-in Target Names}) as follows: 2626 2627@example 2628.PHONY : clean 2629@end example 2630 2631@noindent 2632Once this is done, @samp{make clean} will run the commands regardless of 2633whether there is a file named @file{clean}. 2634 2635Since it knows that phony targets do not name actual files that could be 2636remade from other files, @code{make} skips the implicit rule search for 2637phony targets (@pxref{Implicit Rules}). This is why declaring a target 2638phony is good for performance, even if you are not worried about the 2639actual file existing. 2640 2641Thus, you first write the line that states that @code{clean} is a 2642phony target, then you write the rule, like this: 2643 2644@example 2645@group 2646.PHONY: clean 2647clean: 2648 rm *.o temp 2649@end group 2650@end example 2651 2652Another example of the usefulness of phony targets is in conjunction 2653with recursive invocations of @code{make} (for more information, see 2654@ref{Recursion, ,Recursive Use of @code{make}}). In this case the 2655makefile will often contain a variable which lists a number of 2656subdirectories to be built. One way to handle this is with one rule 2657whose command is a shell loop over the subdirectories, like this: 2658 2659@example 2660@group 2661SUBDIRS = foo bar baz 2662 2663subdirs: 2664 for dir in $(SUBDIRS); do \ 2665 $(MAKE) -C $$dir; \ 2666 done 2667@end group 2668@end example 2669 2670There are a few problems with this method, however. First, any error 2671detected in a submake is not noted by this rule, so it will continue to 2672build the rest of the directories even when one fails. This can be 2673overcome by adding shell commands to note the error and exit, but then 2674it will do so even if @code{make} is invoked with the @code{-k} option, 2675which is unfortunate. Second, and perhaps more importantly, you cannot 2676take advantage of @code{make}'s ability to build targets in parallel 2677(@pxref{Parallel, ,Parallel Execution}), since there is only one rule. 2678 2679By declaring the subdirectories as phony targets (you must do this as 2680the subdirectory obviously always exists; otherwise it won't be built) 2681you can remove these problems: 2682 2683@example 2684@group 2685SUBDIRS = foo bar baz 2686 2687.PHONY: subdirs $(SUBDIRS) 2688 2689subdirs: $(SUBDIRS) 2690 2691$(SUBDIRS): 2692 $(MAKE) -C $@@ 2693 2694foo: baz 2695@end group 2696@end example 2697 2698Here we've also declared that the @file{foo} subdirectory cannot be 2699built until after the @file{baz} subdirectory is complete; this kind of 2700relationship declaration is particularly important when attempting 2701parallel builds. 2702 2703A phony target should not be a prerequisite of a real target file; if it 2704is, its commands are run every time @code{make} goes to update that 2705file. As long as a phony target is never a prerequisite of a real 2706target, the phony target commands will be executed only when the phony 2707target is a specified goal (@pxref{Goals, ,Arguments to Specify the 2708Goals}). 2709 2710Phony targets can have prerequisites. When one directory contains multiple 2711programs, it is most convenient to describe all of the programs in one 2712makefile @file{./Makefile}. Since the target remade by default will be the 2713first one in the makefile, it is common to make this a phony target named 2714@samp{all} and give it, as prerequisites, all the individual programs. For 2715example: 2716 2717@example 2718all : prog1 prog2 prog3 2719.PHONY : all 2720 2721prog1 : prog1.o utils.o 2722 cc -o prog1 prog1.o utils.o 2723 2724prog2 : prog2.o 2725 cc -o prog2 prog2.o 2726 2727prog3 : prog3.o sort.o utils.o 2728 cc -o prog3 prog3.o sort.o utils.o 2729@end example 2730 2731@noindent 2732Now you can say just @samp{make} to remake all three programs, or 2733specify as arguments the ones to remake (as in @samp{make prog1 2734prog3}). Phoniness is not inherited: the prerequisites of a phony 2735target are not themselves phony, unless explicitly declared to be so. 2736 2737When one phony target is a prerequisite of another, it serves as a subroutine 2738of the other. For example, here @samp{make cleanall} will delete the 2739object files, the difference files, and the file @file{program}: 2740 2741@example 2742.PHONY: cleanall cleanobj cleandiff 2743 2744cleanall : cleanobj cleandiff 2745 rm program 2746 2747cleanobj : 2748 rm *.o 2749 2750cleandiff : 2751 rm *.diff 2752@end example 2753 2754@node Force Targets, Empty Targets, Phony Targets, Rules 2755@section Rules without Commands or Prerequisites 2756@cindex force targets 2757@cindex targets, force 2758@cindex @code{FORCE} 2759@cindex rule, no commands or prerequisites 2760 2761If a rule has no prerequisites or commands, and the target of the rule 2762is a nonexistent file, then @code{make} imagines this target to have 2763been updated whenever its rule is run. This implies that all targets 2764depending on this one will always have their commands run. 2765 2766An example will illustrate this: 2767 2768@example 2769@group 2770clean: FORCE 2771 rm $(objects) 2772FORCE: 2773@end group 2774@end example 2775 2776Here the target @samp{FORCE} satisfies the special conditions, so the 2777target @file{clean} that depends on it is forced to run its commands. 2778There is nothing special about the name @samp{FORCE}, but that is one name 2779commonly used this way. 2780 2781As you can see, using @samp{FORCE} this way has the same results as using 2782@samp{.PHONY: clean}. 2783 2784Using @samp{.PHONY} is more explicit and more efficient. However, 2785other versions of @code{make} do not support @samp{.PHONY}; thus 2786@samp{FORCE} appears in many makefiles. @xref{Phony Targets}. 2787 2788@node Empty Targets, Special Targets, Force Targets, Rules 2789@section Empty Target Files to Record Events 2790@cindex empty targets 2791@cindex targets, empty 2792@cindex recording events with empty targets 2793 2794The @dfn{empty target} is a variant of the phony target; it is used to hold 2795commands for an action that you request explicitly from time to time. 2796Unlike a phony target, this target file can really exist; but the file's 2797contents do not matter, and usually are empty. 2798 2799The purpose of the empty target file is to record, with its 2800last-modification time, when the rule's commands were last executed. It 2801does so because one of the commands is a @code{touch} command to update the 2802target file. 2803 2804The empty target file should have some prerequisites (otherwise it 2805doesn't make sense). When you ask to remake the empty target, the 2806commands are executed if any prerequisite is more recent than the target; 2807in other words, if a prerequisite has changed since the last time you 2808remade the target. Here is an example: 2809 2810@example 2811print: foo.c bar.c 2812 lpr -p $? 2813 touch print 2814@end example 2815@cindex @code{print} target 2816@cindex @code{lpr} (shell command) 2817@cindex @code{touch} (shell command) 2818 2819@noindent 2820With this rule, @samp{make print} will execute the @code{lpr} command if 2821either source file has changed since the last @samp{make print}. The 2822automatic variable @samp{$?} is used to print only those files that have 2823changed (@pxref{Automatic Variables}). 2824 2825@node Special Targets, Multiple Targets, Empty Targets, Rules 2826@section Special Built-in Target Names 2827@cindex special targets 2828@cindex built-in special targets 2829@cindex targets, built-in special 2830 2831Certain names have special meanings if they appear as targets. 2832 2833@table @code 2834@findex .PHONY 2835@item .PHONY 2836 2837The prerequisites of the special target @code{.PHONY} are considered to 2838be phony targets. When it is time to consider such a target, 2839@code{make} will run its commands unconditionally, regardless of 2840whether a file with that name exists or what its last-modification 2841time is. @xref{Phony Targets, ,Phony Targets}. 2842 2843@findex .SUFFIXES 2844@item .SUFFIXES 2845 2846The prerequisites of the special target @code{.SUFFIXES} are the list 2847of suffixes to be used in checking for suffix rules. 2848@xref{Suffix Rules, , Old-Fashioned Suffix Rules}. 2849 2850@findex .DEFAULT 2851@item .DEFAULT 2852 2853The commands specified for @code{.DEFAULT} are used for any target for 2854which no rules are found (either explicit rules or implicit rules). 2855@xref{Last Resort}. If @code{.DEFAULT} commands are specified, every 2856file mentioned as a prerequisite, but not as a target in a rule, will have 2857these commands executed on its behalf. @xref{Implicit Rule Search, 2858,Implicit Rule Search Algorithm}. 2859 2860@findex .PRECIOUS 2861@item .PRECIOUS 2862@cindex precious targets 2863@cindex preserving with @code{.PRECIOUS} 2864 2865The targets which @code{.PRECIOUS} depends on are given the following 2866special treatment: if @code{make} is killed or interrupted during the 2867execution of their commands, the target is not deleted. 2868@xref{Interrupts, ,Interrupting or Killing @code{make}}. Also, if the 2869target is an intermediate file, it will not be deleted after it is no 2870longer needed, as is normally done. @xref{Chained Rules, ,Chains of 2871Implicit Rules}. In this latter respect it overlaps with the 2872@code{.SECONDARY} special target. 2873 2874You can also list the target pattern of an implicit rule (such as 2875@samp{%.o}) as a prerequisite file of the special target @code{.PRECIOUS} 2876to preserve intermediate files created by rules whose target patterns 2877match that file's name. 2878 2879@findex .INTERMEDIATE 2880@item .INTERMEDIATE 2881@cindex intermediate targets, explicit 2882 2883The targets which @code{.INTERMEDIATE} depends on are treated as 2884intermediate files. @xref{Chained Rules, ,Chains of Implicit Rules}. 2885@code{.INTERMEDIATE} with no prerequisites has no effect. 2886 2887@findex .SECONDARY 2888@item .SECONDARY 2889@cindex secondary targets 2890@cindex preserving with @code{.SECONDARY} 2891 2892The targets which @code{.SECONDARY} depends on are treated as 2893intermediate files, except that they are never automatically deleted. 2894@xref{Chained Rules, ,Chains of Implicit Rules}. 2895 2896@code{.SECONDARY} with no prerequisites causes all targets to be treated 2897as secondary (i.e., no target is removed because it is considered 2898intermediate). 2899 2900@findex .SECONDEXPANSION 2901@item .SECONDEXPANSION 2902 2903If @code{.SECONDEXPANSION} is mentioned as a target anywhere in the 2904makefile, then all prerequisite lists defined @emph{after} it appears 2905will be expanded a second time after all makefiles have been read in. 2906@xref{Secondary Expansion, ,Secondary Expansion}. 2907 2908The prerequisites of the special target @code{.SUFFIXES} are the list 2909of suffixes to be used in checking for suffix rules. 2910@xref{Suffix Rules, , Old-Fashioned Suffix Rules}. 2911 2912@findex .DELETE_ON_ERROR 2913@item .DELETE_ON_ERROR 2914@cindex removing targets on failure 2915 2916If @code{.DELETE_ON_ERROR} is mentioned as a target anywhere in the 2917makefile, then @code{make} will delete the target of a rule if it has 2918changed and its commands exit with a nonzero exit status, just as it 2919does when it receives a signal. @xref{Errors, ,Errors in Commands}. 2920 2921@findex .IGNORE 2922@item .IGNORE 2923 2924If you specify prerequisites for @code{.IGNORE}, then @code{make} will 2925ignore errors in execution of the commands run for those particular 2926files. The commands for @code{.IGNORE} are not meaningful. 2927 2928If mentioned as a target with no prerequisites, @code{.IGNORE} says to 2929ignore errors in execution of commands for all files. This usage of 2930@samp{.IGNORE} is supported only for historical compatibility. Since 2931this affects every command in the makefile, it is not very useful; we 2932recommend you use the more selective ways to ignore errors in specific 2933commands. @xref{Errors, ,Errors in Commands}. 2934 2935@findex .LOW_RESOLUTION_TIME 2936@item .LOW_RESOLUTION_TIME 2937 2938If you specify prerequisites for @code{.LOW_RESOLUTION_TIME}, 2939@command{make} assumes that these files are created by commands that 2940generate low resolution time stamps. The commands for 2941@code{.LOW_RESOLUTION_TIME} are not meaningful. 2942 2943The high resolution file time stamps of many modern hosts lessen the 2944chance of @command{make} incorrectly concluding that a file is up to 2945date. Unfortunately, these hosts provide no way to set a high 2946resolution file time stamp, so commands like @samp{cp -p} that 2947explicitly set a file's time stamp must discard its subsecond part. If 2948a file is created by such a command, you should list it as a 2949prerequisite of @code{.LOW_RESOLUTION_TIME} so that @command{make} does 2950not mistakenly conclude that the file is out of date. For example: 2951 2952@example 2953@group 2954.LOW_RESOLUTION_TIME: dst 2955dst: src 2956 cp -p src dst 2957@end group 2958@end example 2959 2960Since @samp{cp -p} discards the subsecond part of @file{src}'s time 2961stamp, @file{dst} is typically slightly older than @file{src} even when 2962it is up to date. The @code{.LOW_RESOLUTION_TIME} line causes 2963@command{make} to consider @file{dst} to be up to date if its time stamp 2964is at the start of the same second that @file{src}'s time stamp is in. 2965 2966Due to a limitation of the archive format, archive member time stamps 2967are always low resolution. You need not list archive members as 2968prerequisites of @code{.LOW_RESOLUTION_TIME}, as @command{make} does this 2969automatically. 2970 2971@findex .SILENT 2972@item .SILENT 2973 2974If you specify prerequisites for @code{.SILENT}, then @code{make} will 2975not print the commands to remake those particular files before executing 2976them. The commands for @code{.SILENT} are not meaningful. 2977 2978If mentioned as a target with no prerequisites, @code{.SILENT} says not 2979to print any commands before executing them. This usage of 2980@samp{.SILENT} is supported only for historical compatibility. We 2981recommend you use the more selective ways to silence specific commands. 2982@xref{Echoing, ,Command Echoing}. If you want to silence all commands 2983for a particular run of @code{make}, use the @samp{-s} or 2984@w{@samp{--silent}} option (@pxref{Options Summary}). 2985 2986@findex .EXPORT_ALL_VARIABLES 2987@item .EXPORT_ALL_VARIABLES 2988 2989Simply by being mentioned as a target, this tells @code{make} to 2990export all variables to child processes by default. 2991@xref{Variables/Recursion, ,Communicating Variables to a 2992Sub-@code{make}}. 2993 2994@findex .NOTPARALLEL 2995@item .NOTPARALLEL 2996@cindex parallel execution, overriding 2997 2998If @code{.NOTPARALLEL} is mentioned as a target, then this invocation of 2999@code{make} will be run serially, even if the @samp{-j} option is 3000given. Any recursively invoked @code{make} command will still be run in 3001parallel (unless its makefile contains this target). Any prerequisites 3002on this target are ignored. 3003@end table 3004 3005Any defined implicit rule suffix also counts as a special target if it 3006appears as a target, and so does the concatenation of two suffixes, such 3007as @samp{.c.o}. These targets are suffix rules, an obsolete way of 3008defining implicit rules (but a way still widely used). In principle, any 3009target name could be special in this way if you break it in two and add 3010both pieces to the suffix list. In practice, suffixes normally begin with 3011@samp{.}, so these special target names also begin with @samp{.}. 3012@xref{Suffix Rules, ,Old-Fashioned Suffix Rules}. 3013 3014@node Multiple Targets, Multiple Rules, Special Targets, Rules 3015@section Multiple Targets in a Rule 3016@cindex multiple targets 3017@cindex several targets in a rule 3018@cindex targets, multiple 3019@cindex rule, with multiple targets 3020 3021A rule with multiple targets is equivalent to writing many rules, each with 3022one target, and all identical aside from that. The same commands apply to 3023all the targets, but their effects may vary because you can substitute the 3024actual target name into the command using @samp{$@@}. The rule contributes 3025the same prerequisites to all the targets also. 3026 3027This is useful in two cases. 3028 3029@itemize @bullet 3030@item 3031You want just prerequisites, no commands. For example: 3032 3033@example 3034kbd.o command.o files.o: command.h 3035@end example 3036 3037@noindent 3038gives an additional prerequisite to each of the three object files 3039mentioned. 3040 3041@item 3042Similar commands work for all the targets. The commands do not need 3043to be absolutely identical, since the automatic variable @samp{$@@} 3044can be used to substitute the particular target to be remade into the 3045commands (@pxref{Automatic Variables}). For example: 3046 3047@example 3048@group 3049bigoutput littleoutput : text.g 3050 generate text.g -$(subst output,,$@@) > $@@ 3051@end group 3052@end example 3053@findex subst 3054 3055@noindent 3056is equivalent to 3057 3058@example 3059bigoutput : text.g 3060 generate text.g -big > bigoutput 3061littleoutput : text.g 3062 generate text.g -little > littleoutput 3063@end example 3064 3065@noindent 3066Here we assume the hypothetical program @code{generate} makes two 3067types of output, one if given @samp{-big} and one if given 3068@samp{-little}. 3069@xref{Text Functions, ,Functions for String Substitution and Analysis}, 3070for an explanation of the @code{subst} function. 3071@end itemize 3072 3073Suppose you would like to vary the prerequisites according to the target, 3074much as the variable @samp{$@@} allows you to vary the commands. 3075You cannot do this with multiple targets in an ordinary rule, but you can 3076do it with a @dfn{static pattern rule}. 3077@xref{Static Pattern, ,Static Pattern Rules}. 3078 3079@node Multiple Rules, Static Pattern, Multiple Targets, Rules 3080@section Multiple Rules for One Target 3081@cindex multiple rules for one target 3082@cindex several rules for one target 3083@cindex rule, multiple for one target 3084@cindex target, multiple rules for one 3085 3086One file can be the target of several rules. All the prerequisites 3087mentioned in all the rules are merged into one list of prerequisites for 3088the target. If the target is older than any prerequisite from any rule, 3089the commands are executed. 3090 3091There can only be one set of commands to be executed for a file. If 3092more than one rule gives commands for the same file, @code{make} uses 3093the last set given and prints an error message. (As a special case, 3094if the file's name begins with a dot, no error message is printed. 3095This odd behavior is only for compatibility with other implementations 3096of @code{make}... you should avoid using it). Occasionally it is 3097useful to have the same target invoke multiple commands which are 3098defined in different parts of your makefile; you can use 3099@dfn{double-colon rules} (@pxref{Double-Colon}) for this. 3100 3101An extra rule with just prerequisites can be used to give a few extra 3102prerequisites to many files at once. For example, makefiles often 3103have a variable, such as @code{objects}, containing a list of all the 3104compiler output files in the system being made. An easy way to say 3105that all of them must be recompiled if @file{config.h} changes is to 3106write the following: 3107 3108@example 3109objects = foo.o bar.o 3110foo.o : defs.h 3111bar.o : defs.h test.h 3112$(objects) : config.h 3113@end example 3114 3115This could be inserted or taken out without changing the rules that really 3116specify how to make the object files, making it a convenient form to use if 3117you wish to add the additional prerequisite intermittently. 3118 3119Another wrinkle is that the additional prerequisites could be specified with 3120a variable that you set with a command argument to @code{make} 3121(@pxref{Overriding, ,Overriding Variables}). For example, 3122 3123@example 3124@group 3125extradeps= 3126$(objects) : $(extradeps) 3127@end group 3128@end example 3129 3130@noindent 3131means that the command @samp{make extradeps=foo.h} will consider 3132@file{foo.h} as a prerequisite of each object file, but plain @samp{make} 3133will not. 3134 3135If none of the explicit rules for a target has commands, then @code{make} 3136searches for an applicable implicit rule to find some commands 3137@pxref{Implicit Rules, ,Using Implicit Rules}). 3138 3139@node Static Pattern, Double-Colon, Multiple Rules, Rules 3140@section Static Pattern Rules 3141@cindex static pattern rule 3142@cindex rule, static pattern 3143@cindex pattern rules, static (not implicit) 3144@cindex varying prerequisites 3145@cindex prerequisites, varying (static pattern) 3146 3147@dfn{Static pattern rules} are rules which specify multiple targets and 3148construct the prerequisite names for each target based on the target name. 3149They are more general than ordinary rules with multiple targets because the 3150targets do not have to have identical prerequisites. Their prerequisites must 3151be @emph{analogous}, but not necessarily @emph{identical}. 3152 3153@menu 3154* Static Usage:: The syntax of static pattern rules. 3155* Static versus Implicit:: When are they better than implicit rules? 3156@end menu 3157 3158@node Static Usage, Static versus Implicit, Static Pattern, Static Pattern 3159@subsection Syntax of Static Pattern Rules 3160@cindex static pattern rule, syntax of 3161@cindex pattern rules, static, syntax of 3162 3163Here is the syntax of a static pattern rule: 3164 3165@example 3166@var{targets} @dots{}: @var{target-pattern}: @var{prereq-patterns} @dots{} 3167 @var{commands} 3168 @dots{} 3169@end example 3170 3171@noindent 3172The @var{targets} list specifies the targets that the rule applies to. 3173The targets can contain wildcard characters, just like the targets of 3174ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File 3175Names}). 3176 3177@cindex target pattern, static (not implicit) 3178@cindex stem 3179The @var{target-pattern} and @var{prereq-patterns} say how to compute the 3180prerequisites of each target. Each target is matched against the 3181@var{target-pattern} to extract a part of the target name, called the 3182@dfn{stem}. This stem is substituted into each of the @var{prereq-patterns} 3183to make the prerequisite names (one from each @var{prereq-pattern}). 3184 3185Each pattern normally contains the character @samp{%} just once. When the 3186@var{target-pattern} matches a target, the @samp{%} can match any part of 3187the target name; this part is called the @dfn{stem}. The rest of the 3188pattern must match exactly. For example, the target @file{foo.o} matches 3189the pattern @samp{%.o}, with @samp{foo} as the stem. The targets 3190@file{foo.c} and @file{foo.out} do not match that pattern.@refill 3191 3192@cindex prerequisite pattern, static (not implicit) 3193The prerequisite names for each target are made by substituting the stem 3194for the @samp{%} in each prerequisite pattern. For example, if one 3195prerequisite pattern is @file{%.c}, then substitution of the stem 3196@samp{foo} gives the prerequisite name @file{foo.c}. It is legitimate 3197to write a prerequisite pattern that does not contain @samp{%}; then this 3198prerequisite is the same for all targets. 3199 3200@cindex @code{%}, quoting in static pattern 3201@cindex @code{%}, quoting with @code{\} (backslash) 3202@cindex @code{\} (backslash), to quote @code{%} 3203@cindex backslash (@code{\}), to quote @code{%} 3204@cindex quoting @code{%}, in static pattern 3205@samp{%} characters in pattern rules can be quoted with preceding 3206backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%} 3207characters can be quoted with more backslashes. Backslashes that quote 3208@samp{%} characters or other backslashes are removed from the pattern 3209before it is compared to file names or has a stem substituted into it. 3210Backslashes that are not in danger of quoting @samp{%} characters go 3211unmolested. For example, the pattern @file{the\%weird\\%pattern\\} has 3212@samp{the%weird\} preceding the operative @samp{%} character, and 3213@samp{pattern\\} following it. The final two backslashes are left alone 3214because they cannot affect any @samp{%} character.@refill 3215 3216Here is an example, which compiles each of @file{foo.o} and @file{bar.o} 3217from the corresponding @file{.c} file: 3218 3219@example 3220@group 3221objects = foo.o bar.o 3222 3223all: $(objects) 3224 3225$(objects): %.o: %.c 3226 $(CC) -c $(CFLAGS) $< -o $@@ 3227@end group 3228@end example 3229 3230@noindent 3231Here @samp{$<} is the automatic variable that holds the name of the 3232prerequisite and @samp{$@@} is the automatic variable that holds the name 3233of the target; see @ref{Automatic Variables}. 3234 3235Each target specified must match the target pattern; a warning is issued 3236for each target that does not. If you have a list of files, only some of 3237which will match the pattern, you can use the @code{filter} function to 3238remove nonmatching file names (@pxref{Text Functions, ,Functions for String Substitution and Analysis}): 3239 3240@example 3241files = foo.elc bar.o lose.o 3242 3243$(filter %.o,$(files)): %.o: %.c 3244 $(CC) -c $(CFLAGS) $< -o $@@ 3245$(filter %.elc,$(files)): %.elc: %.el 3246 emacs -f batch-byte-compile $< 3247@end example 3248 3249@noindent 3250In this example the result of @samp{$(filter %.o,$(files))} is 3251@file{bar.o lose.o}, and the first static pattern rule causes each of 3252these object files to be updated by compiling the corresponding C source 3253file. The result of @w{@samp{$(filter %.elc,$(files))}} is 3254@file{foo.elc}, so that file is made from @file{foo.el}.@refill 3255 3256Another example shows how to use @code{$*} in static pattern rules: 3257@vindex $*@r{, and static pattern} 3258 3259@example 3260@group 3261bigoutput littleoutput : %output : text.g 3262 generate text.g -$* > $@@ 3263@end group 3264@end example 3265 3266@noindent 3267When the @code{generate} command is run, @code{$*} will expand to the 3268stem, either @samp{big} or @samp{little}. 3269 3270@node Static versus Implicit, , Static Usage, Static Pattern 3271@subsection Static Pattern Rules versus Implicit Rules 3272@cindex rule, static pattern versus implicit 3273@cindex static pattern rule, versus implicit 3274 3275A static pattern rule has much in common with an implicit rule defined as a 3276pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}). 3277Both have a pattern for the target and patterns for constructing the 3278names of prerequisites. The difference is in how @code{make} decides 3279@emph{when} the rule applies. 3280 3281An implicit rule @emph{can} apply to any target that matches its pattern, 3282but it @emph{does} apply only when the target has no commands otherwise 3283specified, and only when the prerequisites can be found. If more than one 3284implicit rule appears applicable, only one applies; the choice depends on 3285the order of rules. 3286 3287By contrast, a static pattern rule applies to the precise list of targets 3288that you specify in the rule. It cannot apply to any other target and it 3289invariably does apply to each of the targets specified. If two conflicting 3290rules apply, and both have commands, that's an error. 3291 3292The static pattern rule can be better than an implicit rule for these 3293reasons: 3294 3295@itemize @bullet 3296@item 3297You may wish to override the usual implicit rule for a few 3298files whose names cannot be categorized syntactically but 3299can be given in an explicit list. 3300 3301@item 3302If you cannot be sure of the precise contents of the directories 3303you are using, you may not be sure which other irrelevant files 3304might lead @code{make} to use the wrong implicit rule. The choice 3305might depend on the order in which the implicit rule search is done. 3306With static pattern rules, there is no uncertainty: each rule applies 3307to precisely the targets specified. 3308@end itemize 3309 3310@node Double-Colon, Automatic Prerequisites, Static Pattern, Rules 3311@section Double-Colon Rules 3312@cindex double-colon rules 3313@cindex rule, double-colon (@code{::}) 3314@cindex multiple rules for one target (@code{::}) 3315@cindex @code{::} rules (double-colon) 3316 3317@dfn{Double-colon} rules are rules written with @samp{::} instead of 3318@samp{:} after the target names. They are handled differently from 3319ordinary rules when the same target appears in more than one rule. 3320 3321When a target appears in multiple rules, all the rules must be the same 3322type: all ordinary, or all double-colon. If they are double-colon, each 3323of them is independent of the others. Each double-colon rule's commands 3324are executed if the target is older than any prerequisites of that rule. 3325If there are no prerequisites for that rule, its commands are always 3326executed (even if the target already exists). This can result in 3327executing none, any, or all of the double-colon rules. 3328 3329Double-colon rules with the same target are in fact completely separate 3330from one another. Each double-colon rule is processed individually, just 3331as rules with different targets are processed. 3332 3333The double-colon rules for a target are executed in the order they appear 3334in the makefile. However, the cases where double-colon rules really make 3335sense are those where the order of executing the commands would not matter. 3336 3337Double-colon rules are somewhat obscure and not often very useful; they 3338provide a mechanism for cases in which the method used to update a target 3339differs depending on which prerequisite files caused the update, and such 3340cases are rare. 3341 3342Each double-colon rule should specify commands; if it does not, an 3343implicit rule will be used if one applies. 3344@xref{Implicit Rules, ,Using Implicit Rules}. 3345 3346@node Automatic Prerequisites, , Double-Colon, Rules 3347@section Generating Prerequisites Automatically 3348@cindex prerequisites, automatic generation 3349@cindex automatic generation of prerequisites 3350@cindex generating prerequisites automatically 3351 3352In the makefile for a program, many of the rules you need to write often 3353say only that some object file depends on some header 3354file. For example, if @file{main.c} uses @file{defs.h} via an 3355@code{#include}, you would write: 3356 3357@example 3358main.o: defs.h 3359@end example 3360 3361@noindent 3362You need this rule so that @code{make} knows that it must remake 3363@file{main.o} whenever @file{defs.h} changes. You can see that for a 3364large program you would have to write dozens of such rules in your 3365makefile. And, you must always be very careful to update the makefile 3366every time you add or remove an @code{#include}. 3367@cindex @code{#include} 3368 3369@cindex @code{-M} (to compiler) 3370To avoid this hassle, most modern C compilers can write these rules for 3371you, by looking at the @code{#include} lines in the source files. 3372Usually this is done with the @samp{-M} option to the compiler. 3373For example, the command: 3374 3375@example 3376cc -M main.c 3377@end example 3378 3379@noindent 3380generates the output: 3381 3382@example 3383main.o : main.c defs.h 3384@end example 3385 3386@noindent 3387Thus you no longer have to write all those rules yourself. 3388The compiler will do it for you. 3389 3390Note that such a prerequisite constitutes mentioning @file{main.o} in a 3391makefile, so it can never be considered an intermediate file by implicit 3392rule search. This means that @code{make} won't ever remove the file 3393after using it; @pxref{Chained Rules, ,Chains of Implicit Rules}. 3394 3395@cindex @code{make depend} 3396With old @code{make} programs, it was traditional practice to use this 3397compiler feature to generate prerequisites on demand with a command like 3398@samp{make depend}. That command would create a file @file{depend} 3399containing all the automatically-generated prerequisites; then the 3400makefile could use @code{include} to read them in (@pxref{Include}). 3401 3402In GNU @code{make}, the feature of remaking makefiles makes this 3403practice obsolete---you need never tell @code{make} explicitly to 3404regenerate the prerequisites, because it always regenerates any makefile 3405that is out of date. @xref{Remaking Makefiles}. 3406 3407The practice we recommend for automatic prerequisite generation is to have 3408one makefile corresponding to each source file. For each source file 3409@file{@var{name}.c} there is a makefile @file{@var{name}.d} which lists 3410what files the object file @file{@var{name}.o} depends on. That way 3411only the source files that have changed need to be rescanned to produce 3412the new prerequisites. 3413 3414Here is the pattern rule to generate a file of prerequisites (i.e., a makefile) 3415called @file{@var{name}.d} from a C source file called @file{@var{name}.c}: 3416 3417@smallexample 3418@group 3419%.d: %.c 3420 @@set -e; rm -f $@@; \ 3421 $(CC) -M $(CPPFLAGS) $< > $@@.$$$$; \ 3422 sed 's,\($*\)\.o[ :]*,\1.o $@@ : ,g' < $@@.$$$$ > $@@; \ 3423 rm -f $@@.$$$$ 3424@end group 3425@end smallexample 3426 3427@noindent 3428@xref{Pattern Rules}, for information on defining pattern rules. The 3429@samp{-e} flag to the shell causes it to exit immediately if the 3430@code{$(CC)} command (or any other command) fails (exits with a 3431nonzero status). 3432@cindex @code{-e} (shell flag) 3433 3434@cindex @code{-MM} (to GNU compiler) 3435With the GNU C compiler, you may wish to use the @samp{-MM} flag instead 3436of @samp{-M}. This omits prerequisites on system header files. 3437@xref{Preprocessor Options, , Options Controlling the Preprocessor, 3438gcc.info, Using GNU CC}, for details. 3439 3440@cindex @code{sed} (shell command) 3441The purpose of the @code{sed} command is to translate (for example): 3442 3443@example 3444main.o : main.c defs.h 3445@end example 3446 3447@noindent 3448into: 3449 3450@example 3451main.o main.d : main.c defs.h 3452@end example 3453 3454@noindent 3455@cindex @code{.d} 3456This makes each @samp{.d} file depend on all the source and header files 3457that the corresponding @samp{.o} file depends on. @code{make} then 3458knows it must regenerate the prerequisites whenever any of the source or 3459header files changes. 3460 3461Once you've defined the rule to remake the @samp{.d} files, 3462you then use the @code{include} directive to read them all in. 3463@xref{Include}. For example: 3464 3465@example 3466@group 3467sources = foo.c bar.c 3468 3469include $(sources:.c=.d) 3470@end group 3471@end example 3472 3473@noindent 3474(This example uses a substitution variable reference to translate the 3475list of source files @samp{foo.c bar.c} into a list of prerequisite 3476makefiles, @samp{foo.d bar.d}. @xref{Substitution Refs}, for full 3477information on substitution references.) Since the @samp{.d} files are 3478makefiles like any others, @code{make} will remake them as necessary 3479with no further work from you. @xref{Remaking Makefiles}. 3480 3481Note that the @samp{.d} files contain target definitions; you should 3482be sure to place the @code{include} directive @emph{after} the first, 3483default goal in your makefiles or run the risk of having a random 3484object file become the default goal. 3485@xref{How Make Works}. 3486 3487@node Commands, Using Variables, Rules, Top 3488@chapter Writing the Commands in Rules 3489@cindex commands, how to write 3490@cindex rule commands 3491@cindex writing rule commands 3492 3493The commands of a rule consist of one or more shell command lines to 3494be executed, one at a time, in the order they appear. Typically, the 3495result of executing these commands is that the target of the rule is 3496brought up to date. 3497 3498Users use many different shell programs, but commands in makefiles are 3499always interpreted by @file{/bin/sh} unless the makefile specifies 3500otherwise. @xref{Execution, ,Command Execution}. 3501 3502@menu 3503* Command Syntax:: Command syntax features and pitfalls. 3504* Echoing:: How to control when commands are echoed. 3505* Execution:: How commands are executed. 3506* Parallel:: How commands can be executed in parallel. 3507* Errors:: What happens after a command execution error. 3508* Interrupts:: What happens when a command is interrupted. 3509* Recursion:: Invoking @code{make} from makefiles. 3510* Sequences:: Defining canned sequences of commands. 3511* Empty Commands:: Defining useful, do-nothing commands. 3512@end menu 3513 3514@node Command Syntax, Echoing, Commands, Commands 3515@section Command Syntax 3516@cindex command syntax 3517@cindex syntax of commands 3518 3519Makefiles have the unusual property that there are really two distinct 3520syntaxes in one file. Most of the makefile uses @code{make} syntax 3521(@pxref{Makefiles, ,Writing Makefiles}). However, commands are meant to be 3522interpreted by the shell and so they are written using shell syntax. 3523The @code{make} program does not try to understand shell syntax: it 3524performs only a very few specific translations on the content of the 3525command before handing it to the shell. 3526 3527Each command line must start with a tab, except that the first command 3528line may be attached to the target-and-prerequisites line with a 3529semicolon in between. @emph{Any} line in the makefile that begins 3530with a tab and appears in a ``rule context'' (that is, after a rule 3531has been started until another rule or variable definition) will be 3532considered a command line for that rule. Blank lines and lines of 3533just comments may appear among the command lines; they are ignored. 3534 3535Some consequences of these rules include: 3536 3537@itemize @bullet 3538@item 3539A blank line that begins with a tab is not blank: it's an empty 3540command (@pxref{Empty Commands}). 3541 3542@cindex comments, in commands 3543@cindex commands, comments in 3544@cindex @code{#} (comments), in commands 3545@item 3546A comment in a command line is not a @code{make} comment; it will be 3547passed to the shell as-is. Whether the shell treats it as a comment 3548or not depends on your shell. 3549 3550@item 3551A variable definition in a ``rule context'' which is indented by a tab 3552as the first character on the line, will be considered a command line, 3553not a @code{make} variable definition, and passed to the shell. 3554 3555@item 3556A conditional expression (@code{ifdef}, @code{ifeq}, 3557etc. @pxref{Conditional Syntax, ,Syntax of Conditionals}) in a ``rule 3558context'' which is indented by a tab as the first character on the 3559line, will be considered a command line and be passed to the shell. 3560 3561@end itemize 3562 3563@menu 3564* Splitting Lines:: Breaking long command lines for readability. 3565* Variables in Commands:: Using @code{make} variables in commands. 3566@end menu 3567 3568@node Splitting Lines, Variables in Commands, Command Syntax, Command Syntax 3569@subsection Splitting Command Lines 3570@cindex commands, splitting 3571@cindex splitting commands 3572@cindex commands, backslash (@code{\}) in 3573@cindex commands, quoting newlines in 3574@cindex backslash (@code{\}), in commands 3575@cindex @code{\} (backslash), in commands 3576@cindex quoting newline, in commands 3577@cindex newline, quoting, in commands 3578 3579One of the few ways in which @code{make} does interpret command lines 3580is checking for a backslash just before the newline. As in normal 3581makefile syntax, a single command can be split into multiple lines in 3582the makefile by placing a backslash before each newline. A sequence 3583of lines like this is considered a single command, and one instance of 3584the shell will be invoked to run it. 3585 3586However, in contrast to how they are treated in other places in a 3587makefile, backslash-newline pairs are @emph{not} removed from the 3588command. Both the backslash and the newline characters are preserved 3589and passed to the shell. How the backslash-newline is interpreted 3590depends on your shell. If the first character of the next line 3591after the backslash-newline is a tab, then that tab (and only that 3592tab) is removed. Whitespace is never added to the command. 3593 3594For example, this makefile: 3595 3596@example 3597@group 3598all : 3599 @@echo no\ 3600space 3601 @@echo no\ 3602 space 3603 @@echo one \ 3604 space 3605 @@echo one\ 3606 space 3607@end group 3608@end example 3609 3610@noindent 3611consists of four separate shell commands where the output is: 3612 3613@example 3614@group 3615nospace 3616nospace 3617one space 3618one space 3619@end group 3620@end example 3621 3622As a more complex example, this makefile: 3623 3624@example 3625@group 3626all : ; @@echo 'hello \ 3627 world' ; echo "hello \ 3628 world" 3629@end group 3630@end example 3631 3632@noindent 3633will run one shell with a command script of: 3634 3635@example 3636@group 3637echo 'hello \ 3638world' ; echo "hello \ 3639 world" 3640@end group 3641@end example 3642 3643@noindent 3644which, according to shell quoting rules, will yield the following output: 3645 3646@example 3647@group 3648hello \ 3649world 3650hello world 3651@end group 3652@end example 3653 3654@noindent 3655Notice how the backslash/newline pair was removed inside the string quoted 3656with double quotes (@code{"..."}), but not from the string quoted with single 3657quotes (@code{'...'}). This is the way the default shell (@file{/bin/sh}) 3658handles backslash/newline pairs. If you specify a different shell in your 3659makefiles it may treat them differently. 3660 3661Sometimes you want to split a long line inside of single quotes, but 3662you don't want the backslash-newline to appear in the quoted content. 3663This is often the case when passing scripts to languages such as Perl, 3664where extraneous backslashes inside the script can change its meaning 3665or even be a syntax error. One simple way of handling this is to 3666place the quoted string, or even the entire command, into a 3667@code{make} variable then use the variable in the command. In this 3668situation the newline quoting rules for makefiles will be used, and 3669the backslash-newline will be removed. If we rewrite our example 3670above using this method: 3671 3672@example 3673@group 3674HELLO = 'hello \ 3675world' 3676 3677all : ; @@echo $(HELLO) 3678@end group 3679@end example 3680 3681@noindent 3682we will get output like this: 3683 3684@example 3685@group 3686hello world 3687@end group 3688@end example 3689 3690If you like, you can also use target-specific variables 3691(@pxref{Target-specific, ,Target-specific Variable Values}) to obtain 3692a tighter correspondence between the variable and the command that 3693uses it. 3694 3695@node Variables in Commands, , Splitting Lines, Command Syntax 3696@subsection Using Variables in Commands 3697@cindex variable references in commands 3698@cindex commands, using variables in 3699 3700The other way in which @code{make} processes commands is by expanding 3701any variable references in them (@pxref{Reference,Basics of Variable 3702References}). This occurs after make has finished reading all the 3703makefiles and the target is determined to be out of date; so, the 3704commands for targets which are not rebuilt are never expanded. 3705 3706Variable and function references in commands have identical syntax and 3707semantics to references elsewhere in the makefile. They also have the 3708same quoting rules: if you want a dollar sign to appear in your 3709command, you must double it (@samp{$$}). For shells like the default 3710shell, that use dollar signs to introduce variables, it's important to 3711keep clear in your mind whether the variable you want to reference is 3712a @code{make} variable (use a single dollar sign) or a shell variable 3713(use two dollar signs). For example: 3714 3715@example 3716@group 3717LIST = one two three 3718all: 3719 for i in $(LIST); do \ 3720 echo $$i; \ 3721 done 3722@end group 3723@end example 3724 3725@noindent 3726results in the following command being passed to the shell: 3727 3728@example 3729@group 3730for i in one two three; do \ 3731 echo $i; \ 3732done 3733@end group 3734@end example 3735 3736@noindent 3737which generates the expected result: 3738 3739@example 3740@group 3741one 3742two 3743three 3744@end group 3745@end example 3746 3747@node Echoing, Execution, Command Syntax, Commands 3748@section Command Echoing 3749@cindex echoing of commands 3750@cindex silent operation 3751@cindex @code{@@} (in commands) 3752@cindex commands, echoing 3753@cindex printing of commands 3754 3755Normally @code{make} prints each command line before it is executed. 3756We call this @dfn{echoing} because it gives the appearance that you 3757are typing the commands yourself. 3758 3759When a line starts with @samp{@@}, the echoing of that line is suppressed. 3760The @samp{@@} is discarded before the command is passed to the shell. 3761Typically you would use this for a command whose only effect is to print 3762something, such as an @code{echo} command to indicate progress through 3763the makefile: 3764 3765@example 3766@@echo About to make distribution files 3767@end example 3768 3769@cindex @code{-n} 3770@cindex @code{--just-print} 3771@cindex @code{--dry-run} 3772@cindex @code{--recon} 3773When @code{make} is given the flag @samp{-n} or @samp{--just-print} 3774it only echoes commands, it won't execute them. @xref{Options Summary, 3775,Summary of Options}. In this case and only this case, even the 3776commands starting with @samp{@@} are printed. This flag is useful for 3777finding out which commands @code{make} thinks are necessary without 3778actually doing them. 3779 3780@cindex @code{-s} 3781@cindex @code{--silent} 3782@cindex @code{--quiet} 3783@findex .SILENT 3784The @samp{-s} or @samp{--silent} 3785flag to @code{make} prevents all echoing, as if all commands 3786started with @samp{@@}. A rule in the makefile for the special target 3787@code{.SILENT} without prerequisites has the same effect 3788(@pxref{Special Targets, ,Special Built-in Target Names}). 3789@code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill 3790 3791@node Execution, Parallel, Echoing, Commands 3792@section Command Execution 3793@cindex commands, execution 3794@cindex execution, of commands 3795@cindex shell command, execution 3796@vindex @code{SHELL} @r{(command execution)} 3797 3798When it is time to execute commands to update a target, they are 3799executed by invoking a new subshell for each command line. (In 3800practice, @code{make} may take shortcuts that do not affect the 3801results.) 3802 3803@cindex @code{cd} (shell command) 3804@cindex shell variables, setting in commands 3805@cindex commands setting shell variables 3806@strong{Please note:} this implies that setting shell variables and 3807invoking shell commands such as @code{cd} that set a context local to 3808each process will not affect the following command lines.@footnote{On 3809MS-DOS, the value of current working directory is @strong{global}, so 3810changing it @emph{will} affect the following command lines on those 3811systems.} If you want to use @code{cd} to affect the next statement, 3812put both statements in a single command line. Then @code{make} will 3813invoke one shell to run the entire line, and the shell will execute 3814the statements in sequence. For example: 3815 3816@example 3817foo : bar/lose 3818 cd $(@@D) && gobble $(@@F) > ../$@@ 3819@end example 3820 3821@noindent 3822Here we use the shell AND operator (@code{&&}) so that if the 3823@code{cd} command fails, the script will fail without trying to invoke 3824the @code{gobble} command in the wrong directory, which could cause 3825problems (in this case it would certainly cause @file{../foo} to be 3826truncated, at least). 3827 3828@menu 3829* Choosing the Shell:: How @code{make} chooses the shell used 3830 to run commands. 3831@end menu 3832 3833@node Choosing the Shell, , Execution, Execution 3834@subsection Choosing the Shell 3835@cindex shell, choosing the 3836@cindex @code{SHELL}, value of 3837 3838@vindex SHELL 3839The program used as the shell is taken from the variable @code{SHELL}. 3840If this variable is not set in your makefile, the program 3841@file{/bin/sh} is used as the shell. 3842 3843@cindex environment, @code{SHELL} in 3844Unlike most variables, the variable @code{SHELL} is never set from the 3845environment. This is because the @code{SHELL} environment variable is 3846used to specify your personal choice of shell program for interactive 3847use. It would be very bad for personal choices like this to affect the 3848functioning of makefiles. @xref{Environment, ,Variables from the 3849Environment}. 3850 3851Furthermore, when you do set @code{SHELL} in your makefile that value 3852is @emph{not} exported in the environment to commands that @code{make} 3853invokes. Instead, the value inherited from the user's environment, if 3854any, is exported. You can override this behavior by explicitly 3855exporting @code{SHELL} (@pxref{Variables/Recursion, ,Communicating 3856Variables to a Sub-@code{make}}), forcing it to be passed in the 3857environment to commands. 3858 3859@vindex @code{MAKESHELL} @r{(MS-DOS alternative to @code{SHELL})} 3860However, on MS-DOS and MS-Windows the value of @code{SHELL} in the 3861environment @strong{is} used, since on those systems most users do not 3862set this variable, and therefore it is most likely set specifically to 3863be used by @code{make}. On MS-DOS, if the setting of @code{SHELL} is 3864not suitable for @code{make}, you can set the variable 3865@code{MAKESHELL} to the shell that @code{make} should use; if set it 3866will be used as the shell instead of the value of @code{SHELL}. 3867 3868@subsubheading Choosing a Shell in DOS and Windows 3869@cindex shell, in DOS and Windows 3870@cindex DOS, choosing a shell in 3871@cindex Windows, choosing a shell in 3872 3873Choosing a shell in MS-DOS and MS-Windows is much more complex than on 3874other systems. 3875 3876@vindex COMSPEC 3877On MS-DOS, if @code{SHELL} is not set, the value of the variable 3878@code{COMSPEC} (which is always set) is used instead. 3879 3880@cindex @code{SHELL}, MS-DOS specifics 3881The processing of lines that set the variable @code{SHELL} in Makefiles 3882is different on MS-DOS. The stock shell, @file{command.com}, is 3883ridiculously limited in its functionality and many users of @code{make} 3884tend to install a replacement shell. Therefore, on MS-DOS, @code{make} 3885examines the value of @code{SHELL}, and changes its behavior based on 3886whether it points to a Unix-style or DOS-style shell. This allows 3887reasonable functionality even if @code{SHELL} points to 3888@file{command.com}. 3889 3890If @code{SHELL} points to a Unix-style shell, @code{make} on MS-DOS 3891additionally checks whether that shell can indeed be found; if not, it 3892ignores the line that sets @code{SHELL}. In MS-DOS, GNU @code{make} 3893searches for the shell in the following places: 3894 3895@enumerate 3896@item 3897In the precise place pointed to by the value of @code{SHELL}. For 3898example, if the makefile specifies @samp{SHELL = /bin/sh}, @code{make} 3899will look in the directory @file{/bin} on the current drive. 3900 3901@item 3902In the current directory. 3903 3904@item 3905In each of the directories in the @code{PATH} variable, in order. 3906 3907@end enumerate 3908 3909In every directory it examines, @code{make} will first look for the 3910specific file (@file{sh} in the example above). If this is not found, 3911it will also look in that directory for that file with one of the known 3912extensions which identify executable files. For example @file{.exe}, 3913@file{.com}, @file{.bat}, @file{.btm}, @file{.sh}, and some others. 3914 3915If any of these attempts is successful, the value of @code{SHELL} will 3916be set to the full pathname of the shell as found. However, if none of 3917these is found, the value of @code{SHELL} will not be changed, and thus 3918the line that sets it will be effectively ignored. This is so 3919@code{make} will only support features specific to a Unix-style shell if 3920such a shell is actually installed on the system where @code{make} runs. 3921 3922Note that this extended search for the shell is limited to the cases 3923where @code{SHELL} is set from the Makefile; if it is set in the 3924environment or command line, you are expected to set it to the full 3925pathname of the shell, exactly as things are on Unix. 3926 3927The effect of the above DOS-specific processing is that a Makefile that 3928contains @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work 3929on MS-DOS unaltered if you have e.g.@: @file{sh.exe} installed in some 3930directory along your @code{PATH}. 3931 3932@node Parallel, Errors, Execution, Commands 3933@section Parallel Execution 3934@cindex commands, execution in parallel 3935@cindex parallel execution 3936@cindex execution, in parallel 3937@cindex job slots 3938@cindex @code{-j} 3939@cindex @code{--jobs} 3940 3941GNU @code{make} knows how to execute several commands at once. 3942Normally, @code{make} will execute only one command at a time, waiting 3943for it to finish before executing the next. However, the @samp{-j} or 3944@samp{--jobs} option tells @code{make} to execute many commands 3945simultaneously.@refill 3946 3947On MS-DOS, the @samp{-j} option has no effect, since that system doesn't 3948support multi-processing. 3949 3950If the @samp{-j} option is followed by an integer, this is the number of 3951commands to execute at once; this is called the number of @dfn{job slots}. 3952If there is nothing looking like an integer after the @samp{-j} option, 3953there is no limit on the number of job slots. The default number of job 3954slots is one, which means serial execution (one thing at a time). 3955 3956One unpleasant consequence of running several commands simultaneously is 3957that output generated by the commands appears whenever each command 3958sends it, so messages from different commands may be interspersed. 3959 3960Another problem is that two processes cannot both take input from the 3961same device; so to make sure that only one command tries to take input 3962from the terminal at once, @code{make} will invalidate the standard 3963input streams of all but one running command. This means that 3964attempting to read from standard input will usually be a fatal error (a 3965@samp{Broken pipe} signal) for most child processes if there are 3966several. 3967@cindex broken pipe 3968@cindex standard input 3969 3970It is unpredictable which command will have a valid standard input stream 3971(which will come from the terminal, or wherever you redirect the standard 3972input of @code{make}). The first command run will always get it first, and 3973the first command started after that one finishes will get it next, and so 3974on. 3975 3976We will change how this aspect of @code{make} works if we find a better 3977alternative. In the mean time, you should not rely on any command using 3978standard input at all if you are using the parallel execution feature; but 3979if you are not using this feature, then standard input works normally in 3980all commands. 3981 3982Finally, handling recursive @code{make} invocations raises issues. For 3983more information on this, see 3984@ref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}. 3985 3986If a command fails (is killed by a signal or exits with a nonzero 3987status), and errors are not ignored for that command 3988(@pxref{Errors, ,Errors in Commands}), 3989the remaining command lines to remake the same target will not be run. 3990If a command fails and the @samp{-k} or @samp{--keep-going} 3991option was not given 3992(@pxref{Options Summary, ,Summary of Options}), 3993@code{make} aborts execution. If make 3994terminates for any reason (including a signal) with child processes 3995running, it waits for them to finish before actually exiting.@refill 3996 3997@cindex load average 3998@cindex limiting jobs based on load 3999@cindex jobs, limiting based on load 4000@cindex @code{-l} (load average) 4001@cindex @code{--max-load} 4002@cindex @code{--load-average} 4003When the system is heavily loaded, you will probably want to run fewer jobs 4004than when it is lightly loaded. You can use the @samp{-l} option to tell 4005@code{make} to limit the number of jobs to run at once, based on the load 4006average. The @samp{-l} or @samp{--max-load} 4007option is followed by a floating-point number. For 4008example, 4009 4010@example 4011-l 2.5 4012@end example 4013 4014@noindent 4015will not let @code{make} start more than one job if the load average is 4016above 2.5. The @samp{-l} option with no following number removes the 4017load limit, if one was given with a previous @samp{-l} option.@refill 4018 4019More precisely, when @code{make} goes to start up a job, and it already has 4020at least one job running, it checks the current load average; if it is not 4021lower than the limit given with @samp{-l}, @code{make} waits until the load 4022average goes below that limit, or until all the other jobs finish. 4023 4024By default, there is no load limit. 4025 4026@node Errors, Interrupts, Parallel, Commands 4027@section Errors in Commands 4028@cindex errors (in commands) 4029@cindex commands, errors in 4030@cindex exit status (errors) 4031 4032After each shell command returns, @code{make} looks at its exit status. 4033If the command completed successfully, the next command line is executed 4034in a new shell; after the last command line is finished, the rule is 4035finished. 4036 4037If there is an error (the exit status is nonzero), @code{make} gives up on 4038the current rule, and perhaps on all rules. 4039 4040Sometimes the failure of a certain command does not indicate a problem. 4041For example, you may use the @code{mkdir} command to ensure that a 4042directory exists. If the directory already exists, @code{mkdir} will 4043report an error, but you probably want @code{make} to continue regardless. 4044 4045@cindex @code{-} (in commands) 4046To ignore errors in a command line, write a @samp{-} at the beginning of 4047the line's text (after the initial tab). The @samp{-} is discarded before 4048the command is passed to the shell for execution. 4049 4050For example, 4051 4052@example 4053@group 4054clean: 4055 -rm -f *.o 4056@end group 4057@end example 4058@cindex @code{rm} (shell command) 4059 4060@noindent 4061This causes @code{rm} to continue even if it is unable to remove a file. 4062 4063@cindex @code{-i} 4064@cindex @code{--ignore-errors} 4065@findex .IGNORE 4066When you run @code{make} with the @samp{-i} or @samp{--ignore-errors} 4067flag, errors are ignored in all commands of all rules. A rule in the 4068makefile for the special target @code{.IGNORE} has the same effect, if 4069there are no prerequisites. These ways of ignoring errors are obsolete 4070because @samp{-} is more flexible. 4071 4072When errors are to be ignored, because of either a @samp{-} or the 4073@samp{-i} flag, @code{make} treats an error return just like success, 4074except that it prints out a message that tells you the status code 4075the command exited with, and says that the error has been ignored. 4076 4077When an error happens that @code{make} has not been told to ignore, 4078it implies that the current target cannot be correctly remade, and neither 4079can any other that depends on it either directly or indirectly. No further 4080commands will be executed for these targets, since their preconditions 4081have not been achieved. 4082 4083 4084@cindex @code{-k} 4085@cindex @code{--keep-going} 4086Normally @code{make} gives up immediately in this circumstance, returning a 4087nonzero status. However, if the @samp{-k} or @samp{--keep-going} 4088flag is specified, @code{make} 4089continues to consider the other prerequisites of the pending targets, 4090remaking them if necessary, before it gives up and returns nonzero status. 4091For example, after an error in compiling one object file, @samp{make -k} 4092will continue compiling other object files even though it already knows 4093that linking them will be impossible. @xref{Options Summary, ,Summary of Options}. 4094 4095The usual behavior assumes that your purpose is to get the specified 4096targets up to date; once @code{make} learns that this is impossible, it 4097might as well report the failure immediately. The @samp{-k} option says 4098that the real purpose is to test as many of the changes made in the 4099program as possible, perhaps to find several independent problems so 4100that you can correct them all before the next attempt to compile. This 4101is why Emacs' @code{compile} command passes the @samp{-k} flag by 4102default. 4103@cindex Emacs (@code{M-x compile}) 4104 4105@findex .DELETE_ON_ERROR 4106@cindex deletion of target files 4107@cindex removal of target files 4108@cindex target, deleting on error 4109Usually when a command fails, if it has changed the target file at all, 4110the file is corrupted and cannot be used---or at least it is not 4111completely updated. Yet the file's time stamp says that it is now up to 4112date, so the next time @code{make} runs, it will not try to update that 4113file. The situation is just the same as when the command is killed by a 4114signal; @pxref{Interrupts}. So generally the right thing to do is to 4115delete the target file if the command fails after beginning to change 4116the file. @code{make} will do this if @code{.DELETE_ON_ERROR} appears 4117as a target. This is almost always what you want @code{make} to do, but 4118it is not historical practice; so for compatibility, you must explicitly 4119request it. 4120 4121@node Interrupts, Recursion, Errors, Commands 4122@section Interrupting or Killing @code{make} 4123@cindex interrupt 4124@cindex signal 4125@cindex deletion of target files 4126@cindex removal of target files 4127@cindex target, deleting on interrupt 4128@cindex killing (interruption) 4129 4130If @code{make} gets a fatal signal while a command is executing, it may 4131delete the target file that the command was supposed to update. This is 4132done if the target file's last-modification time has changed since 4133@code{make} first checked it. 4134 4135The purpose of deleting the target is to make sure that it is remade from 4136scratch when @code{make} is next run. Why is this? Suppose you type 4137@kbd{Ctrl-c} while a compiler is running, and it has begun to write an 4138object file @file{foo.o}. The @kbd{Ctrl-c} kills the compiler, resulting 4139in an incomplete file whose last-modification time is newer than the source 4140file @file{foo.c}. But @code{make} also receives the @kbd{Ctrl-c} signal 4141and deletes this incomplete file. If @code{make} did not do this, the next 4142invocation of @code{make} would think that @file{foo.o} did not require 4143updating---resulting in a strange error message from the linker when it 4144tries to link an object file half of which is missing. 4145 4146@findex .PRECIOUS 4147You can prevent the deletion of a target file in this way by making the 4148special target @code{.PRECIOUS} depend on it. Before remaking a target, 4149@code{make} checks to see whether it appears on the prerequisites of 4150@code{.PRECIOUS}, and thereby decides whether the target should be deleted 4151if a signal happens. Some reasons why you might do this are that the 4152target is updated in some atomic fashion, or exists only to record a 4153modification-time (its contents do not matter), or must exist at all 4154times to prevent other sorts of trouble. 4155 4156@node Recursion, Sequences, Interrupts, Commands 4157@section Recursive Use of @code{make} 4158@cindex recursion 4159@cindex subdirectories, recursion for 4160 4161Recursive use of @code{make} means using @code{make} as a command in a 4162makefile. This technique is useful when you want separate makefiles for 4163various subsystems that compose a larger system. For example, suppose you 4164have a subdirectory @file{subdir} which has its own makefile, and you would 4165like the containing directory's makefile to run @code{make} on the 4166subdirectory. You can do it by writing this: 4167 4168@example 4169subsystem: 4170 cd subdir && $(MAKE) 4171@end example 4172 4173@noindent 4174or, equivalently, this (@pxref{Options Summary, ,Summary of Options}): 4175 4176@example 4177subsystem: 4178 $(MAKE) -C subdir 4179@end example 4180@cindex @code{-C} 4181@cindex @code{--directory} 4182 4183You can write recursive @code{make} commands just by copying this example, 4184but there are many things to know about how they work and why, and about 4185how the sub-@code{make} relates to the top-level @code{make}. You may 4186also find it useful to declare targets that invoke recursive 4187@code{make} commands as @samp{.PHONY} (for more discussion on when 4188this is useful, see @ref{Phony Targets}). 4189 4190@vindex @code{CURDIR} 4191For your convenience, when GNU @code{make} starts (after it has 4192processed any @code{-C} options) it sets the variable @code{CURDIR} to 4193the pathname of the current working directory. This value is never 4194touched by @code{make} again: in particular note that if you include 4195files from other directories the value of @code{CURDIR} does not 4196change. The value has the same precedence it would have if it were 4197set in the makefile (by default, an environment variable @code{CURDIR} 4198will not override this value). Note that setting this variable has no 4199impact on the operation of @code{make} (it does not cause @code{make} 4200to change its working directory, for example). 4201 4202@menu 4203* MAKE Variable:: The special effects of using @samp{$(MAKE)}. 4204* Variables/Recursion:: How to communicate variables to a sub-@code{make}. 4205* Options/Recursion:: How to communicate options to a sub-@code{make}. 4206* -w Option:: How the @samp{-w} or @samp{--print-directory} option 4207 helps debug use of recursive @code{make} commands. 4208@end menu 4209 4210@node MAKE Variable, Variables/Recursion, Recursion, Recursion 4211@subsection How the @code{MAKE} Variable Works 4212@vindex MAKE 4213@cindex recursion, and @code{MAKE} variable 4214 4215Recursive @code{make} commands should always use the variable @code{MAKE}, 4216not the explicit command name @samp{make}, as shown here: 4217 4218@example 4219@group 4220subsystem: 4221 cd subdir && $(MAKE) 4222@end group 4223@end example 4224 4225The value of this variable is the file name with which @code{make} was 4226invoked. If this file name was @file{/bin/make}, then the command executed 4227is @samp{cd subdir && /bin/make}. If you use a special version of 4228@code{make} to run the top-level makefile, the same special version will be 4229executed for recursive invocations. 4230@cindex @code{cd} (shell command) 4231 4232@cindex +, and commands 4233As a special feature, using the variable @code{MAKE} in the commands of 4234a rule alters the effects of the @samp{-t} (@samp{--touch}), @samp{-n} 4235(@samp{--just-print}), or @samp{-q} (@w{@samp{--question}}) option. 4236Using the @code{MAKE} variable has the same effect as using a @samp{+} 4237character at the beginning of the command line. @xref{Instead of 4238Execution, ,Instead of Executing the Commands}. This special feature 4239is only enabled if the @code{MAKE} variable appears directly in the 4240command script: it does not apply if the @code{MAKE} variable is 4241referenced through expansion of another variable. In the latter case 4242you must use the @samp{+} token to get these special effects.@refill 4243 4244Consider the command @samp{make -t} in the above example. (The 4245@samp{-t} option marks targets as up to date without actually running 4246any commands; see @ref{Instead of Execution}.) Following the usual 4247definition of @samp{-t}, a @samp{make -t} command in the example would 4248create a file named @file{subsystem} and do nothing else. What you 4249really want it to do is run @samp{@w{cd subdir &&} @w{make -t}}; but that would 4250require executing the command, and @samp{-t} says not to execute 4251commands.@refill 4252@cindex @code{-t}, and recursion 4253@cindex recursion, and @code{-t} 4254@cindex @code{--touch}, and recursion 4255 4256The special feature makes this do what you want: whenever a command 4257line of a rule contains the variable @code{MAKE}, the flags @samp{-t}, 4258@samp{-n} and @samp{-q} do not apply to that line. Command lines 4259containing @code{MAKE} are executed normally despite the presence of a 4260flag that causes most commands not to be run. The usual 4261@code{MAKEFLAGS} mechanism passes the flags to the sub-@code{make} 4262(@pxref{Options/Recursion, ,Communicating Options to a 4263Sub-@code{make}}), so your request to touch the files, or print the 4264commands, is propagated to the subsystem.@refill 4265 4266@node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion 4267@subsection Communicating Variables to a Sub-@code{make} 4268@cindex sub-@code{make} 4269@cindex environment, and recursion 4270@cindex exporting variables 4271@cindex variables, environment 4272@cindex variables, exporting 4273@cindex recursion, and environment 4274@cindex recursion, and variables 4275 4276Variable values of the top-level @code{make} can be passed to the 4277sub-@code{make} through the environment by explicit request. These 4278variables are defined in the sub-@code{make} as defaults, but do not 4279override what is specified in the makefile used by the sub-@code{make} 4280makefile unless you use the @samp{-e} switch (@pxref{Options Summary, 4281,Summary of Options}).@refill 4282 4283To pass down, or @dfn{export}, a variable, @code{make} adds the variable 4284and its value to the environment for running each command. The 4285sub-@code{make}, in turn, uses the environment to initialize its table 4286of variable values. @xref{Environment, ,Variables from the 4287Environment}. 4288 4289Except by explicit request, @code{make} exports a variable only if it 4290is either defined in the environment initially or set on the command 4291line, and if its name consists only of letters, numbers, and underscores. 4292Some shells cannot cope with environment variable names consisting of 4293characters other than letters, numbers, and underscores. 4294 4295@cindex SHELL, exported value 4296The value of the @code{make} variable @code{SHELL} is not exported. 4297Instead, the value of the @code{SHELL} variable from the invoking 4298environment is passed to the sub-@code{make}. You can force 4299@code{make} to export its value for @code{SHELL} by using the 4300@code{export} directive, described below. @xref{Choosing the Shell}. 4301 4302The special variable @code{MAKEFLAGS} is always exported (unless you 4303unexport it). @code{MAKEFILES} is exported if you set it to anything. 4304 4305@code{make} automatically passes down variable values that were defined 4306on the command line, by putting them in the @code{MAKEFLAGS} variable. 4307@iftex 4308See the next section. 4309@end iftex 4310@ifnottex 4311@xref{Options/Recursion}. 4312@end ifnottex 4313 4314Variables are @emph{not} normally passed down if they were created by 4315default by @code{make} (@pxref{Implicit Variables, ,Variables Used by 4316Implicit Rules}). The sub-@code{make} will define these for 4317itself.@refill 4318 4319@findex export 4320If you want to export specific variables to a sub-@code{make}, use the 4321@code{export} directive, like this: 4322 4323@example 4324export @var{variable} @dots{} 4325@end example 4326 4327@noindent 4328@findex unexport 4329If you want to @emph{prevent} a variable from being exported, use the 4330@code{unexport} directive, like this: 4331 4332@example 4333unexport @var{variable} @dots{} 4334@end example 4335 4336@noindent 4337In both of these forms, the arguments to @code{export} and 4338@code{unexport} are expanded, and so could be variables or functions 4339which expand to a (list of) variable names to be (un)exported. 4340 4341As a convenience, you can define a variable and export it at the same 4342time by doing: 4343 4344@example 4345export @var{variable} = value 4346@end example 4347 4348@noindent 4349has the same result as: 4350 4351@example 4352@var{variable} = value 4353export @var{variable} 4354@end example 4355 4356@noindent 4357and 4358 4359@example 4360export @var{variable} := value 4361@end example 4362 4363@noindent 4364has the same result as: 4365 4366@example 4367@var{variable} := value 4368export @var{variable} 4369@end example 4370 4371Likewise, 4372 4373@example 4374export @var{variable} += value 4375@end example 4376 4377@noindent 4378is just like: 4379 4380@example 4381@var{variable} += value 4382export @var{variable} 4383@end example 4384 4385@noindent 4386@xref{Appending, ,Appending More Text to Variables}. 4387 4388You may notice that the @code{export} and @code{unexport} directives 4389work in @code{make} in the same way they work in the shell, @code{sh}. 4390 4391If you want all variables to be exported by default, you can use 4392@code{export} by itself: 4393 4394@example 4395export 4396@end example 4397 4398@noindent 4399This tells @code{make} that variables which are not explicitly mentioned 4400in an @code{export} or @code{unexport} directive should be exported. 4401Any variable given in an @code{unexport} directive will still @emph{not} 4402be exported. If you use @code{export} by itself to export variables by 4403default, variables whose names contain characters other than 4404alphanumerics and underscores will not be exported unless specifically 4405mentioned in an @code{export} directive.@refill 4406 4407@findex .EXPORT_ALL_VARIABLES 4408The behavior elicited by an @code{export} directive by itself was the 4409default in older versions of GNU @code{make}. If your makefiles depend 4410on this behavior and you want to be compatible with old versions of 4411@code{make}, you can write a rule for the special target 4412@code{.EXPORT_ALL_VARIABLES} instead of using the @code{export} directive. 4413This will be ignored by old @code{make}s, while the @code{export} 4414directive will cause a syntax error.@refill 4415@cindex compatibility in exporting 4416 4417Likewise, you can use @code{unexport} by itself to tell @code{make} 4418@emph{not} to export variables by default. Since this is the default 4419behavior, you would only need to do this if @code{export} had been used 4420by itself earlier (in an included makefile, perhaps). You 4421@strong{cannot} use @code{export} and @code{unexport} by themselves to 4422have variables exported for some commands and not for others. The last 4423@code{export} or @code{unexport} directive that appears by itself 4424determines the behavior for the entire run of @code{make}.@refill 4425 4426@vindex MAKELEVEL 4427@cindex recursion, level of 4428As a special feature, the variable @code{MAKELEVEL} is changed when it 4429is passed down from level to level. This variable's value is a string 4430which is the depth of the level as a decimal number. The value is 4431@samp{0} for the top-level @code{make}; @samp{1} for a sub-@code{make}, 4432@samp{2} for a sub-sub-@code{make}, and so on. The incrementation 4433happens when @code{make} sets up the environment for a command.@refill 4434 4435The main use of @code{MAKELEVEL} is to test it in a conditional 4436directive (@pxref{Conditionals, ,Conditional Parts of Makefiles}); this 4437way you can write a makefile that behaves one way if run recursively and 4438another way if run directly by you.@refill 4439 4440@vindex MAKEFILES 4441You can use the variable @code{MAKEFILES} to cause all sub-@code{make} 4442commands to use additional makefiles. The value of @code{MAKEFILES} is 4443a whitespace-separated list of file names. This variable, if defined in 4444the outer-level makefile, is passed down through the environment; then 4445it serves as a list of extra makefiles for the sub-@code{make} to read 4446before the usual or specified ones. @xref{MAKEFILES Variable, ,The 4447Variable @code{MAKEFILES}}.@refill 4448 4449@node Options/Recursion, -w Option, Variables/Recursion, Recursion 4450@subsection Communicating Options to a Sub-@code{make} 4451@cindex options, and recursion 4452@cindex recursion, and options 4453 4454@vindex MAKEFLAGS 4455Flags such as @samp{-s} and @samp{-k} are passed automatically to the 4456sub-@code{make} through the variable @code{MAKEFLAGS}. This variable is 4457set up automatically by @code{make} to contain the flag letters that 4458@code{make} received. Thus, if you do @w{@samp{make -ks}} then 4459@code{MAKEFLAGS} gets the value @samp{ks}.@refill 4460 4461As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS} 4462in its environment. In response, it takes the flags from that value and 4463processes them as if they had been given as arguments. 4464@xref{Options Summary, ,Summary of Options}. 4465 4466@cindex command line variable definitions, and recursion 4467@cindex variables, command line, and recursion 4468@cindex recursion, and command line variable definitions 4469Likewise variables defined on the command line are passed to the 4470sub-@code{make} through @code{MAKEFLAGS}. Words in the value of 4471@code{MAKEFLAGS} that contain @samp{=}, @code{make} treats as variable 4472definitions just as if they appeared on the command line. 4473@xref{Overriding, ,Overriding Variables}. 4474 4475@cindex @code{-C}, and recursion 4476@cindex @code{-f}, and recursion 4477@cindex @code{-o}, and recursion 4478@cindex @code{-W}, and recursion 4479@cindex @code{--directory}, and recursion 4480@cindex @code{--file}, and recursion 4481@cindex @code{--old-file}, and recursion 4482@cindex @code{--assume-old}, and recursion 4483@cindex @code{--assume-new}, and recursion 4484@cindex @code{--new-file}, and recursion 4485@cindex recursion, and @code{-C} 4486@cindex recursion, and @code{-f} 4487@cindex recursion, and @code{-o} 4488@cindex recursion, and @code{-W} 4489The options @samp{-C}, @samp{-f}, @samp{-o}, and @samp{-W} are not put 4490into @code{MAKEFLAGS}; these options are not passed down.@refill 4491 4492@cindex @code{-j}, and recursion 4493@cindex @code{--jobs}, and recursion 4494@cindex recursion, and @code{-j} 4495@cindex job slots, and recursion 4496The @samp{-j} option is a special case (@pxref{Parallel, ,Parallel Execution}). 4497If you set it to some numeric value @samp{N} and your operating system 4498supports it (most any UNIX system will; others typically won't), the 4499parent @code{make} and all the sub-@code{make}s will communicate to 4500ensure that there are only @samp{N} jobs running at the same time 4501between them all. Note that any job that is marked recursive 4502(@pxref{Instead of Execution, ,Instead of Executing the Commands}) 4503doesn't count against the total jobs (otherwise we could get @samp{N} 4504sub-@code{make}s running and have no slots left over for any real work!) 4505 4506If your operating system doesn't support the above communication, then 4507@samp{-j 1} is always put into @code{MAKEFLAGS} instead of the value you 4508specified. This is because if the @w{@samp{-j}} option were passed down 4509to sub-@code{make}s, you would get many more jobs running in parallel 4510than you asked for. If you give @samp{-j} with no numeric argument, 4511meaning to run as many jobs as possible in parallel, this is passed 4512down, since multiple infinities are no more than one.@refill 4513 4514If you do not want to pass the other flags down, you must change the 4515value of @code{MAKEFLAGS}, like this: 4516 4517@example 4518subsystem: 4519 cd subdir && $(MAKE) MAKEFLAGS= 4520@end example 4521 4522@vindex MAKEOVERRIDES 4523The command line variable definitions really appear in the variable 4524@code{MAKEOVERRIDES}, and @code{MAKEFLAGS} contains a reference to this 4525variable. If you do want to pass flags down normally, but don't want to 4526pass down the command line variable definitions, you can reset 4527@code{MAKEOVERRIDES} to empty, like this: 4528 4529@example 4530MAKEOVERRIDES = 4531@end example 4532 4533@noindent 4534@cindex Arg list too long 4535@cindex E2BIG 4536This is not usually useful to do. However, some systems have a small 4537fixed limit on the size of the environment, and putting so much 4538information into the value of @code{MAKEFLAGS} can exceed it. If you 4539see the error message @samp{Arg list too long}, this may be the problem. 4540@findex .POSIX 4541@cindex POSIX.2 4542(For strict compliance with POSIX.2, changing @code{MAKEOVERRIDES} does 4543not affect @code{MAKEFLAGS} if the special target @samp{.POSIX} appears 4544in the makefile. You probably do not care about this.) 4545 4546@vindex MFLAGS 4547A similar variable @code{MFLAGS} exists also, for historical 4548compatibility. It has the same value as @code{MAKEFLAGS} except that it 4549does not contain the command line variable definitions, and it always 4550begins with a hyphen unless it is empty (@code{MAKEFLAGS} begins with a 4551hyphen only when it begins with an option that has no single-letter 4552version, such as @samp{--warn-undefined-variables}). @code{MFLAGS} was 4553traditionally used explicitly in the recursive @code{make} command, like 4554this: 4555 4556@example 4557subsystem: 4558 cd subdir && $(MAKE) $(MFLAGS) 4559@end example 4560 4561@noindent 4562but now @code{MAKEFLAGS} makes this usage redundant. If you want your 4563makefiles to be compatible with old @code{make} programs, use this 4564technique; it will work fine with more modern @code{make} versions too. 4565 4566@cindex setting options from environment 4567@cindex options, setting from environment 4568@cindex setting options in makefiles 4569@cindex options, setting in makefiles 4570The @code{MAKEFLAGS} variable can also be useful if you want to have 4571certain options, such as @samp{-k} (@pxref{Options Summary, ,Summary of 4572Options}), set each time you run @code{make}. You simply put a value for 4573@code{MAKEFLAGS} in your environment. You can also set @code{MAKEFLAGS} in 4574a makefile, to specify additional flags that should also be in effect for 4575that makefile. (Note that you cannot use @code{MFLAGS} this way. That 4576variable is set only for compatibility; @code{make} does not interpret a 4577value you set for it in any way.) 4578 4579When @code{make} interprets the value of @code{MAKEFLAGS} (either from the 4580environment or from a makefile), it first prepends a hyphen if the value 4581does not already begin with one. Then it chops the value into words 4582separated by blanks, and parses these words as if they were options given 4583on the command line (except that @samp{-C}, @samp{-f}, @samp{-h}, 4584@samp{-o}, @samp{-W}, and their long-named versions are ignored; and there 4585is no error for an invalid option). 4586 4587If you do put @code{MAKEFLAGS} in your environment, you should be sure not 4588to include any options that will drastically affect the actions of 4589@code{make} and undermine the purpose of makefiles and of @code{make} 4590itself. For instance, the @samp{-t}, @samp{-n}, and @samp{-q} options, if 4591put in one of these variables, could have disastrous consequences and would 4592certainly have at least surprising and probably annoying effects.@refill 4593 4594@node -w Option, , Options/Recursion, Recursion 4595@subsection The @samp{--print-directory} Option 4596@cindex directories, printing them 4597@cindex printing directories 4598@cindex recursion, and printing directories 4599 4600If you use several levels of recursive @code{make} invocations, the 4601@samp{-w} or @w{@samp{--print-directory}} option can make the output a 4602lot easier to understand by showing each directory as @code{make} 4603starts processing it and as @code{make} finishes processing it. For 4604example, if @samp{make -w} is run in the directory @file{/u/gnu/make}, 4605@code{make} will print a line of the form:@refill 4606 4607@example 4608make: Entering directory `/u/gnu/make'. 4609@end example 4610 4611@noindent 4612before doing anything else, and a line of the form: 4613 4614@example 4615make: Leaving directory `/u/gnu/make'. 4616@end example 4617 4618@noindent 4619when processing is completed. 4620 4621@cindex @code{-C}, and @code{-w} 4622@cindex @code{--directory}, and @code{--print-directory} 4623@cindex recursion, and @code{-w} 4624@cindex @code{-w}, and @code{-C} 4625@cindex @code{-w}, and recursion 4626@cindex @code{--print-directory}, and @code{--directory} 4627@cindex @code{--print-directory}, and recursion 4628@cindex @code{--no-print-directory} 4629@cindex @code{--print-directory}, disabling 4630@cindex @code{-w}, disabling 4631Normally, you do not need to specify this option because @samp{make} 4632does it for you: @samp{-w} is turned on automatically when you use the 4633@samp{-C} option, and in sub-@code{make}s. @code{make} will not 4634automatically turn on @samp{-w} if you also use @samp{-s}, which says to 4635be silent, or if you use @samp{--no-print-directory} to explicitly 4636disable it. 4637 4638@node Sequences, Empty Commands, Recursion, Commands 4639@section Defining Canned Command Sequences 4640@cindex sequences of commands 4641@cindex commands, sequences of 4642 4643When the same sequence of commands is useful in making various targets, you 4644can define it as a canned sequence with the @code{define} directive, and 4645refer to the canned sequence from the rules for those targets. The canned 4646sequence is actually a variable, so the name must not conflict with other 4647variable names. 4648 4649Here is an example of defining a canned sequence of commands: 4650 4651@example 4652define run-yacc 4653yacc $(firstword $^) 4654mv y.tab.c $@@ 4655endef 4656@end example 4657@cindex @code{yacc} 4658 4659@noindent 4660Here @code{run-yacc} is the name of the variable being defined; 4661@code{endef} marks the end of the definition; the lines in between are the 4662commands. The @code{define} directive does not expand variable references 4663and function calls in the canned sequence; the @samp{$} characters, 4664parentheses, variable names, and so on, all become part of the value of the 4665variable you are defining. 4666@xref{Defining, ,Defining Variables Verbatim}, 4667for a complete explanation of @code{define}. 4668 4669The first command in this example runs Yacc on the first prerequisite of 4670whichever rule uses the canned sequence. The output file from Yacc is 4671always named @file{y.tab.c}. The second command moves the output to the 4672rule's target file name. 4673 4674To use the canned sequence, substitute the variable into the commands of a 4675rule. You can substitute it like any other variable 4676(@pxref{Reference, ,Basics of Variable References}). 4677Because variables defined by @code{define} are recursively expanded 4678variables, all the variable references you wrote inside the @code{define} 4679are expanded now. For example: 4680 4681@example 4682foo.c : foo.y 4683 $(run-yacc) 4684@end example 4685 4686@noindent 4687@samp{foo.y} will be substituted for the variable @samp{$^} when it occurs in 4688@code{run-yacc}'s value, and @samp{foo.c} for @samp{$@@}.@refill 4689 4690This is a realistic example, but this particular one is not needed in 4691practice because @code{make} has an implicit rule to figure out these 4692commands based on the file names involved 4693(@pxref{Implicit Rules, ,Using Implicit Rules}). 4694 4695@cindex @@, and @code{define} 4696@cindex -, and @code{define} 4697@cindex +, and @code{define} 4698In command execution, each line of a canned sequence is treated just as 4699if the line appeared on its own in the rule, preceded by a tab. In 4700particular, @code{make} invokes a separate subshell for each line. You 4701can use the special prefix characters that affect command lines 4702(@samp{@@}, @samp{-}, and @samp{+}) on each line of a canned sequence. 4703@xref{Commands, ,Writing the Commands in Rules}. 4704For example, using this canned sequence: 4705 4706@example 4707define frobnicate 4708@@echo "frobnicating target $@@" 4709frob-step-1 $< -o $@@-step-1 4710frob-step-2 $@@-step-1 -o $@@ 4711endef 4712@end example 4713 4714@noindent 4715@code{make} will not echo the first line, the @code{echo} command. 4716But it @emph{will} echo the following two command lines. 4717 4718On the other hand, prefix characters on the command line that refers to 4719a canned sequence apply to every line in the sequence. So the rule: 4720 4721@example 4722frob.out: frob.in 4723 @@$(frobnicate) 4724@end example 4725 4726@noindent 4727does not echo @emph{any} commands. 4728(@xref{Echoing, ,Command Echoing}, for a full explanation of @samp{@@}.) 4729 4730@node Empty Commands, , Sequences, Commands 4731@section Using Empty Commands 4732@cindex empty commands 4733@cindex commands, empty 4734 4735It is sometimes useful to define commands which do nothing. This is done 4736simply by giving a command that consists of nothing but whitespace. For 4737example: 4738 4739@example 4740target: ; 4741@end example 4742 4743@noindent 4744defines an empty command string for @file{target}. You could also use a 4745line beginning with a tab character to define an empty command string, 4746but this would be confusing because such a line looks empty. 4747 4748@findex .DEFAULT@r{, and empty commands} 4749You may be wondering why you would want to define a command string that 4750does nothing. The only reason this is useful is to prevent a target 4751from getting implicit commands (from implicit rules or the 4752@code{.DEFAULT} special target; @pxref{Implicit Rules} and 4753@pxref{Last Resort, ,Defining Last-Resort Default Rules}).@refill 4754 4755@c !!! another reason is for canonical stamp files: 4756@ignore 4757@example 4758foo: stamp-foo ; 4759stamp-foo: foo.in 4760 create foo frm foo.in 4761 touch $@ 4762@end example 4763@end ignore 4764 4765You may be inclined to define empty command strings for targets that are 4766not actual files, but only exist so that their prerequisites can be 4767remade. However, this is not the best way to do that, because the 4768prerequisites may not be remade properly if the target file actually does exist. 4769@xref{Phony Targets, ,Phony Targets}, for a better way to do this. 4770 4771@node Using Variables, Conditionals, Commands, Top 4772@chapter How to Use Variables 4773@cindex variable 4774@cindex value 4775@cindex recursive variable expansion 4776@cindex simple variable expansion 4777 4778A @dfn{variable} is a name defined in a makefile to represent a string 4779of text, called the variable's @dfn{value}. These values are 4780substituted by explicit request into targets, prerequisites, commands, 4781and other parts of the makefile. (In some other versions of @code{make}, 4782variables are called @dfn{macros}.) 4783@cindex macro 4784 4785Variables and functions in all parts of a makefile are expanded when 4786read, except for the shell commands in rules, the right-hand sides of 4787variable definitions using @samp{=}, and the bodies of variable 4788definitions using the @code{define} directive.@refill 4789 4790Variables can represent lists of file names, options to pass to compilers, 4791programs to run, directories to look in for source files, directories to 4792write output in, or anything else you can imagine. 4793 4794A variable name may be any sequence of characters not containing @samp{:}, 4795@samp{#}, @samp{=}, or leading or trailing whitespace. However, 4796variable names containing characters other than letters, numbers, and 4797underscores should be avoided, as they may be given special meanings in the 4798future, and with some shells they cannot be passed through the environment to a 4799sub-@code{make} 4800(@pxref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}). 4801 4802Variable names are case-sensitive. The names @samp{foo}, @samp{FOO}, 4803and @samp{Foo} all refer to different variables. 4804 4805It is traditional to use upper case letters in variable names, but we 4806recommend using lower case letters for variable names that serve internal 4807purposes in the makefile, and reserving upper case for parameters that 4808control implicit rules or for parameters that the user should override with 4809command options (@pxref{Overriding, ,Overriding Variables}). 4810 4811A few variables have names that are a single punctuation character or 4812just a few characters. These are the @dfn{automatic variables}, and 4813they have particular specialized uses. @xref{Automatic Variables}. 4814 4815@menu 4816* Reference:: How to use the value of a variable. 4817* Flavors:: Variables come in two flavors. 4818* Advanced:: Advanced features for referencing a variable. 4819* Values:: All the ways variables get their values. 4820* Setting:: How to set a variable in the makefile. 4821* Appending:: How to append more text to the old value 4822 of a variable. 4823* Override Directive:: How to set a variable in the makefile even if 4824 the user has set it with a command argument. 4825* Defining:: An alternate way to set a variable 4826 to a verbatim string. 4827* Environment:: Variable values can come from the environment. 4828* Target-specific:: Variable values can be defined on a per-target 4829 basis. 4830* Pattern-specific:: Target-specific variable values can be applied 4831 to a group of targets that match a pattern. 4832@end menu 4833 4834@node Reference, Flavors, Using Variables, Using Variables 4835@section Basics of Variable References 4836@cindex variables, how to reference 4837@cindex reference to variables 4838@cindex @code{$}, in variable reference 4839@cindex dollar sign (@code{$}), in variable reference 4840 4841To substitute a variable's value, write a dollar sign followed by the name 4842of the variable in parentheses or braces: either @samp{$(foo)} or 4843@samp{$@{foo@}} is a valid reference to the variable @code{foo}. This 4844special significance of @samp{$} is why you must write @samp{$$} to have 4845the effect of a single dollar sign in a file name or command. 4846 4847Variable references can be used in any context: targets, prerequisites, 4848commands, most directives, and new variable values. Here is an 4849example of a common case, where a variable holds the names of all the 4850object files in a program: 4851 4852@example 4853@group 4854objects = program.o foo.o utils.o 4855program : $(objects) 4856 cc -o program $(objects) 4857 4858$(objects) : defs.h 4859@end group 4860@end example 4861 4862Variable references work by strict textual substitution. Thus, the rule 4863 4864@example 4865@group 4866foo = c 4867prog.o : prog.$(foo) 4868 $(foo)$(foo) -$(foo) prog.$(foo) 4869@end group 4870@end example 4871 4872@noindent 4873could be used to compile a C program @file{prog.c}. Since spaces before 4874the variable value are ignored in variable assignments, the value of 4875@code{foo} is precisely @samp{c}. (Don't actually write your makefiles 4876this way!) 4877 4878A dollar sign followed by a character other than a dollar sign, 4879open-parenthesis or open-brace treats that single character as the 4880variable name. Thus, you could reference the variable @code{x} with 4881@samp{$x}. However, this practice is strongly discouraged, except in 4882the case of the automatic variables (@pxref{Automatic Variables}). 4883 4884@node Flavors, Advanced, Reference, Using Variables 4885@section The Two Flavors of Variables 4886@cindex flavors of variables 4887@cindex recursive variable expansion 4888@cindex variables, flavors 4889@cindex recursively expanded variables 4890@cindex variables, recursively expanded 4891 4892There are two ways that a variable in GNU @code{make} can have a value; 4893we call them the two @dfn{flavors} of variables. The two flavors are 4894distinguished in how they are defined and in what they do when expanded. 4895 4896@cindex = 4897The first flavor of variable is a @dfn{recursively expanded} variable. 4898Variables of this sort are defined by lines using @samp{=} 4899(@pxref{Setting, ,Setting Variables}) or by the @code{define} directive 4900(@pxref{Defining, ,Defining Variables Verbatim}). The value you specify 4901is installed verbatim; if it contains references to other variables, 4902these references are expanded whenever this variable is substituted (in 4903the course of expanding some other string). When this happens, it is 4904called @dfn{recursive expansion}.@refill 4905 4906For example, 4907 4908@example 4909foo = $(bar) 4910bar = $(ugh) 4911ugh = Huh? 4912 4913all:;echo $(foo) 4914@end example 4915 4916@noindent 4917will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which 4918expands to @samp{$(ugh)} which finally expands to @samp{Huh?}.@refill 4919 4920This flavor of variable is the only sort supported by other versions of 4921@code{make}. It has its advantages and its disadvantages. An advantage 4922(most would say) is that: 4923 4924@example 4925CFLAGS = $(include_dirs) -O 4926include_dirs = -Ifoo -Ibar 4927@end example 4928 4929@noindent 4930will do what was intended: when @samp{CFLAGS} is expanded in a command, 4931it will expand to @samp{-Ifoo -Ibar -O}. A major disadvantage is that you 4932cannot append something on the end of a variable, as in 4933 4934@example 4935CFLAGS = $(CFLAGS) -O 4936@end example 4937 4938@noindent 4939because it will cause an infinite loop in the variable expansion. 4940(Actually @code{make} detects the infinite loop and reports an error.) 4941@cindex loops in variable expansion 4942@cindex variables, loops in expansion 4943 4944Another disadvantage is that any functions 4945(@pxref{Functions, ,Functions for Transforming Text}) 4946referenced in the definition will be executed every time the variable is 4947expanded. This makes @code{make} run slower; worse, it causes the 4948@code{wildcard} and @code{shell} functions to give unpredictable results 4949because you cannot easily control when they are called, or even how many 4950times. 4951 4952To avoid all the problems and inconveniences of recursively expanded 4953variables, there is another flavor: simply expanded variables. 4954 4955@cindex simply expanded variables 4956@cindex variables, simply expanded 4957@cindex := 4958@dfn{Simply expanded variables} are defined by lines using @samp{:=} 4959(@pxref{Setting, ,Setting Variables}). 4960The value of a simply expanded variable is scanned 4961once and for all, expanding any references to other variables and 4962functions, when the variable is defined. The actual value of the simply 4963expanded variable is the result of expanding the text that you write. 4964It does not contain any references to other variables; it contains their 4965values @emph{as of the time this variable was defined}. Therefore, 4966 4967@example 4968x := foo 4969y := $(x) bar 4970x := later 4971@end example 4972 4973@noindent 4974is equivalent to 4975 4976@example 4977y := foo bar 4978x := later 4979@end example 4980 4981When a simply expanded variable is referenced, its value is substituted 4982verbatim. 4983 4984Here is a somewhat more complicated example, illustrating the use of 4985@samp{:=} in conjunction with the @code{shell} function. 4986(@xref{Shell Function, , The @code{shell} Function}.) This example 4987also shows use of the variable @code{MAKELEVEL}, which is changed 4988when it is passed down from level to level. 4989(@xref{Variables/Recursion, , Communicating Variables to a 4990Sub-@code{make}}, for information about @code{MAKELEVEL}.) 4991 4992@vindex MAKELEVEL 4993@vindex MAKE 4994@example 4995@group 4996ifeq (0,$@{MAKELEVEL@}) 4997whoami := $(shell whoami) 4998host-type := $(shell arch) 4999MAKE := $@{MAKE@} host-type=$@{host-type@} whoami=$@{whoami@} 5000endif 5001@end group 5002@end example 5003 5004@noindent 5005An advantage of this use of @samp{:=} is that a typical 5006`descend into a directory' command then looks like this: 5007 5008@example 5009@group 5010$@{subdirs@}: 5011 $@{MAKE@} -C $@@ all 5012@end group 5013@end example 5014 5015Simply expanded variables generally make complicated makefile programming 5016more predictable because they work like variables in most programming 5017languages. They allow you to redefine a variable using its own value (or 5018its value processed in some way by one of the expansion functions) and to 5019use the expansion functions much more efficiently 5020(@pxref{Functions, ,Functions for Transforming Text}). 5021 5022@cindex spaces, in variable values 5023@cindex whitespace, in variable values 5024@cindex variables, spaces in values 5025You can also use them to introduce controlled leading whitespace into 5026variable values. Leading whitespace characters are discarded from your 5027input before substitution of variable references and function calls; 5028this means you can include leading spaces in a variable value by 5029protecting them with variable references, like this: 5030 5031@example 5032nullstring := 5033space := $(nullstring) # end of the line 5034@end example 5035 5036@noindent 5037Here the value of the variable @code{space} is precisely one space. The 5038comment @w{@samp{# end of the line}} is included here just for clarity. 5039Since trailing space characters are @emph{not} stripped from variable 5040values, just a space at the end of the line would have the same effect 5041(but be rather hard to read). If you put whitespace at the end of a 5042variable value, it is a good idea to put a comment like that at the end 5043of the line to make your intent clear. Conversely, if you do @emph{not} 5044want any whitespace characters at the end of your variable value, you 5045must remember not to put a random comment on the end of the line after 5046some whitespace, such as this: 5047 5048@example 5049dir := /foo/bar # directory to put the frobs in 5050@end example 5051 5052@noindent 5053Here the value of the variable @code{dir} is @w{@samp{/foo/bar }} 5054(with four trailing spaces), which was probably not the intention. 5055(Imagine something like @w{@samp{$(dir)/file}} with this definition!) 5056 5057@cindex conditional variable assignment 5058@cindex variables, conditional assignment 5059@cindex ?= 5060There is another assignment operator for variables, @samp{?=}. This 5061is called a conditional variable assignment operator, because it only 5062has an effect if the variable is not yet defined. This statement: 5063 5064@example 5065FOO ?= bar 5066@end example 5067 5068@noindent 5069is exactly equivalent to this 5070(@pxref{Origin Function, ,The @code{origin} Function}): 5071 5072@example 5073ifeq ($(origin FOO), undefined) 5074 FOO = bar 5075endif 5076@end example 5077 5078Note that a variable set to an empty value is still defined, so 5079@samp{?=} will not set that variable. 5080 5081@node Advanced, Values, Flavors, Using Variables 5082@section Advanced Features for Reference to Variables 5083@cindex reference to variables 5084 5085This section describes some advanced features you can use to reference 5086variables in more flexible ways. 5087 5088@menu 5089* Substitution Refs:: Referencing a variable with 5090 substitutions on the value. 5091* Computed Names:: Computing the name of the variable to refer to. 5092@end menu 5093 5094@node Substitution Refs, Computed Names, Advanced, Advanced 5095@subsection Substitution References 5096@cindex modified variable reference 5097@cindex substitution variable reference 5098@cindex variables, modified reference 5099@cindex variables, substitution reference 5100 5101@cindex variables, substituting suffix in 5102@cindex suffix, substituting in variables 5103A @dfn{substitution reference} substitutes the value of a variable with 5104alterations that you specify. It has the form 5105@samp{$(@var{var}:@var{a}=@var{b})} (or 5106@samp{$@{@var{var}:@var{a}=@var{b}@}}) and its meaning is to take the value 5107of the variable @var{var}, replace every @var{a} at the end of a word with 5108@var{b} in that value, and substitute the resulting string. 5109 5110When we say ``at the end of a word'', we mean that @var{a} must appear 5111either followed by whitespace or at the end of the value in order to be 5112replaced; other occurrences of @var{a} in the value are unaltered. For 5113example:@refill 5114 5115@example 5116foo := a.o b.o c.o 5117bar := $(foo:.o=.c) 5118@end example 5119 5120@noindent 5121sets @samp{bar} to @samp{a.c b.c c.c}. @xref{Setting, ,Setting Variables}. 5122 5123A substitution reference is actually an abbreviation for use of the 5124@code{patsubst} expansion function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}). We provide 5125substitution references as well as @code{patsubst} for compatibility with 5126other implementations of @code{make}. 5127 5128@findex patsubst 5129Another type of substitution reference lets you use the full power of 5130the @code{patsubst} function. It has the same form 5131@samp{$(@var{var}:@var{a}=@var{b})} described above, except that now 5132@var{a} must contain a single @samp{%} character. This case is 5133equivalent to @samp{$(patsubst @var{a},@var{b},$(@var{var}))}. 5134@xref{Text Functions, ,Functions for String Substitution and Analysis}, 5135for a description of the @code{patsubst} function.@refill 5136 5137@example 5138@group 5139@exdent For example: 5140 5141foo := a.o b.o c.o 5142bar := $(foo:%.o=%.c) 5143@end group 5144@end example 5145 5146@noindent 5147sets @samp{bar} to @samp{a.c b.c c.c}. 5148 5149@node Computed Names, , Substitution Refs, Advanced 5150@subsection Computed Variable Names 5151@cindex nested variable reference 5152@cindex computed variable name 5153@cindex variables, computed names 5154@cindex variables, nested references 5155@cindex variables, @samp{$} in name 5156@cindex @code{$}, in variable name 5157@cindex dollar sign (@code{$}), in variable name 5158 5159Computed variable names are a complicated concept needed only for 5160sophisticated makefile programming. For most purposes you need not 5161consider them, except to know that making a variable with a dollar sign 5162in its name might have strange results. However, if you are the type 5163that wants to understand everything, or you are actually interested in 5164what they do, read on. 5165 5166Variables may be referenced inside the name of a variable. This is 5167called a @dfn{computed variable name} or a @dfn{nested variable 5168reference}. For example, 5169 5170@example 5171x = y 5172y = z 5173a := $($(x)) 5174@end example 5175 5176@noindent 5177defines @code{a} as @samp{z}: the @samp{$(x)} inside @samp{$($(x))} expands 5178to @samp{y}, so @samp{$($(x))} expands to @samp{$(y)} which in turn expands 5179to @samp{z}. Here the name of the variable to reference is not stated 5180explicitly; it is computed by expansion of @samp{$(x)}. The reference 5181@samp{$(x)} here is nested within the outer variable reference. 5182 5183The previous example shows two levels of nesting, but any number of levels 5184is possible. For example, here are three levels: 5185 5186@example 5187x = y 5188y = z 5189z = u 5190a := $($($(x))) 5191@end example 5192 5193@noindent 5194Here the innermost @samp{$(x)} expands to @samp{y}, so @samp{$($(x))} 5195expands to @samp{$(y)} which in turn expands to @samp{z}; now we have 5196@samp{$(z)}, which becomes @samp{u}. 5197 5198References to recursively-expanded variables within a variable name are 5199reexpanded in the usual fashion. For example: 5200 5201@example 5202x = $(y) 5203y = z 5204z = Hello 5205a := $($(x)) 5206@end example 5207 5208@noindent 5209defines @code{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))} 5210which becomes @samp{$(z)} which becomes @samp{Hello}. 5211 5212Nested variable references can also contain modified references and 5213function invocations (@pxref{Functions, ,Functions for Transforming Text}), 5214just like any other reference. 5215For example, using the @code{subst} function 5216(@pxref{Text Functions, ,Functions for String Substitution and Analysis}): 5217 5218@example 5219@group 5220x = variable1 5221variable2 := Hello 5222y = $(subst 1,2,$(x)) 5223z = y 5224a := $($($(z))) 5225@end group 5226@end example 5227 5228@noindent 5229eventually defines @code{a} as @samp{Hello}. It is doubtful that anyone 5230would ever want to write a nested reference as convoluted as this one, but 5231it works: @samp{$($($(z)))} expands to @samp{$($(y))} which becomes 5232@samp{$($(subst 1,2,$(x)))}. This gets the value @samp{variable1} from 5233@code{x} and changes it by substitution to @samp{variable2}, so that the 5234entire string becomes @samp{$(variable2)}, a simple variable reference 5235whose value is @samp{Hello}.@refill 5236 5237A computed variable name need not consist entirely of a single variable 5238reference. It can contain several variable references, as well as some 5239invariant text. For example, 5240 5241@example 5242@group 5243a_dirs := dira dirb 52441_dirs := dir1 dir2 5245@end group 5246 5247@group 5248a_files := filea fileb 52491_files := file1 file2 5250@end group 5251 5252@group 5253ifeq "$(use_a)" "yes" 5254a1 := a 5255else 5256a1 := 1 5257endif 5258@end group 5259 5260@group 5261ifeq "$(use_dirs)" "yes" 5262df := dirs 5263else 5264df := files 5265endif 5266 5267dirs := $($(a1)_$(df)) 5268@end group 5269@end example 5270 5271@noindent 5272will give @code{dirs} the same value as @code{a_dirs}, @code{1_dirs}, 5273@code{a_files} or @code{1_files} depending on the settings of @code{use_a} 5274and @code{use_dirs}.@refill 5275 5276Computed variable names can also be used in substitution references: 5277 5278@example 5279@group 5280a_objects := a.o b.o c.o 52811_objects := 1.o 2.o 3.o 5282 5283sources := $($(a1)_objects:.o=.c) 5284@end group 5285@end example 5286 5287@noindent 5288defines @code{sources} as either @samp{a.c b.c c.c} or @samp{1.c 2.c 3.c}, 5289depending on the value of @code{a1}. 5290 5291The only restriction on this sort of use of nested variable references 5292is that they cannot specify part of the name of a function to be called. 5293This is because the test for a recognized function name is done before 5294the expansion of nested references. For example, 5295 5296@example 5297@group 5298ifdef do_sort 5299func := sort 5300else 5301func := strip 5302endif 5303@end group 5304 5305@group 5306bar := a d b g q c 5307@end group 5308 5309@group 5310foo := $($(func) $(bar)) 5311@end group 5312@end example 5313 5314@noindent 5315attempts to give @samp{foo} the value of the variable @samp{sort a d b g 5316q c} or @samp{strip a d b g q c}, rather than giving @samp{a d b g q c} 5317as the argument to either the @code{sort} or the @code{strip} function. 5318This restriction could be removed in the future if that change is shown 5319to be a good idea. 5320 5321You can also use computed variable names in the left-hand side of a 5322variable assignment, or in a @code{define} directive, as in: 5323 5324@example 5325dir = foo 5326$(dir)_sources := $(wildcard $(dir)/*.c) 5327define $(dir)_print 5328lpr $($(dir)_sources) 5329endef 5330@end example 5331 5332@noindent 5333This example defines the variables @samp{dir}, @samp{foo_sources}, and 5334@samp{foo_print}. 5335 5336Note that @dfn{nested variable references} are quite different from 5337@dfn{recursively expanded variables} 5338(@pxref{Flavors, ,The Two Flavors of Variables}), though both are 5339used together in complex ways when doing makefile programming.@refill 5340 5341@node Values, Setting, Advanced, Using Variables 5342@section How Variables Get Their Values 5343@cindex variables, how they get their values 5344@cindex value, how a variable gets it 5345 5346Variables can get values in several different ways: 5347 5348@itemize @bullet 5349@item 5350You can specify an overriding value when you run @code{make}. 5351@xref{Overriding, ,Overriding Variables}. 5352 5353@item 5354You can specify a value in the makefile, either 5355with an assignment (@pxref{Setting, ,Setting Variables}) or with a 5356verbatim definition (@pxref{Defining, ,Defining Variables Verbatim}).@refill 5357 5358@item 5359Variables in the environment become @code{make} variables. 5360@xref{Environment, ,Variables from the Environment}. 5361 5362@item 5363Several @dfn{automatic} variables are given new values for each rule. 5364Each of these has a single conventional use. 5365@xref{Automatic Variables}. 5366 5367@item 5368Several variables have constant initial values. 5369@xref{Implicit Variables, ,Variables Used by Implicit Rules}. 5370@end itemize 5371 5372@node Setting, Appending, Values, Using Variables 5373@section Setting Variables 5374@cindex setting variables 5375@cindex variables, setting 5376@cindex = 5377@cindex := 5378@cindex ?= 5379 5380To set a variable from the makefile, write a line starting with the 5381variable name followed by @samp{=} or @samp{:=}. Whatever follows the 5382@samp{=} or @samp{:=} on the line becomes the value. For example, 5383 5384@example 5385objects = main.o foo.o bar.o utils.o 5386@end example 5387 5388@noindent 5389defines a variable named @code{objects}. Whitespace around the variable 5390name and immediately after the @samp{=} is ignored. 5391 5392Variables defined with @samp{=} are @dfn{recursively expanded} variables. 5393Variables defined with @samp{:=} are @dfn{simply expanded} variables; these 5394definitions can contain variable references which will be expanded before 5395the definition is made. @xref{Flavors, ,The Two Flavors of Variables}. 5396 5397The variable name may contain function and variable references, which 5398are expanded when the line is read to find the actual variable name to use. 5399 5400There is no limit on the length of the value of a variable except the 5401amount of swapping space on the computer. When a variable definition is 5402long, it is a good idea to break it into several lines by inserting 5403backslash-newline at convenient places in the definition. This will not 5404affect the functioning of @code{make}, but it will make the makefile easier 5405to read. 5406 5407Most variable names are considered to have the empty string as a value if 5408you have never set them. Several variables have built-in initial values 5409that are not empty, but you can set them in the usual ways 5410(@pxref{Implicit Variables, ,Variables Used by Implicit Rules}). 5411Several special variables are set 5412automatically to a new value for each rule; these are called the 5413@dfn{automatic} variables (@pxref{Automatic Variables}). 5414 5415If you'd like a variable to be set to a value only if it's not already 5416set, then you can use the shorthand operator @samp{?=} instead of 5417@samp{=}. These two settings of the variable @samp{FOO} are identical 5418(@pxref{Origin Function, ,The @code{origin} Function}): 5419 5420@example 5421FOO ?= bar 5422@end example 5423 5424@noindent 5425and 5426 5427@example 5428ifeq ($(origin FOO), undefined) 5429FOO = bar 5430endif 5431@end example 5432 5433@node Appending, Override Directive, Setting, Using Variables 5434@section Appending More Text to Variables 5435@cindex += 5436@cindex appending to variables 5437@cindex variables, appending to 5438 5439Often it is useful to add more text to the value of a variable already defined. 5440You do this with a line containing @samp{+=}, like this: 5441 5442@example 5443objects += another.o 5444@end example 5445 5446@noindent 5447This takes the value of the variable @code{objects}, and adds the text 5448@samp{another.o} to it (preceded by a single space). Thus: 5449 5450@example 5451objects = main.o foo.o bar.o utils.o 5452objects += another.o 5453@end example 5454 5455@noindent 5456sets @code{objects} to @samp{main.o foo.o bar.o utils.o another.o}. 5457 5458Using @samp{+=} is similar to: 5459 5460@example 5461objects = main.o foo.o bar.o utils.o 5462objects := $(objects) another.o 5463@end example 5464 5465@noindent 5466but differs in ways that become important when you use more complex values. 5467 5468When the variable in question has not been defined before, @samp{+=} 5469acts just like normal @samp{=}: it defines a recursively-expanded 5470variable. However, when there @emph{is} a previous definition, exactly 5471what @samp{+=} does depends on what flavor of variable you defined 5472originally. @xref{Flavors, ,The Two Flavors of Variables}, for an 5473explanation of the two flavors of variables. 5474 5475When you add to a variable's value with @samp{+=}, @code{make} acts 5476essentially as if you had included the extra text in the initial 5477definition of the variable. If you defined it first with @samp{:=}, 5478making it a simply-expanded variable, @samp{+=} adds to that 5479simply-expanded definition, and expands the new text before appending it 5480to the old value just as @samp{:=} does 5481(see @ref{Setting, ,Setting Variables}, for a full explanation of @samp{:=}). 5482In fact, 5483 5484@example 5485variable := value 5486variable += more 5487@end example 5488 5489@noindent 5490is exactly equivalent to: 5491 5492@noindent 5493@example 5494variable := value 5495variable := $(variable) more 5496@end example 5497 5498On the other hand, when you use @samp{+=} with a variable that you defined 5499first to be recursively-expanded using plain @samp{=}, @code{make} does 5500something a bit different. Recall that when you define a 5501recursively-expanded variable, @code{make} does not expand the value you set 5502for variable and function references immediately. Instead it stores the text 5503verbatim, and saves these variable and function references to be expanded 5504later, when you refer to the new variable (@pxref{Flavors, ,The Two Flavors 5505of Variables}). When you use @samp{+=} on a recursively-expanded variable, 5506it is this unexpanded text to which @code{make} appends the new text you 5507specify. 5508 5509@example 5510@group 5511variable = value 5512variable += more 5513@end group 5514@end example 5515 5516@noindent 5517is roughly equivalent to: 5518 5519@example 5520@group 5521temp = value 5522variable = $(temp) more 5523@end group 5524@end example 5525 5526@noindent 5527except that of course it never defines a variable called @code{temp}. 5528The importance of this comes when the variable's old value contains 5529variable references. Take this common example: 5530 5531@example 5532CFLAGS = $(includes) -O 5533@dots{} 5534CFLAGS += -pg # enable profiling 5535@end example 5536 5537@noindent 5538The first line defines the @code{CFLAGS} variable with a reference to another 5539variable, @code{includes}. (@code{CFLAGS} is used by the rules for C 5540compilation; @pxref{Catalogue of Rules, ,Catalogue of Implicit Rules}.) 5541Using @samp{=} for the definition makes @code{CFLAGS} a recursively-expanded 5542variable, meaning @w{@samp{$(includes) -O}} is @emph{not} expanded when 5543@code{make} processes the definition of @code{CFLAGS}. Thus, @code{includes} 5544need not be defined yet for its value to take effect. It only has to be 5545defined before any reference to @code{CFLAGS}. If we tried to append to the 5546value of @code{CFLAGS} without using @samp{+=}, we might do it like this: 5547 5548@example 5549CFLAGS := $(CFLAGS) -pg # enable profiling 5550@end example 5551 5552@noindent 5553This is pretty close, but not quite what we want. Using @samp{:=} 5554redefines @code{CFLAGS} as a simply-expanded variable; this means 5555@code{make} expands the text @w{@samp{$(CFLAGS) -pg}} before setting the 5556variable. If @code{includes} is not yet defined, we get @w{@samp{ -O 5557-pg}}, and a later definition of @code{includes} will have no effect. 5558Conversely, by using @samp{+=} we set @code{CFLAGS} to the 5559@emph{unexpanded} value @w{@samp{$(includes) -O -pg}}. Thus we preserve 5560the reference to @code{includes}, so if that variable gets defined at 5561any later point, a reference like @samp{$(CFLAGS)} still uses its 5562value. 5563 5564@node Override Directive, Defining, Appending, Using Variables 5565@section The @code{override} Directive 5566@findex override 5567@cindex overriding with @code{override} 5568@cindex variables, overriding 5569 5570If a variable has been set with a command argument 5571(@pxref{Overriding, ,Overriding Variables}), 5572then ordinary assignments in the makefile are ignored. If you want to set 5573the variable in the makefile even though it was set with a command 5574argument, you can use an @code{override} directive, which is a line that 5575looks like this:@refill 5576 5577@example 5578override @var{variable} = @var{value} 5579@end example 5580 5581@noindent 5582or 5583 5584@example 5585override @var{variable} := @var{value} 5586@end example 5587 5588To append more text to a variable defined on the command line, use: 5589 5590@example 5591override @var{variable} += @var{more text} 5592@end example 5593 5594@noindent 5595@xref{Appending, ,Appending More Text to Variables}. 5596 5597The @code{override} directive was not invented for escalation in the war 5598between makefiles and command arguments. It was invented so you can alter 5599and add to values that the user specifies with command arguments. 5600 5601For example, suppose you always want the @samp{-g} switch when you run the 5602C compiler, but you would like to allow the user to specify the other 5603switches with a command argument just as usual. You could use this 5604@code{override} directive: 5605 5606@example 5607override CFLAGS += -g 5608@end example 5609 5610You can also use @code{override} directives with @code{define} directives. 5611This is done as you might expect: 5612 5613@example 5614override define foo 5615bar 5616endef 5617@end example 5618 5619@noindent 5620@iftex 5621See the next section for information about @code{define}. 5622@end iftex 5623@ifnottex 5624@xref{Defining, ,Defining Variables Verbatim}. 5625@end ifnottex 5626 5627@node Defining, Environment, Override Directive, Using Variables 5628@section Defining Variables Verbatim 5629@findex define 5630@findex endef 5631@cindex verbatim variable definition 5632@cindex defining variables verbatim 5633@cindex variables, defining verbatim 5634 5635Another way to set the value of a variable is to use the @code{define} 5636directive. This directive has an unusual syntax which allows newline 5637characters to be included in the value, which is convenient for defining 5638both canned sequences of commands 5639(@pxref{Sequences, ,Defining Canned Command Sequences}), and also 5640sections of makefile syntax to use with @code{eval} (@pxref{Eval Function}). 5641 5642The @code{define} directive is followed on the same line by the name of the 5643variable and nothing more. The value to give the variable appears on the 5644following lines. The end of the value is marked by a line containing just 5645the word @code{endef}. Aside from this difference in syntax, @code{define} 5646works just like @samp{=}: it creates a recursively-expanded variable 5647(@pxref{Flavors, ,The Two Flavors of Variables}). 5648The variable name may contain function and variable references, which 5649are expanded when the directive is read to find the actual variable name 5650to use. 5651 5652You may nest @code{define} directives: @code{make} will keep track of 5653nested directives and report an error if they are not all properly 5654closed with @code{endef}. Note that lines beginning with tab 5655characters are considered part of a command script, so any 5656@code{define} or @code{endef} strings appearing on such a line will 5657not be considered @code{make} operators. 5658 5659@example 5660define two-lines 5661echo foo 5662echo $(bar) 5663endef 5664@end example 5665 5666The value in an ordinary assignment cannot contain a newline; but the 5667newlines that separate the lines of the value in a @code{define} become 5668part of the variable's value (except for the final newline which precedes 5669the @code{endef} and is not considered part of the value).@refill 5670 5671@need 800 5672When used in a command script, the previous example is functionally 5673equivalent to this: 5674 5675@example 5676two-lines = echo foo; echo $(bar) 5677@end example 5678 5679@noindent 5680since two commands separated by semicolon behave much like two separate 5681shell commands. However, note that using two separate lines means 5682@code{make} will invoke the shell twice, running an independent subshell 5683for each line. @xref{Execution, ,Command Execution}. 5684 5685If you want variable definitions made with @code{define} to take 5686precedence over command-line variable definitions, you can use the 5687@code{override} directive together with @code{define}: 5688 5689@example 5690override define two-lines 5691foo 5692$(bar) 5693endef 5694@end example 5695 5696@noindent 5697@xref{Override Directive, ,The @code{override} Directive}. 5698 5699@node Environment, Target-specific, Defining, Using Variables 5700@section Variables from the Environment 5701 5702@cindex variables, environment 5703@cindex environment 5704Variables in @code{make} can come from the environment in which 5705@code{make} is run. Every environment variable that @code{make} sees 5706when it starts up is transformed into a @code{make} variable with the 5707same name and value. However, an explicit assignment in the makefile, 5708or with a command argument, overrides the environment. (If the 5709@samp{-e} flag is specified, then values from the environment override 5710assignments in the makefile. @xref{Options Summary, ,Summary of 5711Options}. But this is not recommended practice.) 5712 5713Thus, by setting the variable @code{CFLAGS} in your environment, you can 5714cause all C compilations in most makefiles to use the compiler switches you 5715prefer. This is safe for variables with standard or conventional meanings 5716because you know that no makefile will use them for other things. (Note 5717this is not totally reliable; some makefiles set @code{CFLAGS} explicitly 5718and therefore are not affected by the value in the environment.) 5719 5720When @code{make} runs a command script, variables defined in the 5721makefile are placed into the environment of that command. This allows 5722you to pass values to sub-@code{make} invocations (@pxref{Recursion, 5723,Recursive Use of @code{make}}). By default, only variables that came 5724from the environment or the command line are passed to recursive 5725invocations. You can use the @code{export} directive to pass other 5726variables. @xref{Variables/Recursion, , Communicating Variables to a 5727Sub-@code{make}}, for full details. 5728 5729Other use of variables from the environment is not recommended. It is not 5730wise for makefiles to depend for their functioning on environment variables 5731set up outside their control, since this would cause different users to get 5732different results from the same makefile. This is against the whole 5733purpose of most makefiles. 5734 5735@cindex SHELL, import from environment 5736Such problems would be especially likely with the variable 5737@code{SHELL}, which is normally present in the environment to specify 5738the user's choice of interactive shell. It would be very undesirable 5739for this choice to affect @code{make}; so, @code{make} handles the 5740@code{SHELL} environment variable in a special way; see @ref{Choosing 5741the Shell}.@refill 5742 5743@node Target-specific, Pattern-specific, Environment, Using Variables 5744@section Target-specific Variable Values 5745@cindex target-specific variables 5746@cindex variables, target-specific 5747 5748Variable values in @code{make} are usually global; that is, they are the 5749same regardless of where they are evaluated (unless they're reset, of 5750course). One exception to that is automatic variables 5751(@pxref{Automatic Variables}). 5752 5753The other exception is @dfn{target-specific variable values}. This 5754feature allows you to define different values for the same variable, 5755based on the target that @code{make} is currently building. As with 5756automatic variables, these values are only available within the context 5757of a target's command script (and in other target-specific assignments). 5758 5759Set a target-specific variable value like this: 5760 5761@example 5762@var{target} @dots{} : @var{variable-assignment} 5763@end example 5764 5765@noindent 5766or like this: 5767 5768@example 5769@var{target} @dots{} : override @var{variable-assignment} 5770@end example 5771 5772@noindent 5773or like this: 5774 5775@example 5776@var{target} @dots{} : export @var{variable-assignment} 5777@end example 5778 5779Multiple @var{target} values create a target-specific variable value for 5780each member of the target list individually. 5781 5782The @var{variable-assignment} can be any valid form of assignment; 5783recursive (@samp{=}), static (@samp{:=}), appending (@samp{+=}), or 5784conditional (@samp{?=}). All variables that appear within the 5785@var{variable-assignment} are evaluated within the context of the 5786target: thus, any previously-defined target-specific variable values 5787will be in effect. Note that this variable is actually distinct from 5788any ``global'' value: the two variables do not have to have the same 5789flavor (recursive vs.@: static). 5790 5791Target-specific variables have the same priority as any other makefile 5792variable. Variables provided on the command-line (and in the 5793environment if the @samp{-e} option is in force) will take precedence. 5794Specifying the @code{override} directive will allow the target-specific 5795variable value to be preferred. 5796 5797There is one more special feature of target-specific variables: when 5798you define a target-specific variable that variable value is also in 5799effect for all prerequisites of this target, and all their 5800prerequisites, etc.@: (unless those prerequisites override that variable 5801with their own target-specific variable value). So, for example, a 5802statement like this: 5803 5804@example 5805prog : CFLAGS = -g 5806prog : prog.o foo.o bar.o 5807@end example 5808 5809@noindent 5810will set @code{CFLAGS} to @samp{-g} in the command script for 5811@file{prog}, but it will also set @code{CFLAGS} to @samp{-g} in the 5812command scripts that create @file{prog.o}, @file{foo.o}, and 5813@file{bar.o}, and any command scripts which create their 5814prerequisites. 5815 5816Be aware that a given prerequisite will only be built once per 5817invocation of make, at most. If the same file is a prerequisite of 5818multiple targets, and each of those targets has a different value for 5819the same target-specific variable, then the first target to be built 5820will cause that prerequisite to be built and the prerequisite will 5821inherit the target-specific value from the first target. It will 5822ignore the target-specific values from any other targets. 5823 5824@node Pattern-specific, , Target-specific, Using Variables 5825@section Pattern-specific Variable Values 5826@cindex pattern-specific variables 5827@cindex variables, pattern-specific 5828 5829In addition to target-specific variable values 5830(@pxref{Target-specific, ,Target-specific Variable Values}), GNU 5831@code{make} supports pattern-specific variable values. In this form, 5832the variable is defined for any target that matches the pattern 5833specified. If a target matches more than one pattern, all the 5834matching pattern-specific variables are interpreted in the order in 5835which they were defined in the makefile, and collected together into 5836one set. Variables defined in this way are searched after any 5837target-specific variables defined explicitly for that target, and 5838before target-specific variables defined for the parent target. 5839 5840Set a pattern-specific variable value like this: 5841 5842@example 5843@var{pattern} @dots{} : @var{variable-assignment} 5844@end example 5845 5846@noindent 5847or like this: 5848 5849@example 5850@var{pattern} @dots{} : override @var{variable-assignment} 5851@end example 5852 5853@noindent 5854where @var{pattern} is a %-pattern. As with target-specific variable 5855values, multiple @var{pattern} values create a pattern-specific variable 5856value for each pattern individually. The @var{variable-assignment} can 5857be any valid form of assignment. Any command-line variable setting will 5858take precedence, unless @code{override} is specified. 5859 5860For example: 5861 5862@example 5863%.o : CFLAGS = -O 5864@end example 5865 5866@noindent 5867will assign @code{CFLAGS} the value of @samp{-O} for all targets 5868matching the pattern @code{%.o}. 5869 5870@node Conditionals, Functions, Using Variables, Top 5871@chapter Conditional Parts of Makefiles 5872 5873@cindex conditionals 5874A @dfn{conditional} causes part of a makefile to be obeyed or ignored 5875depending on the values of variables. Conditionals can compare the 5876value of one variable to another, or the value of a variable to 5877a constant string. Conditionals control what @code{make} actually 5878``sees'' in the makefile, so they @emph{cannot} be used to control shell 5879commands at the time of execution.@refill 5880 5881@menu 5882* Conditional Example:: Example of a conditional 5883* Conditional Syntax:: The syntax of conditionals. 5884* Testing Flags:: Conditionals that test flags. 5885@end menu 5886 5887@node Conditional Example, Conditional Syntax, Conditionals, Conditionals 5888@section Example of a Conditional 5889 5890The following example of a conditional tells @code{make} to use one set 5891of libraries if the @code{CC} variable is @samp{gcc}, and a different 5892set of libraries otherwise. It works by controlling which of two 5893command lines will be used as the command for a rule. The result is 5894that @samp{CC=gcc} as an argument to @code{make} changes not only which 5895compiler is used but also which libraries are linked. 5896 5897@example 5898libs_for_gcc = -lgnu 5899normal_libs = 5900 5901foo: $(objects) 5902ifeq ($(CC),gcc) 5903 $(CC) -o foo $(objects) $(libs_for_gcc) 5904else 5905 $(CC) -o foo $(objects) $(normal_libs) 5906endif 5907@end example 5908 5909This conditional uses three directives: one @code{ifeq}, one @code{else} 5910and one @code{endif}. 5911 5912The @code{ifeq} directive begins the conditional, and specifies the 5913condition. It contains two arguments, separated by a comma and surrounded 5914by parentheses. Variable substitution is performed on both arguments and 5915then they are compared. The lines of the makefile following the 5916@code{ifeq} are obeyed if the two arguments match; otherwise they are 5917ignored. 5918 5919The @code{else} directive causes the following lines to be obeyed if the 5920previous conditional failed. In the example above, this means that the 5921second alternative linking command is used whenever the first alternative 5922is not used. It is optional to have an @code{else} in a conditional. 5923 5924The @code{endif} directive ends the conditional. Every conditional must 5925end with an @code{endif}. Unconditional makefile text follows. 5926 5927As this example illustrates, conditionals work at the textual level: 5928the lines of the conditional are treated as part of the makefile, or 5929ignored, according to the condition. This is why the larger syntactic 5930units of the makefile, such as rules, may cross the beginning or the 5931end of the conditional. 5932 5933When the variable @code{CC} has the value @samp{gcc}, the above example has 5934this effect: 5935 5936@example 5937foo: $(objects) 5938 $(CC) -o foo $(objects) $(libs_for_gcc) 5939@end example 5940 5941@noindent 5942When the variable @code{CC} has any other value, the effect is this: 5943 5944@example 5945foo: $(objects) 5946 $(CC) -o foo $(objects) $(normal_libs) 5947@end example 5948 5949Equivalent results can be obtained in another way by conditionalizing a 5950variable assignment and then using the variable unconditionally: 5951 5952@example 5953libs_for_gcc = -lgnu 5954normal_libs = 5955 5956ifeq ($(CC),gcc) 5957 libs=$(libs_for_gcc) 5958else 5959 libs=$(normal_libs) 5960endif 5961 5962foo: $(objects) 5963 $(CC) -o foo $(objects) $(libs) 5964@end example 5965 5966@node Conditional Syntax, Testing Flags, Conditional Example, Conditionals 5967@section Syntax of Conditionals 5968@findex ifdef 5969@findex ifeq 5970@findex ifndef 5971@findex ifneq 5972@findex else 5973@findex endif 5974 5975The syntax of a simple conditional with no @code{else} is as follows: 5976 5977@example 5978@var{conditional-directive} 5979@var{text-if-true} 5980endif 5981@end example 5982 5983@noindent 5984The @var{text-if-true} may be any lines of text, to be considered as part 5985of the makefile if the condition is true. If the condition is false, no 5986text is used instead. 5987 5988The syntax of a complex conditional is as follows: 5989 5990@example 5991@var{conditional-directive} 5992@var{text-if-true} 5993else 5994@var{text-if-false} 5995endif 5996@end example 5997 5998or: 5999 6000@example 6001@var{conditional-directive} 6002@var{text-if-one-is-true} 6003else @var{conditional-directive} 6004@var{text-if-true} 6005else 6006@var{text-if-false} 6007endif 6008@end example 6009 6010@noindent 6011There can be as many ``@code{else} @var{conditional-directive}'' 6012clauses as necessary. Once a given condition is true, 6013@var{text-if-true} is used and no other clause is used; if no 6014condition is true then @var{text-if-false} is used. The 6015@var{text-if-true} and @var{text-if-false} can be any number of lines 6016of text. 6017 6018The syntax of the @var{conditional-directive} is the same whether the 6019conditional is simple or complex; after an @code{else} or not. There 6020are four different directives that test different conditions. Here is 6021a table of them: 6022 6023@table @code 6024@item ifeq (@var{arg1}, @var{arg2}) 6025@itemx ifeq '@var{arg1}' '@var{arg2}' 6026@itemx ifeq "@var{arg1}" "@var{arg2}" 6027@itemx ifeq "@var{arg1}" '@var{arg2}' 6028@itemx ifeq '@var{arg1}' "@var{arg2}" 6029Expand all variable references in @var{arg1} and @var{arg2} and 6030compare them. If they are identical, the @var{text-if-true} is 6031effective; otherwise, the @var{text-if-false}, if any, is effective. 6032 6033Often you want to test if a variable has a non-empty value. When the 6034value results from complex expansions of variables and functions, 6035expansions you would consider empty may actually contain whitespace 6036characters and thus are not seen as empty. However, you can use the 6037@code{strip} function (@pxref{Text Functions}) to avoid interpreting 6038whitespace as a non-empty value. For example: 6039 6040@example 6041@group 6042ifeq ($(strip $(foo)),) 6043@var{text-if-empty} 6044endif 6045@end group 6046@end example 6047 6048@noindent 6049will evaluate @var{text-if-empty} even if the expansion of 6050@code{$(foo)} contains whitespace characters. 6051 6052@item ifneq (@var{arg1}, @var{arg2}) 6053@itemx ifneq '@var{arg1}' '@var{arg2}' 6054@itemx ifneq "@var{arg1}" "@var{arg2}" 6055@itemx ifneq "@var{arg1}" '@var{arg2}' 6056@itemx ifneq '@var{arg1}' "@var{arg2}" 6057Expand all variable references in @var{arg1} and @var{arg2} and 6058compare them. If they are different, the @var{text-if-true} is 6059effective; otherwise, the @var{text-if-false}, if any, is effective. 6060 6061@item ifdef @var{variable-name} 6062The @code{ifdef} form takes the @emph{name} of a variable as its 6063argument, not a reference to a variable. The value of that variable 6064has a non-empty value, the @var{text-if-true} is effective; otherwise, 6065the @var{text-if-false}, if any, is effective. Variables that have 6066never been defined have an empty value. The text @var{variable-name} 6067is expanded, so it could be a variable or function that expands 6068to the name of a variable. For example: 6069 6070@example 6071bar = true 6072foo = bar 6073ifdef $(foo) 6074frobozz = yes 6075endif 6076@end example 6077 6078The variable reference @code{$(foo)} is expanded, yielding @code{bar}, 6079which is considered to be the name of a variable. The variable 6080@code{bar} is not expanded, but its value is examined to determine if 6081it is non-empty. 6082 6083Note that @code{ifdef} only tests whether a variable has a value. It 6084does not expand the variable to see if that value is nonempty. 6085Consequently, tests using @code{ifdef} return true for all definitions 6086except those like @code{foo =}. To test for an empty value, use 6087@w{@code{ifeq ($(foo),)}}. For example, 6088 6089@example 6090bar = 6091foo = $(bar) 6092ifdef foo 6093frobozz = yes 6094else 6095frobozz = no 6096endif 6097@end example 6098 6099@noindent 6100sets @samp{frobozz} to @samp{yes}, while: 6101 6102@example 6103foo = 6104ifdef foo 6105frobozz = yes 6106else 6107frobozz = no 6108endif 6109@end example 6110 6111@noindent 6112sets @samp{frobozz} to @samp{no}. 6113 6114@item ifndef @var{variable-name} 6115If the variable @var{variable-name} has an empty value, the 6116@var{text-if-true} is effective; otherwise, the @var{text-if-false}, 6117if any, is effective. The rules for expansion and testing of 6118@var{variable-name} are identical to the @code{ifdef} directive. 6119@end table 6120 6121Extra spaces are allowed and ignored at the beginning of the conditional 6122directive line, but a tab is not allowed. (If the line begins with a tab, 6123it will be considered a command for a rule.) Aside from this, extra spaces 6124or tabs may be inserted with no effect anywhere except within the directive 6125name or within an argument. A comment starting with @samp{#} may appear at 6126the end of the line. 6127 6128The other two directives that play a part in a conditional are @code{else} 6129and @code{endif}. Each of these directives is written as one word, with no 6130arguments. Extra spaces are allowed and ignored at the beginning of the 6131line, and spaces or tabs at the end. A comment starting with @samp{#} may 6132appear at the end of the line. 6133 6134Conditionals affect which lines of the makefile @code{make} uses. If 6135the condition is true, @code{make} reads the lines of the 6136@var{text-if-true} as part of the makefile; if the condition is false, 6137@code{make} ignores those lines completely. It follows that syntactic 6138units of the makefile, such as rules, may safely be split across the 6139beginning or the end of the conditional.@refill 6140 6141@code{make} evaluates conditionals when it reads a makefile. 6142Consequently, you cannot use automatic variables in the tests of 6143conditionals because they are not defined until commands are run 6144(@pxref{Automatic Variables}). 6145 6146To prevent intolerable confusion, it is not permitted to start a 6147conditional in one makefile and end it in another. However, you may 6148write an @code{include} directive within a conditional, provided you do 6149not attempt to terminate the conditional inside the included file. 6150 6151@node Testing Flags, , Conditional Syntax, Conditionals 6152@section Conditionals that Test Flags 6153 6154You can write a conditional that tests @code{make} command flags such as 6155@samp{-t} by using the variable @code{MAKEFLAGS} together with the 6156@code{findstring} function 6157(@pxref{Text Functions, , Functions for String Substitution and Analysis}). 6158This is useful when @code{touch} is not enough to make a file appear up 6159to date. 6160 6161The @code{findstring} function determines whether one string appears as a 6162substring of another. If you want to test for the @samp{-t} flag, 6163use @samp{t} as the first string and the value of @code{MAKEFLAGS} as 6164the other. 6165 6166For example, here is how to arrange to use @samp{ranlib -t} to finish 6167marking an archive file up to date: 6168 6169@example 6170archive.a: @dots{} 6171ifneq (,$(findstring t,$(MAKEFLAGS))) 6172 +touch archive.a 6173 +ranlib -t archive.a 6174else 6175 ranlib archive.a 6176endif 6177@end example 6178 6179@noindent 6180The @samp{+} prefix marks those command lines as ``recursive'' so 6181that they will be executed despite use of the @samp{-t} flag. 6182@xref{Recursion, ,Recursive Use of @code{make}}. 6183 6184@node Functions, Running, Conditionals, Top 6185@chapter Functions for Transforming Text 6186@cindex functions 6187 6188@dfn{Functions} allow you to do text processing in the makefile to compute 6189the files to operate on or the commands to use. You use a function in a 6190@dfn{function call}, where you give the name of the function and some text 6191(the @dfn{arguments}) for the function to operate on. The result of the 6192function's processing is substituted into the makefile at the point of the 6193call, just as a variable might be substituted. 6194 6195@menu 6196* Syntax of Functions:: How to write a function call. 6197* Text Functions:: General-purpose text manipulation functions. 6198* File Name Functions:: Functions for manipulating file names. 6199* Conditional Functions:: Functions that implement conditions. 6200* Foreach Function:: Repeat some text with controlled variation. 6201* Call Function:: Expand a user-defined function. 6202* Value Function:: Return the un-expanded value of a variable. 6203* Eval Function:: Evaluate the arguments as makefile syntax. 6204* Origin Function:: Find where a variable got its value. 6205* Flavor Function:: Find out the flavor of a variable. 6206* Shell Function:: Substitute the output of a shell command. 6207* Make Control Functions:: Functions that control how make runs. 6208@end menu 6209 6210@node Syntax of Functions, Text Functions, Functions, Functions 6211@section Function Call Syntax 6212@cindex @code{$}, in function call 6213@cindex dollar sign (@code{$}), in function call 6214@cindex arguments of functions 6215@cindex functions, syntax of 6216 6217A function call resembles a variable reference. It looks like this: 6218 6219@example 6220$(@var{function} @var{arguments}) 6221@end example 6222 6223@noindent 6224or like this: 6225 6226@example 6227$@{@var{function} @var{arguments}@} 6228@end example 6229 6230Here @var{function} is a function name; one of a short list of names 6231that are part of @code{make}. You can also essentially create your own 6232functions by using the @code{call} builtin function. 6233 6234The @var{arguments} are the arguments of the function. They are 6235separated from the function name by one or more spaces or tabs, and if 6236there is more than one argument, then they are separated by commas. 6237Such whitespace and commas are not part of an argument's value. The 6238delimiters which you use to surround the function call, whether 6239parentheses or braces, can appear in an argument only in matching pairs; 6240the other kind of delimiters may appear singly. If the arguments 6241themselves contain other function calls or variable references, it is 6242wisest to use the same kind of delimiters for all the references; write 6243@w{@samp{$(subst a,b,$(x))}}, not @w{@samp{$(subst a,b,$@{x@})}}. This 6244is because it is clearer, and because only one type of delimiter is 6245matched to find the end of the reference. 6246 6247The text written for each argument is processed by substitution of 6248variables and function calls to produce the argument value, which 6249is the text on which the function acts. The substitution is done in the 6250order in which the arguments appear. 6251 6252Commas and unmatched parentheses or braces cannot appear in the text of an 6253argument as written; leading spaces cannot appear in the text of the first 6254argument as written. These characters can be put into the argument value 6255by variable substitution. First define variables @code{comma} and 6256@code{space} whose values are isolated comma and space characters, then 6257substitute these variables where such characters are wanted, like this: 6258 6259@example 6260@group 6261comma:= , 6262empty:= 6263space:= $(empty) $(empty) 6264foo:= a b c 6265bar:= $(subst $(space),$(comma),$(foo)) 6266# @r{bar is now `a,b,c'.} 6267@end group 6268@end example 6269 6270@noindent 6271Here the @code{subst} function replaces each space with a comma, through 6272the value of @code{foo}, and substitutes the result. 6273 6274@node Text Functions, File Name Functions, Syntax of Functions, Functions 6275@section Functions for String Substitution and Analysis 6276@cindex functions, for text 6277 6278Here are some functions that operate on strings: 6279 6280@table @code 6281@item $(subst @var{from},@var{to},@var{text}) 6282@findex subst 6283Performs a textual replacement on the text @var{text}: each occurrence 6284of @var{from} is replaced by @var{to}. The result is substituted for 6285the function call. For example, 6286 6287@example 6288$(subst ee,EE,feet on the street) 6289@end example 6290 6291substitutes the string @samp{fEEt on the strEEt}. 6292 6293@item $(patsubst @var{pattern},@var{replacement},@var{text}) 6294@findex patsubst 6295Finds whitespace-separated words in @var{text} that match 6296@var{pattern} and replaces them with @var{replacement}. Here 6297@var{pattern} may contain a @samp{%} which acts as a wildcard, 6298matching any number of any characters within a word. If 6299@var{replacement} also contains a @samp{%}, the @samp{%} is replaced 6300by the text that matched the @samp{%} in @var{pattern}. Only the first 6301@samp{%} in the @var{pattern} and @var{replacement} is treated this 6302way; any subsequent @samp{%} is unchanged.@refill 6303 6304@cindex @code{%}, quoting in @code{patsubst} 6305@cindex @code{%}, quoting with @code{\} (backslash) 6306@cindex @code{\} (backslash), to quote @code{%} 6307@cindex backslash (@code{\}), to quote @code{%} 6308@cindex quoting @code{%}, in @code{patsubst} 6309@samp{%} characters in @code{patsubst} function invocations can be 6310quoted with preceding backslashes (@samp{\}). Backslashes that would 6311otherwise quote @samp{%} characters can be quoted with more backslashes. 6312Backslashes that quote @samp{%} characters or other backslashes are 6313removed from the pattern before it is compared file names or has a stem 6314substituted into it. Backslashes that are not in danger of quoting 6315@samp{%} characters go unmolested. For example, the pattern 6316@file{the\%weird\\%pattern\\} has @samp{the%weird\} preceding the 6317operative @samp{%} character, and @samp{pattern\\} following it. The 6318final two backslashes are left alone because they cannot affect any 6319@samp{%} character.@refill 6320 6321Whitespace between words is folded into single space characters; 6322leading and trailing whitespace is discarded. 6323 6324For example, 6325 6326@example 6327$(patsubst %.c,%.o,x.c.c bar.c) 6328@end example 6329 6330@noindent 6331produces the value @samp{x.c.o bar.o}. 6332 6333Substitution references (@pxref{Substitution Refs, ,Substitution 6334References}) are a simpler way to get the effect of the @code{patsubst} 6335function: 6336 6337@example 6338$(@var{var}:@var{pattern}=@var{replacement}) 6339@end example 6340 6341@noindent 6342is equivalent to 6343 6344@example 6345$(patsubst @var{pattern},@var{replacement},$(@var{var})) 6346@end example 6347 6348The second shorthand simplifies one of the most common uses of 6349@code{patsubst}: replacing the suffix at the end of file names. 6350 6351@example 6352$(@var{var}:@var{suffix}=@var{replacement}) 6353@end example 6354 6355@noindent 6356is equivalent to 6357 6358@example 6359$(patsubst %@var{suffix},%@var{replacement},$(@var{var})) 6360@end example 6361 6362@noindent 6363For example, you might have a list of object files: 6364 6365@example 6366objects = foo.o bar.o baz.o 6367@end example 6368 6369@noindent 6370To get the list of corresponding source files, you could simply write: 6371 6372@example 6373$(objects:.o=.c) 6374@end example 6375 6376@noindent 6377instead of using the general form: 6378 6379@example 6380$(patsubst %.o,%.c,$(objects)) 6381@end example 6382 6383@item $(strip @var{string}) 6384@cindex stripping whitespace 6385@cindex whitespace, stripping 6386@cindex spaces, stripping 6387@findex strip 6388Removes leading and trailing whitespace from @var{string} and replaces 6389each internal sequence of one or more whitespace characters with a 6390single space. Thus, @samp{$(strip a b c )} results in @w{@samp{a b c}}. 6391 6392The function @code{strip} can be very useful when used in conjunction 6393with conditionals. When comparing something with the empty string 6394@samp{} using @code{ifeq} or @code{ifneq}, you usually want a string of 6395just whitespace to match the empty string (@pxref{Conditionals}). 6396 6397Thus, the following may fail to have the desired results: 6398 6399@example 6400.PHONY: all 6401ifneq "$(needs_made)" "" 6402all: $(needs_made) 6403else 6404all:;@@echo 'Nothing to make!' 6405endif 6406@end example 6407 6408@noindent 6409Replacing the variable reference @w{@samp{$(needs_made)}} with the 6410function call @w{@samp{$(strip $(needs_made))}} in the @code{ifneq} 6411directive would make it more robust.@refill 6412 6413@item $(findstring @var{find},@var{in}) 6414@findex findstring 6415@cindex searching for strings 6416@cindex finding strings 6417@cindex strings, searching for 6418Searches @var{in} for an occurrence of @var{find}. If it occurs, the 6419value is @var{find}; otherwise, the value is empty. You can use this 6420function in a conditional to test for the presence of a specific 6421substring in a given string. Thus, the two examples, 6422 6423@example 6424$(findstring a,a b c) 6425$(findstring a,b c) 6426@end example 6427 6428@noindent 6429produce the values @samp{a} and @samp{} (the empty string), 6430respectively. @xref{Testing Flags}, for a practical application of 6431@code{findstring}.@refill 6432 6433@need 750 6434@findex filter 6435@cindex filtering words 6436@cindex words, filtering 6437@item $(filter @var{pattern}@dots{},@var{text}) 6438Returns all whitespace-separated words in @var{text} that @emph{do} match 6439any of the @var{pattern} words, removing any words that @emph{do not} 6440match. The patterns are written using @samp{%}, just like the patterns 6441used in the @code{patsubst} function above.@refill 6442 6443The @code{filter} function can be used to separate out different types 6444of strings (such as file names) in a variable. For example: 6445 6446@example 6447sources := foo.c bar.c baz.s ugh.h 6448foo: $(sources) 6449 cc $(filter %.c %.s,$(sources)) -o foo 6450@end example 6451 6452@noindent 6453says that @file{foo} depends of @file{foo.c}, @file{bar.c}, 6454@file{baz.s} and @file{ugh.h} but only @file{foo.c}, @file{bar.c} and 6455@file{baz.s} should be specified in the command to the 6456compiler.@refill 6457 6458@item $(filter-out @var{pattern}@dots{},@var{text}) 6459@findex filter-out 6460@cindex filtering out words 6461@cindex words, filtering out 6462Returns all whitespace-separated words in @var{text} that @emph{do not} 6463match any of the @var{pattern} words, removing the words that @emph{do} 6464match one or more. This is the exact opposite of the @code{filter} 6465function.@refill 6466 6467For example, given: 6468 6469@example 6470@group 6471objects=main1.o foo.o main2.o bar.o 6472mains=main1.o main2.o 6473@end group 6474@end example 6475 6476@noindent 6477the following generates a list which contains all the object files not 6478in @samp{mains}: 6479 6480@example 6481$(filter-out $(mains),$(objects)) 6482@end example 6483 6484@need 1500 6485@findex sort 6486@cindex sorting words 6487@item $(sort @var{list}) 6488Sorts the words of @var{list} in lexical order, removing duplicate 6489words. The output is a list of words separated by single spaces. 6490Thus, 6491 6492@example 6493$(sort foo bar lose) 6494@end example 6495 6496@noindent 6497returns the value @samp{bar foo lose}. 6498 6499@cindex removing duplicate words 6500@cindex duplicate words, removing 6501@cindex words, removing duplicates 6502Incidentally, since @code{sort} removes duplicate words, you can use 6503it for this purpose even if you don't care about the sort order. 6504 6505@item $(word @var{n},@var{text}) 6506@findex word 6507@cindex word, selecting a 6508@cindex selecting a word 6509Returns the @var{n}th word of @var{text}. The legitimate values of 6510@var{n} start from 1. If @var{n} is bigger than the number of words 6511in @var{text}, the value is empty. For example, 6512 6513@example 6514$(word 2, foo bar baz) 6515@end example 6516 6517@noindent 6518returns @samp{bar}. 6519 6520@item $(wordlist @var{s},@var{e},@var{text}) 6521@findex wordlist 6522@cindex words, selecting lists of 6523@cindex selecting word lists 6524Returns the list of words in @var{text} starting with word @var{s} and 6525ending with word @var{e} (inclusive). The legitimate values of @var{s} 6526start from 1; @var{e} may start from 0. If @var{s} is bigger than the 6527number of words in @var{text}, the value is empty. If @var{e} is 6528bigger than the number of words in @var{text}, words up to the end of 6529@var{text} are returned. If @var{s} is greater than @var{e}, nothing 6530is returned. For example, 6531 6532@example 6533$(wordlist 2, 3, foo bar baz) 6534@end example 6535 6536@noindent 6537returns @samp{bar baz}. 6538 6539@c Following item phrased to prevent overfull hbox. --RJC 17 Jul 92 6540@item $(words @var{text}) 6541@findex words 6542@cindex words, finding number 6543Returns the number of words in @var{text}. 6544Thus, the last word of @var{text} is 6545@w{@code{$(word $(words @var{text}),@var{text})}}.@refill 6546 6547@item $(firstword @var{names}@dots{}) 6548@findex firstword 6549@cindex words, extracting first 6550The argument @var{names} is regarded as a series of names, separated 6551by whitespace. The value is the first name in the series. The rest 6552of the names are ignored. 6553 6554For example, 6555 6556@example 6557$(firstword foo bar) 6558@end example 6559 6560@noindent 6561produces the result @samp{foo}. Although @code{$(firstword 6562@var{text})} is the same as @code{$(word 1,@var{text})}, the 6563@code{firstword} function is retained for its simplicity.@refill 6564 6565 6566@item $(lastword @var{names}@dots{}) 6567@findex lastword 6568@cindex words, extracting last 6569The argument @var{names} is regarded as a series of names, separated 6570by whitespace. The value is the last name in the series. 6571 6572For example, 6573 6574@example 6575$(lastword foo bar) 6576@end example 6577 6578@noindent 6579produces the result @samp{bar}. Although @code{$(lastword 6580@var{text})} is the same as @code{$(word $(words @var{text}),@var{text})}, 6581the @code{lastword} function was added for its simplicity and better 6582performance.@refill 6583@end table 6584 6585 6586Here is a realistic example of the use of @code{subst} and 6587@code{patsubst}. Suppose that a makefile uses the @code{VPATH} variable 6588to specify a list of directories that @code{make} should search for 6589prerequisite files 6590(@pxref{General Search, , @code{VPATH} Search Path for All Prerequisites}). 6591This example shows how to 6592tell the C compiler to search for header files in the same list of 6593directories.@refill 6594 6595The value of @code{VPATH} is a list of directories separated by colons, 6596such as @samp{src:../headers}. First, the @code{subst} function is used to 6597change the colons to spaces: 6598 6599@example 6600$(subst :, ,$(VPATH)) 6601@end example 6602 6603@noindent 6604This produces @samp{src ../headers}. Then @code{patsubst} is used to turn 6605each directory name into a @samp{-I} flag. These can be added to the 6606value of the variable @code{CFLAGS}, which is passed automatically to the C 6607compiler, like this: 6608 6609@example 6610override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH))) 6611@end example 6612 6613@noindent 6614The effect is to append the text @samp{-Isrc -I../headers} to the 6615previously given value of @code{CFLAGS}. The @code{override} directive is 6616used so that the new value is assigned even if the previous value of 6617@code{CFLAGS} was specified with a command argument (@pxref{Override 6618Directive, , The @code{override} Directive}). 6619 6620@node File Name Functions, Conditional Functions, Text Functions, Functions 6621@section Functions for File Names 6622@cindex functions, for file names 6623@cindex file name functions 6624 6625Several of the built-in expansion functions relate specifically to 6626taking apart file names or lists of file names. 6627 6628Each of the following functions performs a specific transformation on a 6629file name. The argument of the function is regarded as a series of file 6630names, separated by whitespace. (Leading and trailing whitespace is 6631ignored.) Each file name in the series is transformed in the same way and 6632the results are concatenated with single spaces between them. 6633 6634@table @code 6635@item $(dir @var{names}@dots{}) 6636@findex dir 6637@cindex directory part 6638@cindex file name, directory part 6639Extracts the directory-part of each file name in @var{names}. The 6640directory-part of the file name is everything up through (and 6641including) the last slash in it. If the file name contains no slash, 6642the directory part is the string @samp{./}. For example, 6643 6644@example 6645$(dir src/foo.c hacks) 6646@end example 6647 6648@noindent 6649produces the result @samp{src/ ./}. 6650 6651@item $(notdir @var{names}@dots{}) 6652@findex notdir 6653@cindex file name, nondirectory part 6654@cindex nondirectory part 6655Extracts all but the directory-part of each file name in @var{names}. 6656If the file name contains no slash, it is left unchanged. Otherwise, 6657everything through the last slash is removed from it. 6658 6659A file name that ends with a slash becomes an empty string. This is 6660unfortunate, because it means that the result does not always have the 6661same number of whitespace-separated file names as the argument had; 6662but we do not see any other valid alternative. 6663 6664For example, 6665 6666@example 6667$(notdir src/foo.c hacks) 6668@end example 6669 6670@noindent 6671produces the result @samp{foo.c hacks}. 6672 6673@item $(suffix @var{names}@dots{}) 6674@findex suffix 6675@cindex suffix, function to find 6676@cindex file name suffix 6677Extracts the suffix of each file name in @var{names}. If the file name 6678contains a period, the suffix is everything starting with the last 6679period. Otherwise, the suffix is the empty string. This frequently 6680means that the result will be empty when @var{names} is not, and if 6681@var{names} contains multiple file names, the result may contain fewer 6682file names. 6683 6684For example, 6685 6686@example 6687$(suffix src/foo.c src-1.0/bar.c hacks) 6688@end example 6689 6690@noindent 6691produces the result @samp{.c .c}. 6692 6693@item $(basename @var{names}@dots{}) 6694@findex basename 6695@cindex basename 6696@cindex file name, basename of 6697Extracts all but the suffix of each file name in @var{names}. If the 6698file name contains a period, the basename is everything starting up to 6699(and not including) the last period. Periods in the directory part are 6700ignored. If there is no period, the basename is the entire file name. 6701For example, 6702 6703@example 6704$(basename src/foo.c src-1.0/bar hacks) 6705@end example 6706 6707@noindent 6708produces the result @samp{src/foo src-1.0/bar hacks}. 6709 6710@c plural convention with dots (be consistent) 6711@item $(addsuffix @var{suffix},@var{names}@dots{}) 6712@findex addsuffix 6713@cindex suffix, adding 6714@cindex file name suffix, adding 6715The argument @var{names} is regarded as a series of names, separated 6716by whitespace; @var{suffix} is used as a unit. The value of 6717@var{suffix} is appended to the end of each individual name and the 6718resulting larger names are concatenated with single spaces between 6719them. For example, 6720 6721@example 6722$(addsuffix .c,foo bar) 6723@end example 6724 6725@noindent 6726produces the result @samp{foo.c bar.c}. 6727 6728@item $(addprefix @var{prefix},@var{names}@dots{}) 6729@findex addprefix 6730@cindex prefix, adding 6731@cindex file name prefix, adding 6732The argument @var{names} is regarded as a series of names, separated 6733by whitespace; @var{prefix} is used as a unit. The value of 6734@var{prefix} is prepended to the front of each individual name and the 6735resulting larger names are concatenated with single spaces between 6736them. For example, 6737 6738@example 6739$(addprefix src/,foo bar) 6740@end example 6741 6742@noindent 6743produces the result @samp{src/foo src/bar}. 6744 6745@item $(join @var{list1},@var{list2}) 6746@findex join 6747@cindex joining lists of words 6748@cindex words, joining lists 6749Concatenates the two arguments word by word: the two first words (one 6750from each argument) concatenated form the first word of the result, the 6751two second words form the second word of the result, and so on. So the 6752@var{n}th word of the result comes from the @var{n}th word of each 6753argument. If one argument has more words that the other, the extra 6754words are copied unchanged into the result. 6755 6756For example, @samp{$(join a b,.c .o)} produces @samp{a.c b.o}. 6757 6758Whitespace between the words in the lists is not preserved; it is 6759replaced with a single space. 6760 6761This function can merge the results of the @code{dir} and 6762@code{notdir} functions, to produce the original list of files which 6763was given to those two functions.@refill 6764 6765@item $(wildcard @var{pattern}) 6766@findex wildcard 6767@cindex wildcard, function 6768The argument @var{pattern} is a file name pattern, typically containing 6769wildcard characters (as in shell file name patterns). The result of 6770@code{wildcard} is a space-separated list of the names of existing files 6771that match the pattern. 6772@xref{Wildcards, ,Using Wildcard Characters in File Names}. 6773 6774@item $(realpath @var{names}@dots{}) 6775@findex realpath 6776@cindex realpath 6777@cindex file name, realpath of 6778For each file name in @var{names} return the canonical absolute name. 6779A canonical name does not contain any @code{.} or @code{..} components, 6780nor any repeated path separators (@code{/}) or symlinks. In case of a 6781failure the empty string is returned. Consult the @code{realpath(3)} 6782documentation for a list of possible failure causes. 6783 6784@item $(abspath @var{names}@dots{}) 6785@findex abspath 6786@cindex abspath 6787@cindex file name, abspath of 6788For each file name in @var{names} return an absolute name that does 6789not contain any @code{.} or @code{..} components, nor any repeated path 6790separators (@code{/}). Note that, in contrast to @code{realpath} 6791function, @code{abspath} does not resolve symlinks and does not require 6792the file names to refer to an existing file or directory. Use the 6793@code{wildcard} function to test for existence. 6794@end table 6795 6796@node Conditional Functions, Foreach Function, File Name Functions, Functions 6797@section Functions for Conditionals 6798@findex if 6799@cindex conditional expansion 6800There are three functions that provide conditional expansion. A key 6801aspect of these functions is that not all of the arguments are 6802expanded initially. Only those arguments which need to be expanded, 6803will be expanded. 6804 6805@table @code 6806@item $(if @var{condition},@var{then-part}[,@var{else-part}]) 6807@findex if 6808The @code{if} function provides support for conditional expansion in a 6809functional context (as opposed to the GNU @code{make} makefile 6810conditionals such as @code{ifeq} (@pxref{Conditional Syntax, ,Syntax of 6811Conditionals}). 6812 6813The first argument, @var{condition}, first has all preceding and 6814trailing whitespace stripped, then is expanded. If it expands to any 6815non-empty string, then the condition is considered to be true. If it 6816expands to an empty string, the condition is considered to be false. 6817 6818If the condition is true then the second argument, @var{then-part}, is 6819evaluated and this is used as the result of the evaluation of the entire 6820@code{if} function. 6821 6822If the condition is false then the third argument, @var{else-part}, is 6823evaluated and this is the result of the @code{if} function. If there is 6824no third argument, the @code{if} function evaluates to nothing (the 6825empty string). 6826 6827Note that only one of the @var{then-part} or the @var{else-part} will be 6828evaluated, never both. Thus, either can contain side-effects (such as 6829@code{shell} function calls, etc.) 6830 6831@item $(or @var{condition1}[,@var{condition2}[,@var{condition3}@dots{}]]) 6832@findex or 6833The @code{or} function provides a ``short-circuiting'' OR operation. 6834Each argument is expanded, in order. If an argument expands to a 6835non-empty string the processing stops and the result of the expansion 6836is that string. If, after all arguments are expanded, all of them are 6837false (empty), then the result of the expansion is the empty string. 6838 6839@item $(and @var{condition1}[,@var{condition2}[,@var{condition3}@dots{}]]) 6840@findex and 6841The @code{and} function provides a ``short-circuiting'' AND operation. 6842Each argument is expanded, in order. If an argument expands to an 6843empty string the processing stops and the result of the expansion is 6844the empty string. If all arguments expand to a non-empty string then 6845the result of the expansion is the expansion of the last argument. 6846 6847@end table 6848 6849@node Foreach Function, Call Function, Conditional Functions, Functions 6850@section The @code{foreach} Function 6851@findex foreach 6852@cindex words, iterating over 6853 6854The @code{foreach} function is very different from other functions. It 6855causes one piece of text to be used repeatedly, each time with a different 6856substitution performed on it. It resembles the @code{for} command in the 6857shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}. 6858 6859The syntax of the @code{foreach} function is: 6860 6861@example 6862$(foreach @var{var},@var{list},@var{text}) 6863@end example 6864 6865@noindent 6866The first two arguments, @var{var} and @var{list}, are expanded before 6867anything else is done; note that the last argument, @var{text}, is 6868@strong{not} expanded at the same time. Then for each word of the expanded 6869value of @var{list}, the variable named by the expanded value of @var{var} 6870is set to that word, and @var{text} is expanded. Presumably @var{text} 6871contains references to that variable, so its expansion will be different 6872each time. 6873 6874The result is that @var{text} is expanded as many times as there are 6875whitespace-separated words in @var{list}. The multiple expansions of 6876@var{text} are concatenated, with spaces between them, to make the result 6877of @code{foreach}. 6878 6879This simple example sets the variable @samp{files} to the list of all files 6880in the directories in the list @samp{dirs}: 6881 6882@example 6883dirs := a b c d 6884files := $(foreach dir,$(dirs),$(wildcard $(dir)/*)) 6885@end example 6886 6887Here @var{text} is @samp{$(wildcard $(dir)/*)}. The first repetition 6888finds the value @samp{a} for @code{dir}, so it produces the same result 6889as @samp{$(wildcard a/*)}; the second repetition produces the result 6890of @samp{$(wildcard b/*)}; and the third, that of @samp{$(wildcard c/*)}. 6891 6892This example has the same result (except for setting @samp{dirs}) as 6893the following example: 6894 6895@example 6896files := $(wildcard a/* b/* c/* d/*) 6897@end example 6898 6899When @var{text} is complicated, you can improve readability by giving it 6900a name, with an additional variable: 6901 6902@example 6903find_files = $(wildcard $(dir)/*) 6904dirs := a b c d 6905files := $(foreach dir,$(dirs),$(find_files)) 6906@end example 6907 6908@noindent 6909Here we use the variable @code{find_files} this way. We use plain @samp{=} 6910to define a recursively-expanding variable, so that its value contains an 6911actual function call to be reexpanded under the control of @code{foreach}; 6912a simply-expanded variable would not do, since @code{wildcard} would be 6913called only once at the time of defining @code{find_files}. 6914 6915The @code{foreach} function has no permanent effect on the variable 6916@var{var}; its value and flavor after the @code{foreach} function call are 6917the same as they were beforehand. The other values which are taken from 6918@var{list} are in effect only temporarily, during the execution of 6919@code{foreach}. The variable @var{var} is a simply-expanded variable 6920during the execution of @code{foreach}. If @var{var} was undefined 6921before the @code{foreach} function call, it is undefined after the call. 6922@xref{Flavors, ,The Two Flavors of Variables}.@refill 6923 6924You must take care when using complex variable expressions that result in 6925variable names because many strange things are valid variable names, but 6926are probably not what you intended. For example, 6927 6928@smallexample 6929files := $(foreach Esta escrito en espanol!,b c ch,$(find_files)) 6930@end smallexample 6931 6932@noindent 6933might be useful if the value of @code{find_files} references the variable 6934whose name is @samp{Esta escrito en espanol!} (es un nombre bastante largo, 6935no?), but it is more likely to be a mistake. 6936 6937@node Call Function, Value Function, Foreach Function, Functions 6938@section The @code{call} Function 6939@findex call 6940@cindex functions, user defined 6941@cindex user defined functions 6942 6943The @code{call} function is unique in that it can be used to create new 6944parameterized functions. You can write a complex expression as the 6945value of a variable, then use @code{call} to expand it with different 6946values. 6947 6948The syntax of the @code{call} function is: 6949 6950@example 6951$(call @var{variable},@var{param},@var{param},@dots{}) 6952@end example 6953 6954When @code{make} expands this function, it assigns each @var{param} to 6955temporary variables @code{$(1)}, @code{$(2)}, etc. The variable 6956@code{$(0)} will contain @var{variable}. There is no maximum number of 6957parameter arguments. There is no minimum, either, but it doesn't make 6958sense to use @code{call} with no parameters. 6959 6960Then @var{variable} is expanded as a @code{make} variable in the context 6961of these temporary assignments. Thus, any reference to @code{$(1)} in 6962the value of @var{variable} will resolve to the first @var{param} in the 6963invocation of @code{call}. 6964 6965Note that @var{variable} is the @emph{name} of a variable, not a 6966@emph{reference} to that variable. Therefore you would not normally use 6967a @samp{$} or parentheses when writing it. (You can, however, use a 6968variable reference in the name if you want the name not to be a 6969constant.) 6970 6971If @var{variable} is the name of a builtin function, the builtin function 6972is always invoked (even if a @code{make} variable by that name also 6973exists). 6974 6975The @code{call} function expands the @var{param} arguments before 6976assigning them to temporary variables. This means that @var{variable} 6977values containing references to builtin functions that have special 6978expansion rules, like @code{foreach} or @code{if}, may not work as you 6979expect. 6980 6981Some examples may make this clearer. 6982 6983This macro simply reverses its arguments: 6984 6985@smallexample 6986reverse = $(2) $(1) 6987 6988foo = $(call reverse,a,b) 6989@end smallexample 6990 6991@noindent 6992Here @var{foo} will contain @samp{b a}. 6993 6994This one is slightly more interesting: it defines a macro to search for 6995the first instance of a program in @code{PATH}: 6996 6997@smallexample 6998pathsearch = $(firstword $(wildcard $(addsuffix /$(1),$(subst :, ,$(PATH))))) 6999 7000LS := $(call pathsearch,ls) 7001@end smallexample 7002 7003@noindent 7004Now the variable LS contains @code{/bin/ls} or similar. 7005 7006The @code{call} function can be nested. Each recursive invocation gets 7007its own local values for @code{$(1)}, etc.@: that mask the values of 7008higher-level @code{call}. For example, here is an implementation of a 7009@dfn{map} function: 7010 7011@smallexample 7012map = $(foreach a,$(2),$(call $(1),$(a))) 7013@end smallexample 7014 7015Now you can @var{map} a function that normally takes only one argument, 7016such as @code{origin}, to multiple values in one step: 7017 7018@smallexample 7019o = $(call map,origin,o map MAKE) 7020@end smallexample 7021 7022and end up with @var{o} containing something like @samp{file file default}. 7023 7024A final caution: be careful when adding whitespace to the arguments to 7025@code{call}. As with other functions, any whitespace contained in the 7026second and subsequent arguments is kept; this can cause strange 7027effects. It's generally safest to remove all extraneous whitespace when 7028providing parameters to @code{call}. 7029 7030@node Value Function, Eval Function, Call Function, Functions 7031@comment node-name, next, previous, up 7032@section The @code{value} Function 7033@findex value 7034@cindex variables, unexpanded value 7035 7036The @code{value} function provides a way for you to use the value of a 7037variable @emph{without} having it expanded. Please note that this 7038does not undo expansions which have already occurred; for example if 7039you create a simply expanded variable its value is expanded during the 7040definition; in that case the @code{value} function will return the 7041same result as using the variable directly. 7042 7043The syntax of the @code{value} function is: 7044 7045@example 7046$(value @var{variable}) 7047@end example 7048 7049Note that @var{variable} is the @emph{name} of a variable; not a 7050@emph{reference} to that variable. Therefore you would not normally 7051use a @samp{$} or parentheses when writing it. (You can, however, use 7052a variable reference in the name if you want the name not to be a 7053constant.) 7054 7055The result of this function is a string containing the value of 7056@var{variable}, without any expansion occurring. For example, in this 7057makefile: 7058 7059@example 7060@group 7061FOO = $PATH 7062 7063all: 7064 @@echo $(FOO) 7065 @@echo $(value FOO) 7066@end group 7067@end example 7068 7069@noindent 7070The first output line would be @code{ATH}, since the ``$P'' would be 7071expanded as a @code{make} variable, while the second output line would 7072be the current value of your @code{$PATH} environment variable, since 7073the @code{value} function avoided the expansion. 7074 7075The @code{value} function is most often used in conjunction with the 7076@code{eval} function (@pxref{Eval Function}). 7077 7078@node Eval Function, Origin Function, Value Function, Functions 7079@comment node-name, next, previous, up 7080@section The @code{eval} Function 7081@findex eval 7082@cindex evaluating makefile syntax 7083@cindex makefile syntax, evaluating 7084 7085The @code{eval} function is very special: it allows you to define new 7086makefile constructs that are not constant; which are the result of 7087evaluating other variables and functions. The argument to the 7088@code{eval} function is expanded, then the results of that expansion 7089are parsed as makefile syntax. The expanded results can define new 7090@code{make} variables, targets, implicit or explicit rules, etc. 7091 7092The result of the @code{eval} function is always the empty string; 7093thus, it can be placed virtually anywhere in a makefile without 7094causing syntax errors. 7095 7096It's important to realize that the @code{eval} argument is expanded 7097@emph{twice}; first by the @code{eval} function, then the results of 7098that expansion are expanded again when they are parsed as makefile 7099syntax. This means you may need to provide extra levels of escaping 7100for ``$'' characters when using @code{eval}. The @code{value} 7101function (@pxref{Value Function}) can sometimes be useful in these 7102situations, to circumvent unwanted expansions. 7103 7104Here is an example of how @code{eval} can be used; this example 7105combines a number of concepts and other functions. Although it might 7106seem overly complex to use @code{eval} in this example, rather than 7107just writing out the rules, consider two things: first, the template 7108definition (in @code{PROGRAM_template}) could need to be much more 7109complex than it is here; and second, you might put the complex, 7110``generic'' part of this example into another makefile, then include 7111it in all the individual makefiles. Now your individual makefiles are 7112quite straightforward. 7113 7114@example 7115@group 7116PROGRAMS = server client 7117 7118server_OBJS = server.o server_priv.o server_access.o 7119server_LIBS = priv protocol 7120 7121client_OBJS = client.o client_api.o client_mem.o 7122client_LIBS = protocol 7123 7124# Everything after this is generic 7125 7126.PHONY: all 7127all: $(PROGRAMS) 7128 7129define PROGRAM_template 7130 $(1): $$($(1)_OBJS) $$($(1)_LIBS:%=-l%) 7131 ALL_OBJS += $$($(1)_OBJS) 7132endef 7133 7134$(foreach prog,$(PROGRAMS),$(eval $(call PROGRAM_template,$(prog)))) 7135 7136$(PROGRAMS): 7137 $(LINK.o) $^ $(LDLIBS) -o $@@ 7138 7139clean: 7140 rm -f $(ALL_OBJS) $(PROGRAMS) 7141@end group 7142@end example 7143 7144@node Origin Function, Flavor Function, Eval Function, Functions 7145@section The @code{origin} Function 7146@findex origin 7147@cindex variables, origin of 7148@cindex origin of variable 7149 7150The @code{origin} function is unlike most other functions in that it does 7151not operate on the values of variables; it tells you something @emph{about} 7152a variable. Specifically, it tells you where it came from. 7153 7154The syntax of the @code{origin} function is: 7155 7156@example 7157$(origin @var{variable}) 7158@end example 7159 7160Note that @var{variable} is the @emph{name} of a variable to inquire about; 7161not a @emph{reference} to that variable. Therefore you would not normally 7162use a @samp{$} or parentheses when writing it. (You can, however, use a 7163variable reference in the name if you want the name not to be a constant.) 7164 7165The result of this function is a string telling you how the variable 7166@var{variable} was defined: 7167 7168@table @samp 7169@item undefined 7170 7171if @var{variable} was never defined. 7172 7173@item default 7174 7175if @var{variable} has a default definition, as is usual with @code{CC} 7176and so on. @xref{Implicit Variables, ,Variables Used by Implicit Rules}. 7177Note that if you have redefined a default variable, the @code{origin} 7178function will return the origin of the later definition. 7179 7180@item environment 7181 7182if @var{variable} was defined as an environment variable and the 7183@samp{-e} option is @emph{not} turned on (@pxref{Options Summary, ,Summary of Options}). 7184 7185@item environment override 7186 7187if @var{variable} was defined as an environment variable and the 7188@w{@samp{-e}} option @emph{is} turned on (@pxref{Options Summary, 7189,Summary of Options}).@refill 7190 7191@item file 7192 7193if @var{variable} was defined in a makefile. 7194 7195@item command line 7196 7197if @var{variable} was defined on the command line. 7198 7199@item override 7200 7201if @var{variable} was defined with an @code{override} directive in a 7202makefile (@pxref{Override Directive, ,The @code{override} Directive}). 7203 7204@item automatic 7205 7206if @var{variable} is an automatic variable defined for the 7207execution of the commands for each rule 7208(@pxref{Automatic Variables}). 7209@end table 7210 7211This information is primarily useful (other than for your curiosity) to 7212determine if you want to believe the value of a variable. For example, 7213suppose you have a makefile @file{foo} that includes another makefile 7214@file{bar}. You want a variable @code{bletch} to be defined in @file{bar} 7215if you run the command @w{@samp{make -f bar}}, even if the environment contains 7216a definition of @code{bletch}. However, if @file{foo} defined 7217@code{bletch} before including @file{bar}, you do not want to override that 7218definition. This could be done by using an @code{override} directive in 7219@file{foo}, giving that definition precedence over the later definition in 7220@file{bar}; unfortunately, the @code{override} directive would also 7221override any command line definitions. So, @file{bar} could 7222include:@refill 7223 7224@example 7225@group 7226ifdef bletch 7227ifeq "$(origin bletch)" "environment" 7228bletch = barf, gag, etc. 7229endif 7230endif 7231@end group 7232@end example 7233 7234@noindent 7235If @code{bletch} has been defined from the environment, this will redefine 7236it. 7237 7238If you want to override a previous definition of @code{bletch} if it came 7239from the environment, even under @samp{-e}, you could instead write: 7240 7241@example 7242@group 7243ifneq "$(findstring environment,$(origin bletch))" "" 7244bletch = barf, gag, etc. 7245endif 7246@end group 7247@end example 7248 7249Here the redefinition takes place if @samp{$(origin bletch)} returns either 7250@samp{environment} or @samp{environment override}. 7251@xref{Text Functions, , Functions for String Substitution and Analysis}. 7252 7253@node Flavor Function, Shell Function, Origin Function, Functions 7254@section The @code{flavor} Function 7255@findex flavor 7256@cindex variables, flavor of 7257@cindex flavor of variable 7258 7259The @code{flavor} function is unlike most other functions (and like 7260@code{origin} function) in that it does not operate on the values of 7261variables; it tells you something @emph{about} a variable. 7262Specifically, it tells you the flavor of a variable (@pxref{Flavors, 7263,The Two Flavors of Variables}). 7264 7265The syntax of the @code{flavor} function is: 7266 7267@example 7268$(flavor @var{variable}) 7269@end example 7270 7271Note that @var{variable} is the @emph{name} of a variable to inquire about; 7272not a @emph{reference} to that variable. Therefore you would not normally 7273use a @samp{$} or parentheses when writing it. (You can, however, use a 7274variable reference in the name if you want the name not to be a constant.) 7275 7276The result of this function is a string that identifies the flavor of the 7277variable @var{variable}: 7278 7279@table @samp 7280@item undefined 7281 7282if @var{variable} was never defined. 7283 7284@item recursive 7285 7286if @var{variable} is a recursively expanded variable. 7287 7288@item simple 7289 7290if @var{variable} is a simply expanded variable. 7291 7292@end table 7293 7294 7295@node Shell Function, Make Control Functions, Flavor Function, Functions 7296@section The @code{shell} Function 7297@findex shell 7298@cindex commands, expansion 7299@cindex backquotes 7300@cindex shell command, function for 7301 7302The @code{shell} function is unlike any other function other than the 7303@code{wildcard} function 7304(@pxref{Wildcard Function, ,The Function @code{wildcard}}) in that it 7305communicates with the world outside of @code{make}. 7306 7307The @code{shell} function performs the same function that backquotes 7308(@samp{`}) perform in most shells: it does @dfn{command expansion}. 7309This means that it takes as an argument a shell command and evaluates 7310to the output of the command. The only processing @code{make} does on 7311the result is to convert each newline (or carriage-return / newline 7312pair) to a single space. If there is a trailing (carriage-return 7313and) newline it will simply be removed.@refill 7314 7315The commands run by calls to the @code{shell} function are run when the 7316function calls are expanded (@pxref{Reading Makefiles, , How 7317@code{make} Reads a Makefile}). Because this function involves 7318spawning a new shell, you should carefully consider the performance 7319implications of using the @code{shell} function within recursively 7320expanded variables vs.@: simply expanded variables (@pxref{Flavors, ,The 7321Two Flavors of Variables}). 7322 7323Here are some examples of the use of the @code{shell} function: 7324 7325@example 7326contents := $(shell cat foo) 7327@end example 7328 7329@noindent 7330sets @code{contents} to the contents of the file @file{foo}, with a space 7331(rather than a newline) separating each line. 7332 7333@example 7334files := $(shell echo *.c) 7335@end example 7336 7337@noindent 7338sets @code{files} to the expansion of @samp{*.c}. Unless @code{make} is 7339using a very strange shell, this has the same result as 7340@w{@samp{$(wildcard *.c)}} (as long as at least one @samp{.c} file 7341exists).@refill 7342 7343@node Make Control Functions, , Shell Function, Functions 7344@section Functions That Control Make 7345@cindex functions, for controlling make 7346@cindex controlling make 7347 7348These functions control the way make runs. Generally, they are used to 7349provide information to the user of the makefile or to cause make to stop 7350if some sort of environmental error is detected. 7351 7352@table @code 7353@item $(error @var{text}@dots{}) 7354@findex error 7355@cindex error, stopping on 7356@cindex stopping make 7357Generates a fatal error where the message is @var{text}. Note that the 7358error is generated whenever this function is evaluated. So, if you put 7359it inside a command script or on the right side of a recursive variable 7360assignment, it won't be evaluated until later. The @var{text} will be 7361expanded before the error is generated. 7362 7363For example, 7364 7365@example 7366ifdef ERROR1 7367$(error error is $(ERROR1)) 7368endif 7369@end example 7370 7371@noindent 7372will generate a fatal error during the read of the makefile if the 7373@code{make} variable @code{ERROR1} is defined. Or, 7374 7375@example 7376ERR = $(error found an error!) 7377 7378.PHONY: err 7379err: ; $(ERR) 7380@end example 7381 7382@noindent 7383will generate a fatal error while @code{make} is running, if the 7384@code{err} target is invoked. 7385 7386@item $(warning @var{text}@dots{}) 7387@findex warning 7388@cindex warnings, printing 7389@cindex printing user warnings 7390This function works similarly to the @code{error} function, above, 7391except that @code{make} doesn't exit. Instead, @var{text} is expanded 7392and the resulting message is displayed, but processing of the makefile 7393continues. 7394 7395The result of the expansion of this function is the empty string. 7396 7397@item $(info @var{text}@dots{}) 7398@findex info 7399@cindex printing messages 7400This function does nothing more than print its (expanded) argument(s) 7401to standard output. No makefile name or line number is added. The 7402result of the expansion of this function is the empty string. 7403@end table 7404 7405@node Running, Implicit Rules, Functions, Top 7406@chapter How to Run @code{make} 7407 7408A makefile that says how to recompile a program can be used in more 7409than one way. The simplest use is to recompile every file that is out 7410of date. Usually, makefiles are written so that if you run 7411@code{make} with no arguments, it does just that. 7412 7413But you might want to update only some of the files; you might want to use 7414a different compiler or different compiler options; you might want just to 7415find out which files are out of date without changing them. 7416 7417By giving arguments when you run @code{make}, you can do any of these 7418things and many others. 7419 7420@cindex exit status of make 7421The exit status of @code{make} is always one of three values: 7422@table @code 7423@item 0 7424The exit status is zero if @code{make} is successful. 7425@item 2 7426The exit status is two if @code{make} encounters any errors. 7427It will print messages describing the particular errors. 7428@item 1 7429The exit status is one if you use the @samp{-q} flag and @code{make} 7430determines that some target is not already up to date. 7431@xref{Instead of Execution, ,Instead of Executing the Commands}. 7432@end table 7433 7434@menu 7435* Makefile Arguments:: How to specify which makefile to use. 7436* Goals:: How to use goal arguments to specify which 7437 parts of the makefile to use. 7438* Instead of Execution:: How to use mode flags to specify what 7439 kind of thing to do with the commands 7440 in the makefile other than simply 7441 execute them. 7442* Avoiding Compilation:: How to avoid recompiling certain files. 7443* Overriding:: How to override a variable to specify 7444 an alternate compiler and other things. 7445* Testing:: How to proceed past some errors, to 7446 test compilation. 7447* Options Summary:: Summary of Options 7448@end menu 7449 7450@node Makefile Arguments, Goals, Running, Running 7451@section Arguments to Specify the Makefile 7452@cindex @code{--file} 7453@cindex @code{--makefile} 7454@cindex @code{-f} 7455 7456The way to specify the name of the makefile is with the @samp{-f} or 7457@samp{--file} option (@samp{--makefile} also works). For example, 7458@samp{-f altmake} says to use the file @file{altmake} as the makefile. 7459 7460If you use the @samp{-f} flag several times and follow each @samp{-f} 7461with an argument, all the specified files are used jointly as 7462makefiles. 7463 7464If you do not use the @samp{-f} or @samp{--file} flag, the default is 7465to try @file{GNUmakefile}, @file{makefile}, and @file{Makefile}, in 7466that order, and use the first of these three which exists or can be made 7467(@pxref{Makefiles, ,Writing Makefiles}).@refill 7468 7469@node Goals, Instead of Execution, Makefile Arguments, Running 7470@section Arguments to Specify the Goals 7471@cindex goal, how to specify 7472 7473The @dfn{goals} are the targets that @code{make} should strive ultimately 7474to update. Other targets are updated as well if they appear as 7475prerequisites of goals, or prerequisites of prerequisites of goals, etc. 7476 7477By default, the goal is the first target in the makefile (not counting 7478targets that start with a period). Therefore, makefiles are usually 7479written so that the first target is for compiling the entire program or 7480programs they describe. If the first rule in the makefile has several 7481targets, only the first target in the rule becomes the default goal, not 7482the whole list. You can manage the selection of the default goal from 7483within your makefile using the @code{.DEFAULT_GOAL} variable 7484(@pxref{Special Variables, , Other Special Variables}). 7485 7486You can also specify a different goal or goals with command-line 7487arguments to @code{make}. Use the name of the goal as an argument. 7488If you specify several goals, @code{make} processes each of them in 7489turn, in the order you name them. 7490 7491Any target in the makefile may be specified as a goal (unless it 7492starts with @samp{-} or contains an @samp{=}, in which case it will be 7493parsed as a switch or variable definition, respectively). Even 7494targets not in the makefile may be specified, if @code{make} can find 7495implicit rules that say how to make them. 7496 7497@vindex MAKECMDGOALS 7498@code{Make} will set the special variable @code{MAKECMDGOALS} to the 7499list of goals you specified on the command line. If no goals were given 7500on the command line, this variable is empty. Note that this variable 7501should be used only in special circumstances. 7502 7503An example of appropriate use is to avoid including @file{.d} files 7504during @code{clean} rules (@pxref{Automatic Prerequisites}), so 7505@code{make} won't create them only to immediately remove them 7506again:@refill 7507 7508@example 7509@group 7510sources = foo.c bar.c 7511 7512ifneq ($(MAKECMDGOALS),clean) 7513include $(sources:.c=.d) 7514endif 7515@end group 7516@end example 7517 7518One use of specifying a goal is if you want to compile only a part of 7519the program, or only one of several programs. Specify as a goal each 7520file that you wish to remake. For example, consider a directory containing 7521several programs, with a makefile that starts like this: 7522 7523@example 7524.PHONY: all 7525all: size nm ld ar as 7526@end example 7527 7528If you are working on the program @code{size}, you might want to say 7529@w{@samp{make size}} so that only the files of that program are recompiled. 7530 7531Another use of specifying a goal is to make files that are not normally 7532made. For example, there may be a file of debugging output, or a 7533version of the program that is compiled specially for testing, which has 7534a rule in the makefile but is not a prerequisite of the default goal. 7535 7536Another use of specifying a goal is to run the commands associated with 7537a phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty 7538Targets, ,Empty Target Files to Record Events}). Many makefiles contain 7539a phony target named @file{clean} which deletes everything except source 7540files. Naturally, this is done only if you request it explicitly with 7541@w{@samp{make clean}}. Following is a list of typical phony and empty 7542target names. @xref{Standard Targets}, for a detailed list of all the 7543standard target names which GNU software packages use. 7544 7545@table @file 7546@item all 7547@cindex @code{all} @r{(standard target)} 7548Make all the top-level targets the makefile knows about. 7549 7550@item clean 7551@cindex @code{clean} @r{(standard target)} 7552Delete all files that are normally created by running @code{make}. 7553 7554@item mostlyclean 7555@cindex @code{mostlyclean} @r{(standard target)} 7556Like @samp{clean}, but may refrain from deleting a few files that people 7557normally don't want to recompile. For example, the @samp{mostlyclean} 7558target for GCC does not delete @file{libgcc.a}, because recompiling it 7559is rarely necessary and takes a lot of time. 7560 7561@item distclean 7562@cindex @code{distclean} @r{(standard target)} 7563@itemx realclean 7564@cindex @code{realclean} @r{(standard target)} 7565@itemx clobber 7566@cindex @code{clobber} @r{(standard target)} 7567Any of these targets might be defined to delete @emph{more} files than 7568@samp{clean} does. For example, this would delete configuration files 7569or links that you would normally create as preparation for compilation, 7570even if the makefile itself cannot create these files. 7571 7572@item install 7573@cindex @code{install} @r{(standard target)} 7574Copy the executable file into a directory that users typically search 7575for commands; copy any auxiliary files that the executable uses into 7576the directories where it will look for them. 7577 7578@item print 7579@cindex @code{print} @r{(standard target)} 7580Print listings of the source files that have changed. 7581 7582@item tar 7583@cindex @code{tar} @r{(standard target)} 7584Create a tar file of the source files. 7585 7586@item shar 7587@cindex @code{shar} @r{(standard target)} 7588Create a shell archive (shar file) of the source files. 7589 7590@item dist 7591@cindex @code{dist} @r{(standard target)} 7592Create a distribution file of the source files. This might 7593be a tar file, or a shar file, or a compressed version of one of the 7594above, or even more than one of the above. 7595 7596@item TAGS 7597@cindex @code{TAGS} @r{(standard target)} 7598Update a tags table for this program. 7599 7600@item check 7601@cindex @code{check} @r{(standard target)} 7602@itemx test 7603@cindex @code{test} @r{(standard target)} 7604Perform self tests on the program this makefile builds. 7605@end table 7606 7607@node Instead of Execution, Avoiding Compilation, Goals, Running 7608@section Instead of Executing the Commands 7609@cindex execution, instead of 7610@cindex commands, instead of executing 7611 7612The makefile tells @code{make} how to tell whether a target is up to date, 7613and how to update each target. But updating the targets is not always 7614what you want. Certain options specify other activities for @code{make}. 7615 7616@comment Extra blank lines make it print better. 7617@table @samp 7618@item -n 7619@itemx --just-print 7620@itemx --dry-run 7621@itemx --recon 7622@cindex @code{--just-print} 7623@cindex @code{--dry-run} 7624@cindex @code{--recon} 7625@cindex @code{-n} 7626 7627``No-op''. The activity is to print what commands would be used to make 7628the targets up to date, but not actually execute them. 7629 7630@item -t 7631@itemx --touch 7632@cindex @code{--touch} 7633@cindex touching files 7634@cindex target, touching 7635@cindex @code{-t} 7636 7637``Touch''. The activity is to mark the targets as up to date without 7638actually changing them. In other words, @code{make} pretends to compile 7639the targets but does not really change their contents. 7640 7641@item -q 7642@itemx --question 7643@cindex @code{--question} 7644@cindex @code{-q} 7645@cindex question mode 7646 7647``Question''. The activity is to find out silently whether the targets 7648are up to date already; but execute no commands in either case. In other 7649words, neither compilation nor output will occur. 7650 7651@item -W @var{file} 7652@itemx --what-if=@var{file} 7653@itemx --assume-new=@var{file} 7654@itemx --new-file=@var{file} 7655@cindex @code{--what-if} 7656@cindex @code{-W} 7657@cindex @code{--assume-new} 7658@cindex @code{--new-file} 7659@cindex what if 7660@cindex files, assuming new 7661 7662``What if''. Each @samp{-W} flag is followed by a file name. The given 7663files' modification times are recorded by @code{make} as being the present 7664time, although the actual modification times remain the same. 7665You can use the @samp{-W} flag in conjunction with the @samp{-n} flag 7666to see what would happen if you were to modify specific files.@refill 7667@end table 7668 7669With the @samp{-n} flag, @code{make} prints the commands that it would 7670normally execute but does not execute them. 7671 7672With the @samp{-t} flag, @code{make} ignores the commands in the rules 7673and uses (in effect) the command @code{touch} for each target that needs to 7674be remade. The @code{touch} command is also printed, unless @samp{-s} or 7675@code{.SILENT} is used. For speed, @code{make} does not actually invoke 7676the program @code{touch}. It does the work directly. 7677 7678With the @samp{-q} flag, @code{make} prints nothing and executes no 7679commands, but the exit status code it returns is zero if and only if the 7680targets to be considered are already up to date. If the exit status is 7681one, then some updating needs to be done. If @code{make} encounters an 7682error, the exit status is two, so you can distinguish an error from a 7683target that is not up to date. 7684 7685It is an error to use more than one of these three flags in the same 7686invocation of @code{make}. 7687 7688@cindex +, and command execution 7689The @samp{-n}, @samp{-t}, and @samp{-q} options do not affect command 7690lines that begin with @samp{+} characters or contain the strings 7691@samp{$(MAKE)} or @samp{$@{MAKE@}}. Note that only the line containing 7692the @samp{+} character or the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} 7693is run regardless of these options. Other lines in the same rule are 7694not run unless they too begin with @samp{+} or contain @samp{$(MAKE)} or 7695@samp{$@{MAKE@}} (@xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.) 7696 7697The @samp{-W} flag provides two features: 7698 7699@itemize @bullet 7700@item 7701If you also use the @samp{-n} or @samp{-q} flag, you can see what 7702@code{make} would do if you were to modify some files. 7703 7704@item 7705Without the @samp{-n} or @samp{-q} flag, when @code{make} is actually 7706executing commands, the @samp{-W} flag can direct @code{make} to act 7707as if some files had been modified, without actually modifying the 7708files.@refill 7709@end itemize 7710 7711Note that the options @samp{-p} and @samp{-v} allow you to obtain other 7712information about @code{make} or about the makefiles in use 7713(@pxref{Options Summary, ,Summary of Options}).@refill 7714 7715@node Avoiding Compilation, Overriding, Instead of Execution, Running 7716@section Avoiding Recompilation of Some Files 7717@cindex @code{-o} 7718@cindex @code{--old-file} 7719@cindex @code{--assume-old} 7720@cindex files, assuming old 7721@cindex files, avoiding recompilation of 7722@cindex recompilation, avoiding 7723 7724Sometimes you may have changed a source file but you do not want to 7725recompile all the files that depend on it. For example, suppose you add 7726a macro or a declaration to a header file that many other files depend 7727on. Being conservative, @code{make} assumes that any change in the 7728header file requires recompilation of all dependent files, but you know 7729that they do not need to be recompiled and you would rather not waste 7730the time waiting for them to compile. 7731 7732If you anticipate the problem before changing the header file, you can 7733use the @samp{-t} flag. This flag tells @code{make} not to run the 7734commands in the rules, but rather to mark the target up to date by 7735changing its last-modification date. You would follow this procedure: 7736 7737@enumerate 7738@item 7739Use the command @samp{make} to recompile the source files that really 7740need recompilation, ensuring that the object files are up-to-date 7741before you begin. 7742 7743@item 7744Make the changes in the header files. 7745 7746@item 7747Use the command @samp{make -t} to mark all the object files as 7748up to date. The next time you run @code{make}, the changes in the 7749header files will not cause any recompilation. 7750@end enumerate 7751 7752If you have already changed the header file at a time when some files 7753do need recompilation, it is too late to do this. Instead, you can 7754use the @w{@samp{-o @var{file}}} flag, which marks a specified file as 7755``old'' (@pxref{Options Summary, ,Summary of Options}). This means 7756that the file itself will not be remade, and nothing else will be 7757remade on its account. Follow this procedure: 7758 7759@enumerate 7760@item 7761Recompile the source files that need compilation for reasons independent 7762of the particular header file, with @samp{make -o @var{headerfile}}. 7763If several header files are involved, use a separate @samp{-o} option 7764for each header file. 7765 7766@item 7767Touch all the object files with @samp{make -t}. 7768@end enumerate 7769 7770@node Overriding, Testing, Avoiding Compilation, Running 7771@section Overriding Variables 7772@cindex overriding variables with arguments 7773@cindex variables, overriding with arguments 7774@cindex command line variables 7775@cindex variables, command line 7776 7777An argument that contains @samp{=} specifies the value of a variable: 7778@samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}. 7779If you specify a value in this way, all ordinary assignments of the same 7780variable in the makefile are ignored; we say they have been 7781@dfn{overridden} by the command line argument. 7782 7783The most common way to use this facility is to pass extra flags to 7784compilers. For example, in a properly written makefile, the variable 7785@code{CFLAGS} is included in each command that runs the C compiler, so a 7786file @file{foo.c} would be compiled something like this: 7787 7788@example 7789cc -c $(CFLAGS) foo.c 7790@end example 7791 7792Thus, whatever value you set for @code{CFLAGS} affects each compilation 7793that occurs. The makefile probably specifies the usual value for 7794@code{CFLAGS}, like this: 7795 7796@example 7797CFLAGS=-g 7798@end example 7799 7800Each time you run @code{make}, you can override this value if you 7801wish. For example, if you say @samp{make CFLAGS='-g -O'}, each C 7802compilation will be done with @samp{cc -c -g -O}. (This also 7803illustrates how you can use quoting in the shell to enclose spaces and 7804other special characters in the value of a variable when you override 7805it.) 7806 7807The variable @code{CFLAGS} is only one of many standard variables that 7808exist just so that you can change them this way. @xref{Implicit 7809Variables, , Variables Used by Implicit Rules}, for a complete list. 7810 7811You can also program the makefile to look at additional variables of your 7812own, giving the user the ability to control other aspects of how the 7813makefile works by changing the variables. 7814 7815When you override a variable with a command argument, you can define either 7816a recursively-expanded variable or a simply-expanded variable. The 7817examples shown above make a recursively-expanded variable; to make a 7818simply-expanded variable, write @samp{:=} instead of @samp{=}. But, unless 7819you want to include a variable reference or function call in the 7820@emph{value} that you specify, it makes no difference which kind of 7821variable you create. 7822 7823There is one way that the makefile can change a variable that you have 7824overridden. This is to use the @code{override} directive, which is a line 7825that looks like this: @samp{override @var{variable} = @var{value}} 7826(@pxref{Override Directive, ,The @code{override} Directive}). 7827 7828@node Testing, Options Summary, Overriding, Running 7829@section Testing the Compilation of a Program 7830@cindex testing compilation 7831@cindex compilation, testing 7832 7833Normally, when an error happens in executing a shell command, @code{make} 7834gives up immediately, returning a nonzero status. No further commands are 7835executed for any target. The error implies that the goal cannot be 7836correctly remade, and @code{make} reports this as soon as it knows. 7837 7838When you are compiling a program that you have just changed, this is not 7839what you want. Instead, you would rather that @code{make} try compiling 7840every file that can be tried, to show you as many compilation errors 7841as possible. 7842 7843@cindex @code{-k} 7844@cindex @code{--keep-going} 7845On these occasions, you should use the @samp{-k} or 7846@samp{--keep-going} flag. This tells @code{make} to continue to 7847consider the other prerequisites of the pending targets, remaking them 7848if necessary, before it gives up and returns nonzero status. For 7849example, after an error in compiling one object file, @samp{make -k} 7850will continue compiling other object files even though it already 7851knows that linking them will be impossible. In addition to continuing 7852after failed shell commands, @samp{make -k} will continue as much as 7853possible after discovering that it does not know how to make a target 7854or prerequisite file. This will always cause an error message, but 7855without @samp{-k}, it is a fatal error (@pxref{Options Summary, 7856,Summary of Options}).@refill 7857 7858The usual behavior of @code{make} assumes that your purpose is to get the 7859goals up to date; once @code{make} learns that this is impossible, it might 7860as well report the failure immediately. The @samp{-k} flag says that the 7861real purpose is to test as much as possible of the changes made in the 7862program, perhaps to find several independent problems so that you can 7863correct them all before the next attempt to compile. This is why Emacs' 7864@kbd{M-x compile} command passes the @samp{-k} flag by default. 7865 7866@node Options Summary, , Testing, Running 7867@section Summary of Options 7868@cindex options 7869@cindex flags 7870@cindex switches 7871 7872Here is a table of all the options @code{make} understands: 7873 7874@table @samp 7875@item -b 7876@cindex @code{-b} 7877@itemx -m 7878@cindex @code{-m} 7879These options are ignored for compatibility with other versions of @code{make}. 7880 7881@item -B 7882@cindex @code{-B} 7883@itemx --always-make 7884@cindex @code{--always-make} 7885Consider all targets out-of-date. GNU @code{make} proceeds to 7886consider targets and their prerequisites using the normal algorithms; 7887however, all targets so considered are always remade regardless of the 7888status of their prerequisites. To avoid infinite recursion, if 7889@code{MAKE_RESTARTS} (@pxref{Special Variables, , Other Special 7890Variables}) is set to a number greater than 0 this option is disabled 7891when considering whether to remake makefiles (@pxref{Remaking 7892Makefiles, , How Makefiles Are Remade}). 7893 7894@item -C @var{dir} 7895@cindex @code{-C} 7896@itemx --directory=@var{dir} 7897@cindex @code{--directory} 7898Change to directory @var{dir} before reading the makefiles. If multiple 7899@samp{-C} options are specified, each is interpreted relative to the 7900previous one: @samp{-C / -C etc} is equivalent to @samp{-C /etc}. 7901This is typically used with recursive invocations of @code{make} 7902(@pxref{Recursion, ,Recursive Use of @code{make}}). 7903 7904@item -d 7905@cindex @code{-d} 7906@c Extra blank line here makes the table look better. 7907 7908Print debugging information in addition to normal processing. The 7909debugging information says which files are being considered for 7910remaking, which file-times are being compared and with what results, 7911which files actually need to be remade, which implicit rules are 7912considered and which are applied---everything interesting about how 7913@code{make} decides what to do. The @code{-d} option is equivalent to 7914@samp{--debug=a} (see below). 7915 7916@item --debug[=@var{options}] 7917@cindex @code{--debug} 7918@c Extra blank line here makes the table look better. 7919 7920Print debugging information in addition to normal processing. Various 7921levels and types of output can be chosen. With no arguments, print the 7922``basic'' level of debugging. Possible arguments are below; only the 7923first character is considered, and values must be comma- or 7924space-separated. 7925 7926@table @code 7927@item a (@i{all}) 7928All types of debugging output are enabled. This is equivalent to using 7929@samp{-d}. 7930 7931@item b (@i{basic}) 7932Basic debugging prints each target that was found to be out-of-date, and 7933whether the build was successful or not. 7934 7935@item v (@i{verbose}) 7936A level above @samp{basic}; includes messages about which makefiles were 7937parsed, prerequisites that did not need to be rebuilt, etc. This option 7938also enables @samp{basic} messages. 7939 7940@item i (@i{implicit}) 7941Prints messages describing the implicit rule searches for each target. 7942This option also enables @samp{basic} messages. 7943 7944@item j (@i{jobs}) 7945Prints messages giving details on the invocation of specific subcommands. 7946 7947@item m (@i{makefile}) 7948By default, the above messages are not enabled while trying to remake 7949the makefiles. This option enables messages while rebuilding makefiles, 7950too. Note that the @samp{all} option does enable this option. This 7951option also enables @samp{basic} messages. 7952@end table 7953 7954@item -e 7955@cindex @code{-e} 7956@itemx --environment-overrides 7957@cindex @code{--environment-overrides} 7958Give variables taken from the environment precedence 7959over variables from makefiles. 7960@xref{Environment, ,Variables from the Environment}. 7961 7962@item -f @var{file} 7963@cindex @code{-f} 7964@itemx --file=@var{file} 7965@cindex @code{--file} 7966@itemx --makefile=@var{file} 7967@cindex @code{--makefile} 7968Read the file named @var{file} as a makefile. 7969@xref{Makefiles, ,Writing Makefiles}. 7970 7971@item -h 7972@cindex @code{-h} 7973@itemx --help 7974@cindex @code{--help} 7975@c Extra blank line here makes the table look better. 7976 7977Remind you of the options that @code{make} understands and then exit. 7978 7979@item -i 7980@cindex @code{-i} 7981@itemx --ignore-errors 7982@cindex @code{--ignore-errors} 7983Ignore all errors in commands executed to remake files. 7984@xref{Errors, ,Errors in Commands}. 7985 7986@item -I @var{dir} 7987@cindex @code{-I} 7988@itemx --include-dir=@var{dir} 7989@cindex @code{--include-dir} 7990Specifies a directory @var{dir} to search for included makefiles. 7991@xref{Include, ,Including Other Makefiles}. If several @samp{-I} 7992options are used to specify several directories, the directories are 7993searched in the order specified. 7994 7995@item -j [@var{jobs}] 7996@cindex @code{-j} 7997@itemx --jobs[=@var{jobs}] 7998@cindex @code{--jobs} 7999Specifies the number of jobs (commands) to run simultaneously. With no 8000argument, @code{make} runs as many jobs simultaneously as possible. If 8001there is more than one @samp{-j} option, the last one is effective. 8002@xref{Parallel, ,Parallel Execution}, 8003for more information on how commands are run. 8004Note that this option is ignored on MS-DOS. 8005 8006@item -k 8007@cindex @code{-k} 8008@itemx --keep-going 8009@cindex @code{--keep-going} 8010Continue as much as possible after an error. While the target that 8011failed, and those that depend on it, cannot be remade, the other 8012prerequisites of these targets can be processed all the same. 8013@xref{Testing, ,Testing the Compilation of a Program}. 8014 8015@item -l [@var{load}] 8016@cindex @code{-l} 8017@itemx --load-average[=@var{load}] 8018@cindex @code{--load-average} 8019@itemx --max-load[=@var{load}] 8020@cindex @code{--max-load} 8021Specifies that no new jobs (commands) should be started if there are 8022other jobs running and the load average is at least @var{load} (a 8023floating-point number). With no argument, removes a previous load 8024limit. @xref{Parallel, ,Parallel Execution}. 8025 8026@item -L 8027@cindex @code{-L} 8028@itemx --check-symlink-times 8029@cindex @code{--check-symlink-times} 8030On systems that support symbolic links, this option causes @code{make} 8031to consider the timestamps on any symbolic links in addition to the 8032timestamp on the file referenced by those links. When this option is 8033provided, the most recent timestamp among the file and the symbolic 8034links is taken as the modification time for this target file. 8035 8036@item -n 8037@cindex @code{-n} 8038@itemx --just-print 8039@cindex @code{--just-print} 8040@itemx --dry-run 8041@cindex @code{--dry-run} 8042@itemx --recon 8043@cindex @code{--recon} 8044@c Extra blank line here makes the table look better. 8045 8046Print the commands that would be executed, but do not execute them. 8047@xref{Instead of Execution, ,Instead of Executing the Commands}. 8048 8049@item -o @var{file} 8050@cindex @code{-o} 8051@itemx --old-file=@var{file} 8052@cindex @code{--old-file} 8053@itemx --assume-old=@var{file} 8054@cindex @code{--assume-old} 8055Do not remake the file @var{file} even if it is older than its 8056prerequisites, and do not remake anything on account of changes in 8057@var{file}. Essentially the file is treated as very old and its rules 8058are ignored. @xref{Avoiding Compilation, ,Avoiding Recompilation of 8059Some Files}.@refill 8060 8061@item -p 8062@cindex @code{-p} 8063@itemx --print-data-base 8064@cindex @code{--print-data-base} 8065@cindex data base of @code{make} rules 8066@cindex predefined rules and variables, printing 8067Print the data base (rules and variable values) that results from 8068reading the makefiles; then execute as usual or as otherwise specified. 8069This also prints the version information given by the @samp{-v} switch 8070(see below). To print the data base without trying to remake any files, 8071use @w{@samp{make -qp}}. To print the data base of predefined rules and 8072variables, use @w{@samp{make -p -f /dev/null}}. The data base output 8073contains filename and linenumber information for command and variable 8074definitions, so it can be a useful debugging tool in complex environments. 8075 8076@item -q 8077@cindex @code{-q} 8078@itemx --question 8079@cindex @code{--question} 8080``Question mode''. Do not run any commands, or print anything; just 8081return an exit status that is zero if the specified targets are already 8082up to date, one if any remaking is required, or two if an error is 8083encountered. @xref{Instead of Execution, ,Instead of Executing the 8084Commands}.@refill 8085 8086@item -r 8087@cindex @code{-r} 8088@itemx --no-builtin-rules 8089@cindex @code{--no-builtin-rules} 8090Eliminate use of the built-in implicit rules (@pxref{Implicit Rules, 8091,Using Implicit Rules}). You can still define your own by writing 8092pattern rules (@pxref{Pattern Rules, ,Defining and Redefining Pattern 8093Rules}). The @samp{-r} option also clears out the default list of 8094suffixes for suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix 8095Rules}). But you can still define your own suffixes with a rule for 8096@code{.SUFFIXES}, and then define your own suffix rules. Note that only 8097@emph{rules} are affected by the @code{-r} option; default variables 8098remain in effect (@pxref{Implicit Variables, ,Variables Used by Implicit 8099Rules}); see the @samp{-R} option below. 8100 8101@item -R 8102@cindex @code{-R} 8103@itemx --no-builtin-variables 8104@cindex @code{--no-builtin-variables} 8105Eliminate use of the built-in rule-specific variables (@pxref{Implicit 8106Variables, ,Variables Used by Implicit Rules}). You can still define 8107your own, of course. The @samp{-R} option also automatically enables 8108the @samp{-r} option (see above), since it doesn't make sense to have 8109implicit rules without any definitions for the variables that they use. 8110 8111@item -s 8112@cindex @code{-s} 8113@itemx --silent 8114@cindex @code{--silent} 8115@itemx --quiet 8116@cindex @code{--quiet} 8117@c Extra blank line here makes the table look better. 8118 8119Silent operation; do not print the commands as they are executed. 8120@xref{Echoing, ,Command Echoing}. 8121 8122@item -S 8123@cindex @code{-S} 8124@itemx --no-keep-going 8125@cindex @code{--no-keep-going} 8126@itemx --stop 8127@cindex @code{--stop} 8128@c Extra blank line here makes the table look better. 8129 8130Cancel the effect of the @samp{-k} option. This is never necessary 8131except in a recursive @code{make} where @samp{-k} might be inherited 8132from the top-level @code{make} via @code{MAKEFLAGS} 8133(@pxref{Recursion, ,Recursive Use of @code{make}}) 8134or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill 8135 8136@item -t 8137@cindex @code{-t} 8138@itemx --touch 8139@cindex @code{--touch} 8140@c Extra blank line here makes the table look better. 8141 8142Touch files (mark them up to date without really changing them) 8143instead of running their commands. This is used to pretend that the 8144commands were done, in order to fool future invocations of 8145@code{make}. @xref{Instead of Execution, ,Instead of Executing the Commands}. 8146 8147@item -v 8148@cindex @code{-v} 8149@itemx --version 8150@cindex @code{--version} 8151Print the version of the @code{make} program plus a copyright, a list 8152of authors, and a notice that there is no warranty; then exit. 8153 8154@item -w 8155@cindex @code{-w} 8156@itemx --print-directory 8157@cindex @code{--print-directory} 8158Print a message containing the working directory both before and after 8159executing the makefile. This may be useful for tracking down errors 8160from complicated nests of recursive @code{make} commands. 8161@xref{Recursion, ,Recursive Use of @code{make}}. (In practice, you 8162rarely need to specify this option since @samp{make} does it for you; 8163see @ref{-w Option, ,The @samp{--print-directory} Option}.) 8164 8165@item --no-print-directory 8166@cindex @code{--no-print-directory} 8167Disable printing of the working directory under @code{-w}. 8168This option is useful when @code{-w} is turned on automatically, 8169but you do not want to see the extra messages. 8170@xref{-w Option, ,The @samp{--print-directory} Option}. 8171 8172@item -W @var{file} 8173@cindex @code{-W} 8174@itemx --what-if=@var{file} 8175@cindex @code{--what-if} 8176@itemx --new-file=@var{file} 8177@cindex @code{--new-file} 8178@itemx --assume-new=@var{file} 8179@cindex @code{--assume-new} 8180Pretend that the target @var{file} has just been modified. When used 8181with the @samp{-n} flag, this shows you what would happen if you were 8182to modify that file. Without @samp{-n}, it is almost the same as 8183running a @code{touch} command on the given file before running 8184@code{make}, except that the modification time is changed only in the 8185imagination of @code{make}. 8186@xref{Instead of Execution, ,Instead of Executing the Commands}. 8187 8188@item --warn-undefined-variables 8189@cindex @code{--warn-undefined-variables} 8190@cindex variables, warning for undefined 8191@cindex undefined variables, warning message 8192Issue a warning message whenever @code{make} sees a reference to an 8193undefined variable. This can be helpful when you are trying to debug 8194makefiles which use variables in complex ways. 8195@end table 8196 8197@node Implicit Rules, Archives, Running, Top 8198@chapter Using Implicit Rules 8199@cindex implicit rule 8200@cindex rule, implicit 8201 8202Certain standard ways of remaking target files are used very often. For 8203example, one customary way to make an object file is from a C source file 8204using the C compiler, @code{cc}. 8205 8206@dfn{Implicit rules} tell @code{make} how to use customary techniques so 8207that you do not have to specify them in detail when you want to use 8208them. For example, there is an implicit rule for C compilation. File 8209names determine which implicit rules are run. For example, C 8210compilation typically takes a @file{.c} file and makes a @file{.o} file. 8211So @code{make} applies the implicit rule for C compilation when it sees 8212this combination of file name endings.@refill 8213 8214A chain of implicit rules can apply in sequence; for example, @code{make} 8215will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file. 8216@iftex 8217@xref{Chained Rules, ,Chains of Implicit Rules}. 8218@end iftex 8219 8220The built-in implicit rules use several variables in their commands so 8221that, by changing the values of the variables, you can change the way the 8222implicit rule works. For example, the variable @code{CFLAGS} controls the 8223flags given to the C compiler by the implicit rule for C compilation. 8224@iftex 8225@xref{Implicit Variables, ,Variables Used by Implicit Rules}. 8226@end iftex 8227 8228You can define your own implicit rules by writing @dfn{pattern rules}. 8229@iftex 8230@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}. 8231@end iftex 8232 8233@dfn{Suffix rules} are a more limited way to define implicit rules. 8234Pattern rules are more general and clearer, but suffix rules are 8235retained for compatibility. 8236@iftex 8237@xref{Suffix Rules, ,Old-Fashioned Suffix Rules}. 8238@end iftex 8239 8240@menu 8241* Using Implicit:: How to use an existing implicit rule 8242 to get the commands for updating a file. 8243* Catalogue of Rules:: A list of built-in implicit rules. 8244* Implicit Variables:: How to change what predefined rules do. 8245* Chained Rules:: How to use a chain of implicit rules. 8246* Pattern Rules:: How to define new implicit rules. 8247* Last Resort:: How to define commands for rules which 8248 cannot find any. 8249* Suffix Rules:: The old-fashioned style of implicit rule. 8250* Implicit Rule Search:: The precise algorithm for applying 8251 implicit rules. 8252@end menu 8253 8254@node Using Implicit, Catalogue of Rules, Implicit Rules, Implicit Rules 8255@section Using Implicit Rules 8256@cindex implicit rule, how to use 8257@cindex rule, implicit, how to use 8258 8259To allow @code{make} to find a customary method for updating a target file, 8260all you have to do is refrain from specifying commands yourself. Either 8261write a rule with no command lines, or don't write a rule at all. Then 8262@code{make} will figure out which implicit rule to use based on which 8263kind of source file exists or can be made. 8264 8265For example, suppose the makefile looks like this: 8266 8267@example 8268foo : foo.o bar.o 8269 cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS) 8270@end example 8271 8272@noindent 8273Because you mention @file{foo.o} but do not give a rule for it, @code{make} 8274will automatically look for an implicit rule that tells how to update it. 8275This happens whether or not the file @file{foo.o} currently exists. 8276 8277If an implicit rule is found, it can supply both commands and one or 8278more prerequisites (the source files). You would want to write a rule 8279for @file{foo.o} with no command lines if you need to specify additional 8280prerequisites, such as header files, that the implicit rule cannot 8281supply. 8282 8283Each implicit rule has a target pattern and prerequisite patterns. There may 8284be many implicit rules with the same target pattern. For example, numerous 8285rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler; 8286another, from a @samp{.p} file with the Pascal compiler; and so on. The rule 8287that actually applies is the one whose prerequisites exist or can be made. 8288So, if you have a file @file{foo.c}, @code{make} will run the C compiler; 8289otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal 8290compiler; and so on. 8291 8292Of course, when you write the makefile, you know which implicit rule you 8293want @code{make} to use, and you know it will choose that one because you 8294know which possible prerequisite files are supposed to exist. 8295@xref{Catalogue of Rules, ,Catalogue of Implicit Rules}, 8296for a catalogue of all the predefined implicit rules. 8297 8298Above, we said an implicit rule applies if the required prerequisites ``exist 8299or can be made''. A file ``can be made'' if it is mentioned explicitly in 8300the makefile as a target or a prerequisite, or if an implicit rule can be 8301recursively found for how to make it. When an implicit prerequisite is the 8302result of another implicit rule, we say that @dfn{chaining} is occurring. 8303@xref{Chained Rules, ,Chains of Implicit Rules}. 8304 8305In general, @code{make} searches for an implicit rule for each target, and 8306for each double-colon rule, that has no commands. A file that is mentioned 8307only as a prerequisite is considered a target whose rule specifies nothing, 8308so implicit rule search happens for it. @xref{Implicit Rule Search, ,Implicit Rule Search Algorithm}, for the 8309details of how the search is done. 8310 8311Note that explicit prerequisites do not influence implicit rule search. 8312For example, consider this explicit rule: 8313 8314@example 8315foo.o: foo.p 8316@end example 8317 8318@noindent 8319The prerequisite on @file{foo.p} does not necessarily mean that 8320@code{make} will remake @file{foo.o} according to the implicit rule to 8321make an object file, a @file{.o} file, from a Pascal source file, a 8322@file{.p} file. For example, if @file{foo.c} also exists, the implicit 8323rule to make an object file from a C source file is used instead, 8324because it appears before the Pascal rule in the list of predefined 8325implicit rules (@pxref{Catalogue of Rules, , Catalogue of Implicit 8326Rules}). 8327 8328If you do not want an implicit rule to be used for a target that has no 8329commands, you can give that target empty commands by writing a semicolon 8330(@pxref{Empty Commands, ,Defining Empty Commands}). 8331 8332@node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules 8333@section Catalogue of Implicit Rules 8334@cindex implicit rule, predefined 8335@cindex rule, implicit, predefined 8336 8337Here is a catalogue of predefined implicit rules which are always 8338available unless the makefile explicitly overrides or cancels them. 8339@xref{Canceling Rules, ,Canceling Implicit Rules}, for information on 8340canceling or overriding an implicit rule. The @samp{-r} or 8341@samp{--no-builtin-rules} option cancels all predefined rules. 8342 8343This manual only documents the default rules available on POSIX-based 8344operating systems. Other operating systems, such as VMS, Windows, 8345OS/2, etc. may have different sets of default rules. To see the full 8346list of default rules and variables available in your version of GNU 8347@code{make}, run @samp{make -p} in a directory with no makefile. 8348 8349Not all of these rules will always be defined, even when the @samp{-r} 8350option is not given. Many of the predefined implicit rules are 8351implemented in @code{make} as suffix rules, so which ones will be 8352defined depends on the @dfn{suffix list} (the list of prerequisites of 8353the special target @code{.SUFFIXES}). The default suffix list is: 8354@code{.out}, @code{.a}, @code{.ln}, @code{.o}, @code{.c}, @code{.cc}, 8355@code{.C}, @code{.cpp}, @code{.p}, @code{.f}, @code{.F}, @code{.r}, @code{.y}, 8356@code{.l}, @code{.s}, @code{.S}, @code{.mod}, @code{.sym}, @code{.def}, 8357@code{.h}, @code{.info}, @code{.dvi}, @code{.tex}, @code{.texinfo}, 8358@code{.texi}, @code{.txinfo}, @code{.w}, @code{.ch} @code{.web}, 8359@code{.sh}, @code{.elc}, @code{.el}. All of the implicit rules 8360described below whose prerequisites have one of these suffixes are 8361actually suffix rules. If you modify the suffix list, the only 8362predefined suffix rules in effect will be those named by one or two of 8363the suffixes that are on the list you specify; rules whose suffixes fail 8364to be on the list are disabled. @xref{Suffix Rules, ,Old-Fashioned 8365Suffix Rules}, for full details on suffix rules. 8366 8367@table @asis 8368@item Compiling C programs 8369@cindex C, rule to compile 8370@pindex cc 8371@pindex gcc 8372@pindex .o 8373@pindex .c 8374@file{@var{n}.o} is made automatically from @file{@var{n}.c} with 8375a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill 8376 8377@item Compiling C++ programs 8378@cindex C++, rule to compile 8379@pindex g++ 8380@pindex .cc 8381@pindex .cpp 8382@pindex .C 8383@file{@var{n}.o} is made automatically from @file{@var{n}.cc}, 8384@file{@var{n}.cpp}, or @file{@var{n}.C} with a command of the form 8385@samp{$(CXX) -c $(CPPFLAGS) $(CXXFLAGS)}. We encourage you to use the 8386suffix @samp{.cc} for C++ source files instead of @samp{.C}.@refill 8387 8388@item Compiling Pascal programs 8389@cindex Pascal, rule to compile 8390@pindex pc 8391@pindex .p 8392@file{@var{n}.o} is made automatically from @file{@var{n}.p} 8393with the command @samp{$(PC) -c $(PFLAGS)}.@refill 8394 8395@item Compiling Fortran and Ratfor programs 8396@cindex Fortran, rule to compile 8397@cindex Ratfor, rule to compile 8398@pindex f77 8399@pindex .f 8400@pindex .r 8401@pindex .F 8402@file{@var{n}.o} is made automatically from @file{@var{n}.r}, 8403@file{@var{n}.F} or @file{@var{n}.f} by running the 8404Fortran compiler. The precise command used is as follows:@refill 8405 8406@table @samp 8407@item .f 8408@samp{$(FC) -c $(FFLAGS)}. 8409@item .F 8410@samp{$(FC) -c $(FFLAGS) $(CPPFLAGS)}. 8411@item .r 8412@samp{$(FC) -c $(FFLAGS) $(RFLAGS)}. 8413@end table 8414 8415@item Preprocessing Fortran and Ratfor programs 8416@file{@var{n}.f} is made automatically from @file{@var{n}.r} or 8417@file{@var{n}.F}. This rule runs just the preprocessor to convert a 8418Ratfor or preprocessable Fortran program into a strict Fortran 8419program. The precise command used is as follows:@refill 8420 8421@table @samp 8422@item .F 8423@samp{$(FC) -F $(CPPFLAGS) $(FFLAGS)}. 8424@item .r 8425@samp{$(FC) -F $(FFLAGS) $(RFLAGS)}. 8426@end table 8427 8428@item Compiling Modula-2 programs 8429@cindex Modula-2, rule to compile 8430@pindex m2c 8431@pindex .sym 8432@pindex .def 8433@pindex .mod 8434@file{@var{n}.sym} is made from @file{@var{n}.def} with a command 8435of the form @samp{$(M2C) $(M2FLAGS) $(DEFFLAGS)}. @file{@var{n}.o} 8436is made from @file{@var{n}.mod}; the form is: 8437@w{@samp{$(M2C) $(M2FLAGS) $(MODFLAGS)}}.@refill 8438 8439@need 1200 8440@item Assembling and preprocessing assembler programs 8441@cindex assembly, rule to compile 8442@pindex as 8443@pindex .s 8444@file{@var{n}.o} is made automatically from @file{@var{n}.s} by 8445running the assembler, @code{as}. The precise command is 8446@samp{$(AS) $(ASFLAGS)}.@refill 8447 8448@pindex .S 8449@file{@var{n}.s} is made automatically from @file{@var{n}.S} by 8450running the C preprocessor, @code{cpp}. The precise command is 8451@w{@samp{$(CPP) $(CPPFLAGS)}}. 8452 8453@item Linking a single object file 8454@cindex linking, predefined rule for 8455@pindex ld 8456@pindex .o 8457@file{@var{n}} is made automatically from @file{@var{n}.o} by running 8458the linker (usually called @code{ld}) via the C compiler. The precise 8459command used is @w{@samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES) $(LDLIBS)}}. 8460 8461This rule does the right thing for a simple program with only one 8462source file. It will also do the right thing if there are multiple 8463object files (presumably coming from various other source files), one 8464of which has a name matching that of the executable file. Thus, 8465 8466@example 8467x: y.o z.o 8468@end example 8469 8470@noindent 8471when @file{x.c}, @file{y.c} and @file{z.c} all exist will execute: 8472 8473@example 8474@group 8475cc -c x.c -o x.o 8476cc -c y.c -o y.o 8477cc -c z.c -o z.o 8478cc x.o y.o z.o -o x 8479rm -f x.o 8480rm -f y.o 8481rm -f z.o 8482@end group 8483@end example 8484 8485@noindent 8486In more complicated cases, such as when there is no object file whose 8487name derives from the executable file name, you must write an explicit 8488command for linking. 8489 8490Each kind of file automatically made into @samp{.o} object files will 8491be automatically linked by using the compiler (@samp{$(CC)}, 8492@samp{$(FC)} or @samp{$(PC)}; the C compiler @samp{$(CC)} is used to 8493assemble @samp{.s} files) without the @samp{-c} option. This could be 8494done by using the @samp{.o} object files as intermediates, but it is 8495faster to do the compiling and linking in one step, so that's how it's 8496done.@refill 8497 8498@item Yacc for C programs 8499@pindex yacc 8500@cindex Yacc, rule to run 8501@pindex .y 8502@file{@var{n}.c} is made automatically from @file{@var{n}.y} by 8503running Yacc with the command @samp{$(YACC) $(YFLAGS)}. 8504 8505@item Lex for C programs 8506@pindex lex 8507@cindex Lex, rule to run 8508@pindex .l 8509@file{@var{n}.c} is made automatically from @file{@var{n}.l} by 8510running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}. 8511 8512@item Lex for Ratfor programs 8513@file{@var{n}.r} is made automatically from @file{@var{n}.l} by 8514running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}. 8515 8516The convention of using the same suffix @samp{.l} for all Lex files 8517regardless of whether they produce C code or Ratfor code makes it 8518impossible for @code{make} to determine automatically which of the two 8519languages you are using in any particular case. If @code{make} is 8520called upon to remake an object file from a @samp{.l} file, it must 8521guess which compiler to use. It will guess the C compiler, because 8522that is more common. If you are using Ratfor, make sure @code{make} 8523knows this by mentioning @file{@var{n}.r} in the makefile. Or, if you 8524are using Ratfor exclusively, with no C files, remove @samp{.c} from 8525the list of implicit rule suffixes with:@refill 8526 8527@example 8528@group 8529.SUFFIXES: 8530.SUFFIXES: .o .r .f .l @dots{} 8531@end group 8532@end example 8533 8534@item Making Lint Libraries from C, Yacc, or Lex programs 8535@pindex lint 8536@cindex @code{lint}, rule to run 8537@pindex .ln 8538@file{@var{n}.ln} is made from @file{@var{n}.c} by running @code{lint}. 8539The precise command is @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}. 8540The same command is used on the C code produced from 8541@file{@var{n}.y} or @file{@var{n}.l}.@refill 8542 8543@item @TeX{} and Web 8544@cindex @TeX{}, rule to run 8545@cindex Web, rule to run 8546@pindex tex 8547@pindex cweave 8548@pindex weave 8549@pindex tangle 8550@pindex ctangle 8551@pindex .dvi 8552@pindex .tex 8553@pindex .web 8554@pindex .w 8555@pindex .ch 8556@file{@var{n}.dvi} is made from @file{@var{n}.tex} with the command 8557@samp{$(TEX)}. @file{@var{n}.tex} is made from @file{@var{n}.web} with 8558@samp{$(WEAVE)}, or from @file{@var{n}.w} (and from @file{@var{n}.ch} if 8559it exists or can be made) with @samp{$(CWEAVE)}. @file{@var{n}.p} is 8560made from @file{@var{n}.web} with @samp{$(TANGLE)} and @file{@var{n}.c} 8561is made from @file{@var{n}.w} (and from @file{@var{n}.ch} if it exists 8562or can be made) with @samp{$(CTANGLE)}.@refill 8563 8564@item Texinfo and Info 8565@cindex Texinfo, rule to format 8566@cindex Info, rule to format 8567@pindex texi2dvi 8568@pindex makeinfo 8569@pindex .texinfo 8570@pindex .info 8571@pindex .texi 8572@pindex .txinfo 8573@file{@var{n}.dvi} is made from @file{@var{n}.texinfo}, 8574@file{@var{n}.texi}, or @file{@var{n}.txinfo}, with the command 8575@w{@samp{$(TEXI2DVI) $(TEXI2DVI_FLAGS)}}. @file{@var{n}.info} is made from 8576@file{@var{n}.texinfo}, @file{@var{n}.texi}, or @file{@var{n}.txinfo}, with 8577the command @w{@samp{$(MAKEINFO) $(MAKEINFO_FLAGS)}}. 8578 8579@item RCS 8580@cindex RCS, rule to extract from 8581@pindex co 8582@pindex ,v @r{(RCS file extension)} 8583Any file @file{@var{n}} is extracted if necessary from an RCS file 8584named either @file{@var{n},v} or @file{RCS/@var{n},v}. The precise 8585command used is @w{@samp{$(CO) $(COFLAGS)}}. @file{@var{n}} will not be 8586extracted from RCS if it already exists, even if the RCS file is 8587newer. The rules for RCS are terminal 8588(@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}), 8589so RCS files cannot be generated from another source; they must 8590actually exist.@refill 8591 8592@item SCCS 8593@cindex SCCS, rule to extract from 8594@pindex get 8595@pindex s. @r{(SCCS file prefix)} 8596Any file @file{@var{n}} is extracted if necessary from an SCCS file 8597named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}. The precise 8598command used is @w{@samp{$(GET) $(GFLAGS)}}. The rules for SCCS are 8599terminal (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}), 8600so SCCS files cannot be generated from another source; they must 8601actually exist.@refill 8602 8603@pindex .sh 8604For the benefit of SCCS, a file @file{@var{n}} is copied from 8605@file{@var{n}.sh} and made executable (by everyone). This is for 8606shell scripts that are checked into SCCS. Since RCS preserves the 8607execution permission of a file, you do not need to use this feature 8608with RCS.@refill 8609 8610We recommend that you avoid using of SCCS. RCS is widely held to be 8611superior, and is also free. By choosing free software in place of 8612comparable (or inferior) proprietary software, you support the free 8613software movement. 8614@end table 8615 8616Usually, you want to change only the variables listed in the table 8617above, which are documented in the following section. 8618 8619However, the commands in built-in implicit rules actually use 8620variables such as @code{COMPILE.c}, @code{LINK.p}, and 8621@code{PREPROCESS.S}, whose values contain the commands listed above. 8622 8623@code{make} follows the convention that the rule to compile a 8624@file{.@var{x}} source file uses the variable @code{COMPILE.@var{x}}. 8625Similarly, the rule to produce an executable from a @file{.@var{x}} 8626file uses @code{LINK.@var{x}}; and the rule to preprocess a 8627@file{.@var{x}} file uses @code{PREPROCESS.@var{x}}. 8628 8629@vindex OUTPUT_OPTION 8630Every rule that produces an object file uses the variable 8631@code{OUTPUT_OPTION}. @code{make} defines this variable either to 8632contain @samp{-o $@@}, or to be empty, depending on a compile-time 8633option. You need the @samp{-o} option to ensure that the output goes 8634into the right file when the source file is in a different directory, 8635as when using @code{VPATH} (@pxref{Directory Search}). However, 8636compilers on some systems do not accept a @samp{-o} switch for object 8637files. If you use such a system, and use @code{VPATH}, some 8638compilations will put their output in the wrong place. 8639A possible workaround for this problem is to give @code{OUTPUT_OPTION} 8640the value @w{@samp{; mv $*.o $@@}}. 8641 8642@node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit Rules 8643@section Variables Used by Implicit Rules 8644@cindex flags for compilers 8645 8646The commands in built-in implicit rules make liberal use of certain 8647predefined variables. You can alter the values of these variables in 8648the makefile, with arguments to @code{make}, or in the environment to 8649alter how the implicit rules work without redefining the rules 8650themselves. You can cancel all variables used by implicit rules with 8651the @samp{-R} or @samp{--no-builtin-variables} option. 8652 8653For example, the command used to compile a C source file actually says 8654@samp{$(CC) -c $(CFLAGS) $(CPPFLAGS)}. The default values of the variables 8655used are @samp{cc} and nothing, resulting in the command @samp{cc -c}. By 8656redefining @samp{CC} to @samp{ncc}, you could cause @samp{ncc} to be 8657used for all C compilations performed by the implicit rule. By redefining 8658@samp{CFLAGS} to be @samp{-g}, you could pass the @samp{-g} option to 8659each compilation. @emph{All} implicit rules that do C compilation use 8660@samp{$(CC)} to get the program name for the compiler and @emph{all} 8661include @samp{$(CFLAGS)} among the arguments given to the compiler.@refill 8662 8663The variables used in implicit rules fall into two classes: those that are 8664names of programs (like @code{CC}) and those that contain arguments for the 8665programs (like @code{CFLAGS}). (The ``name of a program'' may also contain 8666some command arguments, but it must start with an actual executable program 8667name.) If a variable value contains more than one argument, separate them 8668with spaces. 8669 8670The following tables describe of some of the more commonly-used predefined 8671variables. This list is not exhaustive, and the default values shown here may 8672not be what are selected by @code{make} for your environment. To see the 8673complete list of predefined variables for your instance of GNU @code{make} you 8674can run @samp{make -p} in a directory with no makefiles. 8675 8676Here is a table of some of the more common variables used as names of 8677programs in built-in rules: 8678makefiles. 8679 8680@table @code 8681@item AR 8682@vindex AR 8683Archive-maintaining program; default @samp{ar}. 8684@pindex ar 8685 8686@item AS 8687@vindex AS 8688Program for compiling assembly files; default @samp{as}. 8689@pindex as 8690 8691@item CC 8692@vindex CC 8693Program for compiling C programs; default @samp{cc}. 8694@pindex cc 8695 8696@item CO 8697@vindex CO 8698Program for checking out files from RCS; default @samp{co}. 8699@pindex cc 8700 8701@item CXX 8702@vindex CXX 8703Program for compiling C++ programs; default @samp{g++}. 8704@pindex g++ 8705 8706@item CO 8707@vindex CO 8708Program for extracting a file from RCS; default @samp{co}. 8709@pindex co 8710 8711@item CPP 8712@vindex CPP 8713Program for running the C preprocessor, with results to standard output; 8714default @samp{$(CC) -E}. 8715 8716@item FC 8717@vindex FC 8718Program for compiling or preprocessing Fortran and Ratfor programs; 8719default @samp{f77}. 8720@pindex f77 8721 8722@item GET 8723@vindex GET 8724Program for extracting a file from SCCS; default @samp{get}. 8725@pindex get 8726 8727@item LEX 8728@vindex LEX 8729Program to use to turn Lex grammars into source code; default @samp{lex}. 8730@pindex lex 8731 8732@item YACC 8733@vindex YACC 8734Program to use to turn Yacc grammars into source code; default @samp{yacc}. 8735@pindex yacc 8736 8737@item LINT 8738@vindex LINT 8739Program to use to run lint on source code; default @samp{lint}. 8740@pindex lint 8741 8742@item M2C 8743@vindex M2C 8744Program to use to compile Modula-2 source code; default @samp{m2c}. 8745@pindex m2c 8746 8747@item PC 8748@vindex PC 8749Program for compiling Pascal programs; default @samp{pc}. 8750@pindex pc 8751 8752@item MAKEINFO 8753@vindex MAKEINFO 8754Program to convert a Texinfo source file into an Info file; default 8755@samp{makeinfo}. 8756@pindex makeinfo 8757 8758@item TEX 8759@vindex TEX 8760Program to make @TeX{} @sc{dvi} files from @TeX{} source; 8761default @samp{tex}. 8762@pindex tex 8763 8764@item TEXI2DVI 8765@vindex TEXI2DVI 8766Program to make @TeX{} @sc{dvi} files from Texinfo source; 8767default @samp{texi2dvi}. 8768@pindex texi2dvi 8769 8770@item WEAVE 8771@vindex WEAVE 8772Program to translate Web into @TeX{}; default @samp{weave}. 8773@pindex weave 8774 8775@item CWEAVE 8776@vindex CWEAVE 8777Program to translate C Web into @TeX{}; default @samp{cweave}. 8778@pindex cweave 8779 8780@item TANGLE 8781@vindex TANGLE 8782Program to translate Web into Pascal; default @samp{tangle}. 8783@pindex tangle 8784 8785@item CTANGLE 8786@vindex CTANGLE 8787Program to translate C Web into C; default @samp{ctangle}. 8788@pindex ctangle 8789 8790@item RM 8791@vindex RM 8792Command to remove a file; default @samp{rm -f}. 8793@pindex rm 8794@end table 8795 8796Here is a table of variables whose values are additional arguments for the 8797programs above. The default values for all of these is the empty 8798string, unless otherwise noted. 8799 8800@table @code 8801@item ARFLAGS 8802@vindex ARFLAGS 8803Flags to give the archive-maintaining program; default @samp{rv}. 8804 8805@item ASFLAGS 8806@vindex ASFLAGS 8807Extra flags to give to the assembler (when explicitly 8808invoked on a @samp{.s} or @samp{.S} file). 8809 8810@item CFLAGS 8811@vindex CFLAGS 8812Extra flags to give to the C compiler. 8813 8814@item CXXFLAGS 8815@vindex CXXFLAGS 8816Extra flags to give to the C++ compiler. 8817 8818@item COFLAGS 8819@vindex COFLAGS 8820Extra flags to give to the RCS @code{co} program. 8821 8822@item CPPFLAGS 8823@vindex CPPFLAGS 8824Extra flags to give to the C preprocessor and programs 8825that use it (the C and Fortran compilers). 8826 8827@item FFLAGS 8828@vindex FFLAGS 8829Extra flags to give to the Fortran compiler. 8830 8831@item GFLAGS 8832@vindex GFLAGS 8833Extra flags to give to the SCCS @code{get} program. 8834 8835@item LDFLAGS 8836@vindex LDFLAGS 8837Extra flags to give to compilers when they are supposed to invoke the linker, 8838@samp{ld}. 8839 8840@item LFLAGS 8841@vindex LFLAGS 8842Extra flags to give to Lex. 8843 8844@item YFLAGS 8845@vindex YFLAGS 8846Extra flags to give to Yacc. 8847 8848@item PFLAGS 8849@vindex PFLAGS 8850Extra flags to give to the Pascal compiler. 8851 8852@item RFLAGS 8853@vindex RFLAGS 8854Extra flags to give to the Fortran compiler for Ratfor programs. 8855 8856@item LINTFLAGS 8857@vindex LINTFLAGS 8858Extra flags to give to lint. 8859@end table 8860 8861@node Chained Rules, Pattern Rules, Implicit Variables, Implicit Rules 8862@section Chains of Implicit Rules 8863 8864@cindex chains of rules 8865@cindex rule, implicit, chains of 8866Sometimes a file can be made by a sequence of implicit rules. For example, 8867a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running 8868first Yacc and then @code{cc}. Such a sequence is called a @dfn{chain}. 8869 8870If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no 8871special searching is required: @code{make} finds that the object file can 8872be made by C compilation from @file{@var{n}.c}; later on, when considering 8873how to make @file{@var{n}.c}, the rule for running Yacc is 8874used. Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are 8875updated.@refill 8876 8877@cindex intermediate files 8878@cindex files, intermediate 8879However, even if @file{@var{n}.c} does not exist and is not mentioned, 8880@code{make} knows how to envision it as the missing link between 8881@file{@var{n}.o} and @file{@var{n}.y}! In this case, @file{@var{n}.c} is 8882called an @dfn{intermediate file}. Once @code{make} has decided to use the 8883intermediate file, it is entered in the data base as if it had been 8884mentioned in the makefile, along with the implicit rule that says how to 8885create it.@refill 8886 8887Intermediate files are remade using their rules just like all other 8888files. But intermediate files are treated differently in two ways. 8889 8890The first difference is what happens if the intermediate file does not 8891exist. If an ordinary file @var{b} does not exist, and @code{make} 8892considers a target that depends on @var{b}, it invariably creates 8893@var{b} and then updates the target from @var{b}. But if @var{b} is an 8894intermediate file, then @code{make} can leave well enough alone. It 8895won't bother updating @var{b}, or the ultimate target, unless some 8896prerequisite of @var{b} is newer than that target or there is some other 8897reason to update that target. 8898 8899The second difference is that if @code{make} @emph{does} create @var{b} 8900in order to update something else, it deletes @var{b} later on after it 8901is no longer needed. Therefore, an intermediate file which did not 8902exist before @code{make} also does not exist after @code{make}. 8903@code{make} reports the deletion to you by printing a @samp{rm -f} 8904command showing which file it is deleting. 8905 8906Ordinarily, a file cannot be intermediate if it is mentioned in the 8907makefile as a target or prerequisite. However, you can explicitly mark a 8908file as intermediate by listing it as a prerequisite of the special target 8909@code{.INTERMEDIATE}. This takes effect even if the file is mentioned 8910explicitly in some other way. 8911 8912@cindex intermediate files, preserving 8913@cindex preserving intermediate files 8914@cindex secondary files 8915You can prevent automatic deletion of an intermediate file by marking it 8916as a @dfn{secondary} file. To do this, list it as a prerequisite of the 8917special target @code{.SECONDARY}. When a file is secondary, @code{make} 8918will not create the file merely because it does not already exist, but 8919@code{make} does not automatically delete the file. Marking a file as 8920secondary also marks it as intermediate. 8921 8922You can list the target pattern of an implicit rule (such as @samp{%.o}) 8923as a prerequisite of the special target @code{.PRECIOUS} to preserve 8924intermediate files made by implicit rules whose target patterns match 8925that file's name; see @ref{Interrupts}.@refill 8926@cindex preserving with @code{.PRECIOUS} 8927@cindex @code{.PRECIOUS} intermediate files 8928 8929A chain can involve more than two implicit rules. For example, it is 8930possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS, 8931Yacc and @code{cc}. Then both @file{foo.y} and @file{foo.c} are 8932intermediate files that are deleted at the end.@refill 8933 8934No single implicit rule can appear more than once in a chain. This means 8935that @code{make} will not even consider such a ridiculous thing as making 8936@file{foo} from @file{foo.o.o} by running the linker twice. This 8937constraint has the added benefit of preventing any infinite loop in the 8938search for an implicit rule chain. 8939 8940There are some special implicit rules to optimize certain cases that would 8941otherwise be handled by rule chains. For example, making @file{foo} from 8942@file{foo.c} could be handled by compiling and linking with separate 8943chained rules, using @file{foo.o} as an intermediate file. But what 8944actually happens is that a special rule for this case does the compilation 8945and linking with a single @code{cc} command. The optimized rule is used in 8946preference to the step-by-step chain because it comes earlier in the 8947ordering of rules. 8948 8949@node Pattern Rules, Last Resort, Chained Rules, Implicit Rules 8950@section Defining and Redefining Pattern Rules 8951 8952You define an implicit rule by writing a @dfn{pattern rule}. A pattern 8953rule looks like an ordinary rule, except that its target contains the 8954character @samp{%} (exactly one of them). The target is considered a 8955pattern for matching file names; the @samp{%} can match any nonempty 8956substring, while other characters match only themselves. The prerequisites 8957likewise use @samp{%} to show how their names relate to the target name. 8958 8959Thus, a pattern rule @samp{%.o : %.c} says how to make any file 8960@file{@var{stem}.o} from another file @file{@var{stem}.c}.@refill 8961 8962Note that expansion using @samp{%} in pattern rules occurs 8963@strong{after} any variable or function expansions, which take place 8964when the makefile is read. @xref{Using Variables, , How to Use 8965Variables}, and @ref{Functions, ,Functions for Transforming Text}. 8966 8967@menu 8968* Pattern Intro:: An introduction to pattern rules. 8969* Pattern Examples:: Examples of pattern rules. 8970* Automatic Variables:: How to use automatic variables in the 8971 commands of implicit rules. 8972* Pattern Match:: How patterns match. 8973* Match-Anything Rules:: Precautions you should take prior to 8974 defining rules that can match any 8975 target file whatever. 8976* Canceling Rules:: How to override or cancel built-in rules. 8977@end menu 8978 8979@node Pattern Intro, Pattern Examples, Pattern Rules, Pattern Rules 8980@subsection Introduction to Pattern Rules 8981@cindex pattern rule 8982@cindex rule, pattern 8983 8984A pattern rule contains the character @samp{%} (exactly one of them) 8985in the target; otherwise, it looks exactly like an ordinary rule. The 8986target is a pattern for matching file names; the @samp{%} matches any 8987nonempty substring, while other characters match only themselves. 8988@cindex target pattern, implicit 8989@cindex @code{%}, in pattern rules 8990 8991For example, @samp{%.c} as a pattern matches any file name that ends in 8992@samp{.c}. @samp{s.%.c} as a pattern matches any file name that starts 8993with @samp{s.}, ends in @samp{.c} and is at least five characters long. 8994(There must be at least one character to match the @samp{%}.) The substring 8995that the @samp{%} matches is called the @dfn{stem}.@refill 8996 8997@samp{%} in a prerequisite of a pattern rule stands for the same stem 8998that was matched by the @samp{%} in the target. In order for the 8999pattern rule to apply, its target pattern must match the file name 9000under consideration and all of its prerequisites (after pattern 9001substitution) must name files that exist or can be made. These files 9002become prerequisites of the target. 9003@cindex prerequisite pattern, implicit 9004 9005Thus, a rule of the form 9006 9007@example 9008%.o : %.c ; @var{command}@dots{} 9009@end example 9010 9011@noindent 9012specifies how to make a file @file{@var{n}.o}, with another file 9013@file{@var{n}.c} as its prerequisite, provided that @file{@var{n}.c} 9014exists or can be made. 9015 9016There may also be prerequisites that do not use @samp{%}; such a prerequisite 9017attaches to every file made by this pattern rule. These unvarying 9018prerequisites are useful occasionally. 9019 9020A pattern rule need not have any prerequisites that contain @samp{%}, or 9021in fact any prerequisites at all. Such a rule is effectively a general 9022wildcard. It provides a way to make any file that matches the target 9023pattern. @xref{Last Resort}. 9024 9025@c !!! The end of of this paragraph should be rewritten. --bob 9026Pattern rules may have more than one target. Unlike normal rules, this 9027does not act as many different rules with the same prerequisites and 9028commands. If a pattern rule has multiple targets, @code{make} knows that 9029the rule's commands are responsible for making all of the targets. The 9030commands are executed only once to make all the targets. When searching 9031for a pattern rule to match a target, the target patterns of a rule other 9032than the one that matches the target in need of a rule are incidental: 9033@code{make} worries only about giving commands and prerequisites to the file 9034presently in question. However, when this file's commands are run, the 9035other targets are marked as having been updated themselves. 9036@cindex multiple targets, in pattern rule 9037@cindex target, multiple in pattern rule 9038 9039The order in which pattern rules appear in the makefile is important 9040since this is the order in which they are considered. 9041Of equally applicable 9042rules, only the first one found is used. The rules you write take precedence 9043over those that are built in. Note however, that a rule whose 9044prerequisites actually exist or are mentioned always takes priority over a 9045rule with prerequisites that must be made by chaining other implicit rules. 9046@cindex pattern rules, order of 9047@cindex order of pattern rules 9048 9049@node Pattern Examples, Automatic Variables, Pattern Intro, Pattern Rules 9050@subsection Pattern Rule Examples 9051 9052Here are some examples of pattern rules actually predefined in 9053@code{make}. First, the rule that compiles @samp{.c} files into @samp{.o} 9054files:@refill 9055 9056@example 9057%.o : %.c 9058 $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@@ 9059@end example 9060 9061@noindent 9062defines a rule that can make any file @file{@var{x}.o} from 9063@file{@var{x}.c}. The command uses the automatic variables @samp{$@@} and 9064@samp{$<} to substitute the names of the target file and the source file 9065in each case where the rule applies (@pxref{Automatic Variables}).@refill 9066 9067Here is a second built-in rule: 9068 9069@example 9070% :: RCS/%,v 9071 $(CO) $(COFLAGS) $< 9072@end example 9073 9074@noindent 9075defines a rule that can make any file @file{@var{x}} whatsoever from a 9076corresponding file @file{@var{x},v} in the subdirectory @file{RCS}. Since 9077the target is @samp{%}, this rule will apply to any file whatever, provided 9078the appropriate prerequisite file exists. The double colon makes the rule 9079@dfn{terminal}, which means that its prerequisite may not be an intermediate 9080file (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}).@refill 9081 9082@need 500 9083This pattern rule has two targets: 9084 9085@example 9086@group 9087%.tab.c %.tab.h: %.y 9088 bison -d $< 9089@end group 9090@end example 9091 9092@noindent 9093@c The following paragraph is rewritten to avoid overfull hboxes 9094This tells @code{make} that the command @samp{bison -d @var{x}.y} will 9095make both @file{@var{x}.tab.c} and @file{@var{x}.tab.h}. If the file 9096@file{foo} depends on the files @file{parse.tab.o} and @file{scan.o} 9097and the file @file{scan.o} depends on the file @file{parse.tab.h}, 9098when @file{parse.y} is changed, the command @samp{bison -d parse.y} 9099will be executed only once, and the prerequisites of both 9100@file{parse.tab.o} and @file{scan.o} will be satisfied. (Presumably 9101the file @file{parse.tab.o} will be recompiled from @file{parse.tab.c} 9102and the file @file{scan.o} from @file{scan.c}, while @file{foo} is 9103linked from @file{parse.tab.o}, @file{scan.o}, and its other 9104prerequisites, and it will execute happily ever after.)@refill 9105 9106@node Automatic Variables, Pattern Match, Pattern Examples, Pattern Rules 9107@subsection Automatic Variables 9108@cindex automatic variables 9109@cindex variables, automatic 9110@cindex variables, and implicit rule 9111 9112Suppose you are writing a pattern rule to compile a @samp{.c} file into a 9113@samp{.o} file: how do you write the @samp{cc} command so that it operates 9114on the right source file name? You cannot write the name in the command, 9115because the name is different each time the implicit rule is applied. 9116 9117What you do is use a special feature of @code{make}, the @dfn{automatic 9118variables}. These variables have values computed afresh for each rule that 9119is executed, based on the target and prerequisites of the rule. In this 9120example, you would use @samp{$@@} for the object file name and @samp{$<} 9121for the source file name. 9122 9123@cindex automatic variables in prerequisites 9124@cindex prerequisites, and automatic variables 9125It's very important that you recognize the limited scope in which 9126automatic variable values are available: they only have values within 9127the command script. In particular, you cannot use them anywhere 9128within the target list of a rule; they have no value there and will 9129expand to the empty string. Also, they cannot be accessed directly 9130within the prerequisite list of a rule. A common mistake is 9131attempting to use @code{$@@} within the prerequisites list; this will 9132not work. However, there is a special feature of GNU @code{make}, 9133secondary expansion (@pxref{Secondary Expansion}), which will allow 9134automatic variable values to be used in prerequisite lists. 9135 9136Here is a table of automatic variables: 9137 9138@table @code 9139@vindex $@@ 9140@vindex @@ @r{(automatic variable)} 9141@item $@@ 9142The file name of the target of the rule. If the target is an archive 9143member, then @samp{$@@} is the name of the archive file. In a pattern 9144rule that has multiple targets (@pxref{Pattern Intro, ,Introduction to 9145Pattern Rules}), @samp{$@@} is the name of whichever target caused the 9146rule's commands to be run. 9147 9148@vindex $% 9149@vindex % @r{(automatic variable)} 9150@item $% 9151The target member name, when the target is an archive member. 9152@xref{Archives}. For example, if the target is @file{foo.a(bar.o)} then 9153@samp{$%} is @file{bar.o} and @samp{$@@} is @file{foo.a}. @samp{$%} is 9154empty when the target is not an archive member. 9155 9156@vindex $< 9157@vindex < @r{(automatic variable)} 9158@item $< 9159The name of the first prerequisite. If the target got its commands from 9160an implicit rule, this will be the first prerequisite added by the 9161implicit rule (@pxref{Implicit Rules}). 9162 9163@vindex $? 9164@vindex ? @r{(automatic variable)} 9165@item $? 9166The names of all the prerequisites that are newer than the target, with 9167spaces between them. For prerequisites which are archive members, only 9168the member named is used (@pxref{Archives}). 9169@cindex prerequisites, list of changed 9170@cindex list of changed prerequisites 9171 9172@vindex $^ 9173@vindex ^ @r{(automatic variable)} 9174@item $^ 9175The names of all the prerequisites, with spaces between them. For 9176prerequisites which are archive members, only the member named is used 9177(@pxref{Archives}). A target has only one prerequisite on each other file 9178it depends on, no matter how many times each file is listed as a 9179prerequisite. So if you list a prerequisite more than once for a target, 9180the value of @code{$^} contains just one copy of the name. This list 9181does @strong{not} contain any of the order-only prerequisites; for those 9182see the @samp{$|} variable, below. 9183@cindex prerequisites, list of all 9184@cindex list of all prerequisites 9185 9186@vindex $+ 9187@vindex + @r{(automatic variable)} 9188@item $+ 9189This is like @samp{$^}, but prerequisites listed more than once are 9190duplicated in the order they were listed in the makefile. This is 9191primarily useful for use in linking commands where it is meaningful to 9192repeat library file names in a particular order. 9193 9194@vindex $| 9195@vindex | @r{(automatic variable)} 9196@item $| 9197The names of all the order-only prerequisites, with spaces between 9198them. 9199 9200@vindex $* 9201@vindex * @r{(automatic variable)} 9202@item $* 9203The stem with which an implicit rule matches (@pxref{Pattern Match, ,How 9204Patterns Match}). If the target is @file{dir/a.foo.b} and the target 9205pattern is @file{a.%.b} then the stem is @file{dir/foo}. The stem is 9206useful for constructing names of related files.@refill 9207@cindex stem, variable for 9208 9209In a static pattern rule, the stem is part of the file name that matched 9210the @samp{%} in the target pattern. 9211 9212In an explicit rule, there is no stem; so @samp{$*} cannot be determined 9213in that way. Instead, if the target name ends with a recognized suffix 9214(@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}), @samp{$*} is set to 9215the target name minus the suffix. For example, if the target name is 9216@samp{foo.c}, then @samp{$*} is set to @samp{foo}, since @samp{.c} is a 9217suffix. GNU @code{make} does this bizarre thing only for compatibility 9218with other implementations of @code{make}. You should generally avoid 9219using @samp{$*} except in implicit rules or static pattern rules.@refill 9220 9221If the target name in an explicit rule does not end with a recognized 9222suffix, @samp{$*} is set to the empty string for that rule. 9223@end table 9224 9225@samp{$?} is useful even in explicit rules when you wish to operate on only 9226the prerequisites that have changed. For example, suppose that an archive 9227named @file{lib} is supposed to contain copies of several object files. 9228This rule copies just the changed object files into the archive: 9229 9230@example 9231@group 9232lib: foo.o bar.o lose.o win.o 9233 ar r lib $? 9234@end group 9235@end example 9236 9237Of the variables listed above, four have values that are single file 9238names, and three have values that are lists of file names. These seven 9239have variants that get just the file's directory name or just the file 9240name within the directory. The variant variables' names are formed by 9241appending @samp{D} or @samp{F}, respectively. These variants are 9242semi-obsolete in GNU @code{make} since the functions @code{dir} and 9243@code{notdir} can be used to get a similar effect (@pxref{File Name 9244Functions, , Functions for File Names}). Note, however, that the 9245@samp{D} variants all omit the trailing slash which always appears in 9246the output of the @code{dir} function. Here is a table of the variants: 9247 9248@table @samp 9249@vindex $(@@D) 9250@vindex @@D @r{(automatic variable)} 9251@item $(@@D) 9252The directory part of the file name of the target, with the trailing 9253slash removed. If the value of @samp{$@@} is @file{dir/foo.o} then 9254@samp{$(@@D)} is @file{dir}. This value is @file{.} if @samp{$@@} does 9255not contain a slash. 9256 9257@vindex $(@@F) 9258@vindex @@F @r{(automatic variable)} 9259@item $(@@F) 9260The file-within-directory part of the file name of the target. If the 9261value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is 9262@file{foo.o}. @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}. 9263 9264@vindex $(*D) 9265@vindex *D @r{(automatic variable)} 9266@item $(*D) 9267@vindex $(*F) 9268@vindex *F @r{(automatic variable)} 9269@itemx $(*F) 9270The directory part and the file-within-directory 9271part of the stem; @file{dir} and @file{foo} in this example. 9272 9273@vindex $(%D) 9274@vindex %D @r{(automatic variable)} 9275@item $(%D) 9276@vindex $(%F) 9277@vindex %F @r{(automatic variable)} 9278@itemx $(%F) 9279The directory part and the file-within-directory part of the target 9280archive member name. This makes sense only for archive member targets 9281of the form @file{@var{archive}(@var{member})} and is useful only when 9282@var{member} may contain a directory name. (@xref{Archive Members, 9283,Archive Members as Targets}.) 9284 9285@vindex $(<D) 9286@vindex <D @r{(automatic variable)} 9287@item $(<D) 9288@vindex $(<F) 9289@vindex <F @r{(automatic variable)} 9290@itemx $(<F) 9291The directory part and the file-within-directory 9292part of the first prerequisite. 9293 9294@vindex $(^D) 9295@vindex ^D @r{(automatic variable)} 9296@item $(^D) 9297@vindex $(^F) 9298@vindex ^F @r{(automatic variable)} 9299@itemx $(^F) 9300Lists of the directory parts and the file-within-directory 9301parts of all prerequisites. 9302 9303@vindex $(+D) 9304@vindex +D @r{(automatic variable)} 9305@item $(+D) 9306@vindex $(+F) 9307@vindex +F @r{(automatic variable)} 9308@itemx $(+F) 9309Lists of the directory parts and the file-within-directory 9310parts of all prerequisites, including multiple instances of duplicated 9311prerequisites. 9312 9313@vindex $(?D) 9314@vindex ?D @r{(automatic variable)} 9315@item $(?D) 9316@vindex $(?F) 9317@vindex ?F @r{(automatic variable)} 9318@itemx $(?F) 9319Lists of the directory parts and the file-within-directory parts of 9320all prerequisites that are newer than the target. 9321@end table 9322 9323Note that we use a special stylistic convention when we talk about these 9324automatic variables; we write ``the value of @samp{$<}'', rather than 9325@w{``the variable @code{<}''} as we would write for ordinary variables 9326such as @code{objects} and @code{CFLAGS}. We think this convention 9327looks more natural in this special case. Please do not assume it has a 9328deep significance; @samp{$<} refers to the variable named @code{<} just 9329as @samp{$(CFLAGS)} refers to the variable named @code{CFLAGS}. 9330You could just as well use @samp{$(<)} in place of @samp{$<}. 9331 9332@node Pattern Match, Match-Anything Rules, Automatic Variables, Pattern Rules 9333@subsection How Patterns Match 9334 9335@cindex stem 9336A target pattern is composed of a @samp{%} between a prefix and a suffix, 9337either or both of which may be empty. The pattern matches a file name only 9338if the file name starts with the prefix and ends with the suffix, without 9339overlap. The text between the prefix and the suffix is called the 9340@dfn{stem}. Thus, when the pattern @samp{%.o} matches the file name 9341@file{test.o}, the stem is @samp{test}. The pattern rule prerequisites are 9342turned into actual file names by substituting the stem for the character 9343@samp{%}. Thus, if in the same example one of the prerequisites is written 9344as @samp{%.c}, it expands to @samp{test.c}.@refill 9345 9346When the target pattern does not contain a slash (and it usually does 9347not), directory names in the file names are removed from the file name 9348before it is compared with the target prefix and suffix. After the 9349comparison of the file name to the target pattern, the directory 9350names, along with the slash that ends them, are added on to the 9351prerequisite file names generated from the pattern rule's prerequisite 9352patterns and the file name. The directories are ignored only for the 9353purpose of finding an implicit rule to use, not in the application of 9354that rule. Thus, @samp{e%t} matches the file name @file{src/eat}, 9355with @samp{src/a} as the stem. When prerequisites are turned into file 9356names, the directories from the stem are added at the front, while the 9357rest of the stem is substituted for the @samp{%}. The stem 9358@samp{src/a} with a prerequisite pattern @samp{c%r} gives the file name 9359@file{src/car}.@refill 9360 9361@node Match-Anything Rules, Canceling Rules, Pattern Match, Pattern Rules 9362@subsection Match-Anything Pattern Rules 9363 9364@cindex match-anything rule 9365@cindex terminal rule 9366When a pattern rule's target is just @samp{%}, it matches any file name 9367whatever. We call these rules @dfn{match-anything} rules. They are very 9368useful, but it can take a lot of time for @code{make} to think about them, 9369because it must consider every such rule for each file name listed either 9370as a target or as a prerequisite. 9371 9372Suppose the makefile mentions @file{foo.c}. For this target, @code{make} 9373would have to consider making it by linking an object file @file{foo.c.o}, 9374or by C compilation-and-linking in one step from @file{foo.c.c}, or by 9375Pascal compilation-and-linking from @file{foo.c.p}, and many other 9376possibilities. 9377 9378We know these possibilities are ridiculous since @file{foo.c} is a C source 9379file, not an executable. If @code{make} did consider these possibilities, 9380it would ultimately reject them, because files such as @file{foo.c.o} and 9381@file{foo.c.p} would not exist. But these possibilities are so 9382numerous that @code{make} would run very slowly if it had to consider 9383them.@refill 9384 9385To gain speed, we have put various constraints on the way @code{make} 9386considers match-anything rules. There are two different constraints that 9387can be applied, and each time you define a match-anything rule you must 9388choose one or the other for that rule. 9389 9390One choice is to mark the match-anything rule as @dfn{terminal} by defining 9391it with a double colon. When a rule is terminal, it does not apply unless 9392its prerequisites actually exist. Prerequisites that could be made with 9393other implicit rules are not good enough. In other words, no further 9394chaining is allowed beyond a terminal rule. 9395 9396For example, the built-in implicit rules for extracting sources from RCS 9397and SCCS files are terminal; as a result, if the file @file{foo.c,v} does 9398not exist, @code{make} will not even consider trying to make it as an 9399intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}. 9400RCS and SCCS files are generally ultimate source files, which should not be 9401remade from any other files; therefore, @code{make} can save time by not 9402looking for ways to remake them.@refill 9403 9404If you do not mark the match-anything rule as terminal, then it is 9405nonterminal. A nonterminal match-anything rule cannot apply to a file name 9406that indicates a specific type of data. A file name indicates a specific 9407type of data if some non-match-anything implicit rule target matches it. 9408 9409For example, the file name @file{foo.c} matches the target for the pattern 9410rule @samp{%.c : %.y} (the rule to run Yacc). Regardless of whether this 9411rule is actually applicable (which happens only if there is a file 9412@file{foo.y}), the fact that its target matches is enough to prevent 9413consideration of any nonterminal match-anything rules for the file 9414@file{foo.c}. Thus, @code{make} will not even consider trying to make 9415@file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c}, 9416@file{foo.c.p}, etc.@refill 9417 9418The motivation for this constraint is that nonterminal match-anything 9419rules are used for making files containing specific types of data (such as 9420executable files) and a file name with a recognized suffix indicates some 9421other specific type of data (such as a C source file). 9422 9423Special built-in dummy pattern rules are provided solely to recognize 9424certain file names so that nonterminal match-anything rules will not be 9425considered. These dummy rules have no prerequisites and no commands, and 9426they are ignored for all other purposes. For example, the built-in 9427implicit rule 9428 9429@example 9430%.p : 9431@end example 9432 9433@noindent 9434exists to make sure that Pascal source files such as @file{foo.p} match a 9435specific target pattern and thereby prevent time from being wasted looking 9436for @file{foo.p.o} or @file{foo.p.c}. 9437 9438Dummy pattern rules such as the one for @samp{%.p} are made for every 9439suffix listed as valid for use in suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}). 9440 9441@node Canceling Rules, , Match-Anything Rules, Pattern Rules 9442@subsection Canceling Implicit Rules 9443 9444You can override a built-in implicit rule (or one you have defined 9445yourself) by defining a new pattern rule with the same target and 9446prerequisites, but different commands. When the new rule is defined, the 9447built-in one is replaced. The new rule's position in the sequence of 9448implicit rules is determined by where you write the new rule. 9449 9450You can cancel a built-in implicit rule by defining a pattern rule with the 9451same target and prerequisites, but no commands. For example, the following 9452would cancel the rule that runs the assembler: 9453 9454@example 9455%.o : %.s 9456@end example 9457 9458@node Last Resort, Suffix Rules, Pattern Rules, Implicit Rules 9459@section Defining Last-Resort Default Rules 9460@cindex last-resort default rules 9461@cindex default rules, last-resort 9462 9463You can define a last-resort implicit rule by writing a terminal 9464match-anything pattern rule with no prerequisites (@pxref{Match-Anything 9465Rules}). This is just like any other pattern rule; the only thing 9466special about it is that it will match any target. So such a rule's 9467commands are used for all targets and prerequisites that have no commands 9468of their own and for which no other implicit rule applies. 9469 9470For example, when testing a makefile, you might not care if the source 9471files contain real data, only that they exist. Then you might do this: 9472 9473@example 9474%:: 9475 touch $@@ 9476@end example 9477 9478@noindent 9479to cause all the source files needed (as prerequisites) to be created 9480automatically. 9481 9482@findex .DEFAULT 9483You can instead define commands to be used for targets for which there 9484are no rules at all, even ones which don't specify commands. You do 9485this by writing a rule for the target @code{.DEFAULT}. Such a rule's 9486commands are used for all prerequisites which do not appear as targets in 9487any explicit rule, and for which no implicit rule applies. Naturally, 9488there is no @code{.DEFAULT} rule unless you write one. 9489 9490If you use @code{.DEFAULT} with no commands or prerequisites: 9491 9492@example 9493.DEFAULT: 9494@end example 9495 9496@noindent 9497the commands previously stored for @code{.DEFAULT} are cleared. 9498Then @code{make} acts as if you had never defined @code{.DEFAULT} at all. 9499 9500If you do not want a target to get the commands from a match-anything 9501pattern rule or @code{.DEFAULT}, but you also do not want any commands 9502to be run for the target, you can give it empty commands (@pxref{Empty 9503Commands, ,Defining Empty Commands}).@refill 9504 9505You can use a last-resort rule to override part of another makefile. 9506@xref{Overriding Makefiles, , Overriding Part of Another Makefile}. 9507 9508@node Suffix Rules, Implicit Rule Search, Last Resort, Implicit Rules 9509@section Old-Fashioned Suffix Rules 9510@cindex old-fashioned suffix rules 9511@cindex suffix rule 9512 9513@dfn{Suffix rules} are the old-fashioned way of defining implicit rules for 9514@code{make}. Suffix rules are obsolete because pattern rules are more 9515general and clearer. They are supported in GNU @code{make} for 9516compatibility with old makefiles. They come in two kinds: 9517@dfn{double-suffix} and @dfn{single-suffix}.@refill 9518 9519A double-suffix rule is defined by a pair of suffixes: the target suffix 9520and the source suffix. It matches any file whose name ends with the 9521target suffix. The corresponding implicit prerequisite is made by 9522replacing the target suffix with the source suffix in the file name. A 9523two-suffix rule whose target and source suffixes are @samp{.o} and 9524@samp{.c} is equivalent to the pattern rule @samp{%.o : %.c}. 9525 9526A single-suffix rule is defined by a single suffix, which is the source 9527suffix. It matches any file name, and the corresponding implicit 9528prerequisite name is made by appending the source suffix. A single-suffix 9529rule whose source suffix is @samp{.c} is equivalent to the pattern rule 9530@samp{% : %.c}. 9531 9532Suffix rule definitions are recognized by comparing each rule's target 9533against a defined list of known suffixes. When @code{make} sees a rule 9534whose target is a known suffix, this rule is considered a single-suffix 9535rule. When @code{make} sees a rule whose target is two known suffixes 9536concatenated, this rule is taken as a double-suffix rule. 9537 9538For example, @samp{.c} and @samp{.o} are both on the default list of 9539known suffixes. Therefore, if you define a rule whose target is 9540@samp{.c.o}, @code{make} takes it to be a double-suffix rule with source 9541suffix @samp{.c} and target suffix @samp{.o}. Here is the old-fashioned 9542way to define the rule for compiling a C source file:@refill 9543 9544@example 9545.c.o: 9546 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $< 9547@end example 9548 9549Suffix rules cannot have any prerequisites of their own. If they have any, 9550they are treated as normal files with funny names, not as suffix rules. 9551Thus, the rule: 9552 9553@example 9554.c.o: foo.h 9555 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $< 9556@end example 9557 9558@noindent 9559tells how to make the file @file{.c.o} from the prerequisite file 9560@file{foo.h}, and is not at all like the pattern rule: 9561 9562@example 9563%.o: %.c foo.h 9564 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $< 9565@end example 9566 9567@noindent 9568which tells how to make @samp{.o} files from @samp{.c} files, and makes all 9569@samp{.o} files using this pattern rule also depend on @file{foo.h}. 9570 9571Suffix rules with no commands are also meaningless. They do not remove 9572previous rules as do pattern rules with no commands (@pxref{Canceling 9573Rules, , Canceling Implicit Rules}). They simply enter the suffix or pair of suffixes concatenated as 9574a target in the data base.@refill 9575 9576@findex .SUFFIXES 9577The known suffixes are simply the names of the prerequisites of the special 9578target @code{.SUFFIXES}. You can add your own suffixes by writing a rule 9579for @code{.SUFFIXES} that adds more prerequisites, as in: 9580 9581@example 9582.SUFFIXES: .hack .win 9583@end example 9584 9585@noindent 9586which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes. 9587 9588If you wish to eliminate the default known suffixes instead of just adding 9589to them, write a rule for @code{.SUFFIXES} with no prerequisites. By 9590special dispensation, this eliminates all existing prerequisites of 9591@code{.SUFFIXES}. You can then write another rule to add the suffixes you 9592want. For example, 9593 9594@example 9595@group 9596.SUFFIXES: # @r{Delete the default suffixes} 9597.SUFFIXES: .c .o .h # @r{Define our suffix list} 9598@end group 9599@end example 9600 9601The @samp{-r} or @samp{--no-builtin-rules} flag causes the default 9602list of suffixes to be empty. 9603 9604@vindex SUFFIXES 9605The variable @code{SUFFIXES} is defined to the default list of suffixes 9606before @code{make} reads any makefiles. You can change the list of suffixes 9607with a rule for the special target @code{.SUFFIXES}, but that does not alter 9608this variable. 9609 9610@node Implicit Rule Search, , Suffix Rules, Implicit Rules 9611@section Implicit Rule Search Algorithm 9612@cindex implicit rule, search algorithm 9613@cindex search algorithm, implicit rule 9614 9615Here is the procedure @code{make} uses for searching for an implicit rule 9616for a target @var{t}. This procedure is followed for each double-colon 9617rule with no commands, for each target of ordinary rules none of which have 9618commands, and for each prerequisite that is not the target of any rule. It 9619is also followed recursively for prerequisites that come from implicit 9620rules, in the search for a chain of rules. 9621 9622Suffix rules are not mentioned in this algorithm because suffix rules are 9623converted to equivalent pattern rules once the makefiles have been read in. 9624 9625For an archive member target of the form 9626@samp{@var{archive}(@var{member})}, the following algorithm is run 9627twice, first using the entire target name @var{t}, and second using 9628@samp{(@var{member})} as the target @var{t} if the first run found no 9629rule.@refill 9630 9631@enumerate 9632@item 9633Split @var{t} into a directory part, called @var{d}, and the rest, 9634called @var{n}. For example, if @var{t} is @samp{src/foo.o}, then 9635@var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill 9636 9637@item 9638Make a list of all the pattern rules one of whose targets matches 9639@var{t} or @var{n}. If the target pattern contains a slash, it is 9640matched against @var{t}; otherwise, against @var{n}. 9641 9642@item 9643If any rule in that list is @emph{not} a match-anything rule, then 9644remove all nonterminal match-anything rules from the list. 9645 9646@item 9647Remove from the list all rules with no commands. 9648 9649@item 9650For each pattern rule in the list: 9651 9652@enumerate a 9653@item 9654Find the stem @var{s}, which is the nonempty part of @var{t} or @var{n} 9655matched by the @samp{%} in the target pattern.@refill 9656 9657@item 9658Compute the prerequisite names by substituting @var{s} for @samp{%}; if 9659the target pattern does not contain a slash, append @var{d} to 9660the front of each prerequisite name.@refill 9661 9662@item 9663Test whether all the prerequisites exist or ought to exist. (If a 9664file name is mentioned in the makefile as a target or as an explicit 9665prerequisite, then we say it ought to exist.) 9666 9667If all prerequisites exist or ought to exist, or there are no prerequisites, 9668then this rule applies. 9669@end enumerate 9670 9671@item 9672If no pattern rule has been found so far, try harder. 9673For each pattern rule in the list: 9674 9675@enumerate a 9676@item 9677If the rule is terminal, ignore it and go on to the next rule. 9678 9679@item 9680Compute the prerequisite names as before. 9681 9682@item 9683Test whether all the prerequisites exist or ought to exist. 9684 9685@item 9686For each prerequisite that does not exist, follow this algorithm 9687recursively to see if the prerequisite can be made by an implicit 9688rule. 9689 9690@item 9691If all prerequisites exist, ought to exist, or can be 9692made by implicit rules, then this rule applies. 9693@end enumerate 9694 9695@item 9696If no implicit rule applies, the rule for @code{.DEFAULT}, if any, 9697applies. In that case, give @var{t} the same commands that 9698@code{.DEFAULT} has. Otherwise, there are no commands for @var{t}. 9699@end enumerate 9700 9701Once a rule that applies has been found, for each target pattern of the 9702rule other than the one that matched @var{t} or @var{n}, the @samp{%} in 9703the pattern is replaced with @var{s} and the resultant file name is stored 9704until the commands to remake the target file @var{t} are executed. After 9705these commands are executed, each of these stored file names are entered 9706into the data base and marked as having been updated and having the same 9707update status as the file @var{t}. 9708 9709When the commands of a pattern rule are executed for @var{t}, the automatic 9710variables are set corresponding to the target and prerequisites. 9711@xref{Automatic Variables}. 9712 9713@node Archives, Features, Implicit Rules, Top 9714@chapter Using @code{make} to Update Archive Files 9715@cindex archive 9716 9717@dfn{Archive files} are files containing named subfiles called 9718@dfn{members}; they are maintained with the program @code{ar} and their 9719main use is as subroutine libraries for linking. 9720 9721@menu 9722* Archive Members:: Archive members as targets. 9723* Archive Update:: The implicit rule for archive member targets. 9724* Archive Pitfalls:: Dangers to watch out for when using archives. 9725* Archive Suffix Rules:: You can write a special kind of suffix rule 9726 for updating archives. 9727@end menu 9728 9729@node Archive Members, Archive Update, Archives, Archives 9730@section Archive Members as Targets 9731@cindex archive member targets 9732 9733An individual member of an archive file can be used as a target or 9734prerequisite in @code{make}. You specify the member named @var{member} in 9735archive file @var{archive} as follows: 9736 9737@example 9738@var{archive}(@var{member}) 9739@end example 9740 9741@noindent 9742This construct is available only in targets and prerequisites, not in 9743commands! Most programs that you might use in commands do not support this 9744syntax and cannot act directly on archive members. Only @code{ar} and 9745other programs specifically designed to operate on archives can do so. 9746Therefore, valid commands to update an archive member target probably must 9747use @code{ar}. For example, this rule says to create a member 9748@file{hack.o} in archive @file{foolib} by copying the file @file{hack.o}: 9749 9750@example 9751foolib(hack.o) : hack.o 9752 ar cr foolib hack.o 9753@end example 9754 9755In fact, nearly all archive member targets are updated in just this way 9756and there is an implicit rule to do it for you. @strong{Please note:} The 9757@samp{c} flag to @code{ar} is required if the archive file does not 9758already exist. 9759 9760To specify several members in the same archive, you can write all the 9761member names together between the parentheses. For example: 9762 9763@example 9764foolib(hack.o kludge.o) 9765@end example 9766 9767@noindent 9768is equivalent to: 9769 9770@example 9771foolib(hack.o) foolib(kludge.o) 9772@end example 9773 9774@cindex wildcard, in archive member 9775You can also use shell-style wildcards in an archive member reference. 9776@xref{Wildcards, ,Using Wildcard Characters in File Names}. For 9777example, @w{@samp{foolib(*.o)}} expands to all existing members of the 9778@file{foolib} archive whose names end in @samp{.o}; perhaps 9779@samp{@w{foolib(hack.o)} @w{foolib(kludge.o)}}. 9780 9781@node Archive Update, Archive Pitfalls, Archive Members, Archives 9782@section Implicit Rule for Archive Member Targets 9783 9784Recall that a target that looks like @file{@var{a}(@var{m})} stands for the 9785member named @var{m} in the archive file @var{a}. 9786 9787When @code{make} looks for an implicit rule for such a target, as a special 9788feature it considers implicit rules that match @file{(@var{m})}, as well as 9789those that match the actual target @file{@var{a}(@var{m})}. 9790 9791This causes one special rule whose target is @file{(%)} to match. This 9792rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m} 9793into the archive. For example, it will update the archive member target 9794@file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the 9795archive @file{foo.a} as a @emph{member} named @file{bar.o}. 9796 9797When this rule is chained with others, the result is very powerful. 9798Thus, @samp{make "foo.a(bar.o)"} (the quotes are needed to protect the 9799@samp{(} and @samp{)} from being interpreted specially by the shell) in 9800the presence of a file @file{bar.c} is enough to cause the following 9801commands to be run, even without a makefile: 9802 9803@example 9804cc -c bar.c -o bar.o 9805ar r foo.a bar.o 9806rm -f bar.o 9807@end example 9808 9809@noindent 9810Here @code{make} has envisioned the file @file{bar.o} as an intermediate 9811file. @xref{Chained Rules, ,Chains of Implicit Rules}. 9812 9813Implicit rules such as this one are written using the automatic variable 9814@samp{$%}. @xref{Automatic Variables}. 9815 9816An archive member name in an archive cannot contain a directory name, but 9817it may be useful in a makefile to pretend that it does. If you write an 9818archive member target @file{foo.a(dir/file.o)}, @code{make} will perform 9819automatic updating with this command: 9820 9821@example 9822ar r foo.a dir/file.o 9823@end example 9824 9825@noindent 9826which has the effect of copying the file @file{dir/file.o} into a member 9827named @file{file.o}. In connection with such usage, the automatic variables 9828@code{%D} and @code{%F} may be useful. 9829 9830@menu 9831* Archive Symbols:: How to update archive symbol directories. 9832@end menu 9833 9834@node Archive Symbols, , Archive Update, Archive Update 9835@subsection Updating Archive Symbol Directories 9836@cindex @code{__.SYMDEF} 9837@cindex updating archive symbol directories 9838@cindex archive symbol directory updating 9839@cindex symbol directories, updating archive 9840@cindex directories, updating archive symbol 9841 9842An archive file that is used as a library usually contains a special member 9843named @file{__.SYMDEF} that contains a directory of the external symbol 9844names defined by all the other members. After you update any other 9845members, you need to update @file{__.SYMDEF} so that it will summarize the 9846other members properly. This is done by running the @code{ranlib} program: 9847 9848@example 9849ranlib @var{archivefile} 9850@end example 9851 9852Normally you would put this command in the rule for the archive file, 9853and make all the members of the archive file prerequisites of that rule. 9854For example, 9855 9856@example 9857libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{} 9858 ranlib libfoo.a 9859@end example 9860 9861@noindent 9862The effect of this is to update archive members @file{x.o}, @file{y.o}, 9863etc., and then update the symbol directory member @file{__.SYMDEF} by 9864running @code{ranlib}. The rules for updating the members are not shown 9865here; most likely you can omit them and use the implicit rule which copies 9866files into the archive, as described in the preceding section. 9867 9868This is not necessary when using the GNU @code{ar} program, which 9869updates the @file{__.SYMDEF} member automatically. 9870 9871@node Archive Pitfalls, Archive Suffix Rules, Archive Update, Archives 9872@section Dangers When Using Archives 9873@cindex archive, and parallel execution 9874@cindex parallel execution, and archive update 9875@cindex archive, and @code{-j} 9876@cindex @code{-j}, and archive update 9877 9878It is important to be careful when using parallel execution (the 9879@code{-j} switch; @pxref{Parallel, ,Parallel Execution}) and archives. 9880If multiple @code{ar} commands run at the same time on the same archive 9881file, they will not know about each other and can corrupt the file. 9882 9883Possibly a future version of @code{make} will provide a mechanism to 9884circumvent this problem by serializing all commands that operate on the 9885same archive file. But for the time being, you must either write your 9886makefiles to avoid this problem in some other way, or not use @code{-j}. 9887 9888@node Archive Suffix Rules, , Archive Pitfalls, Archives 9889@section Suffix Rules for Archive Files 9890@cindex suffix rule, for archive 9891@cindex archive, suffix rule for 9892@cindex library archive, suffix rule for 9893@cindex @code{.a} (archives) 9894 9895You can write a special kind of suffix rule for dealing with archive 9896files. @xref{Suffix Rules}, for a full explanation of suffix rules. 9897Archive suffix rules are obsolete in GNU @code{make}, because pattern 9898rules for archives are a more general mechanism (@pxref{Archive 9899Update}). But they are retained for compatibility with other 9900@code{make}s. 9901 9902To write a suffix rule for archives, you simply write a suffix rule 9903using the target suffix @samp{.a} (the usual suffix for archive files). 9904For example, here is the old-fashioned suffix rule to update a library 9905archive from C source files: 9906 9907@example 9908@group 9909.c.a: 9910 $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o 9911 $(AR) r $@@ $*.o 9912 $(RM) $*.o 9913@end group 9914@end example 9915 9916@noindent 9917This works just as if you had written the pattern rule: 9918 9919@example 9920@group 9921(%.o): %.c 9922 $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o 9923 $(AR) r $@@ $*.o 9924 $(RM) $*.o 9925@end group 9926@end example 9927 9928In fact, this is just what @code{make} does when it sees a suffix rule 9929with @samp{.a} as the target suffix. Any double-suffix rule 9930@w{@samp{.@var{x}.a}} is converted to a pattern rule with the target 9931pattern @samp{(%.o)} and a prerequisite pattern of @samp{%.@var{x}}. 9932 9933Since you might want to use @samp{.a} as the suffix for some other kind 9934of file, @code{make} also converts archive suffix rules to pattern rules 9935in the normal way (@pxref{Suffix Rules}). Thus a double-suffix rule 9936@w{@samp{.@var{x}.a}} produces two pattern rules: @samp{@w{(%.o):} 9937@w{%.@var{x}}} and @samp{@w{%.a}: @w{%.@var{x}}}.@refill 9938 9939@node Features, Missing, Archives, Top 9940@chapter Features of GNU @code{make} 9941@cindex features of GNU @code{make} 9942@cindex portability 9943@cindex compatibility 9944 9945Here is a summary of the features of GNU @code{make}, for comparison 9946with and credit to other versions of @code{make}. We consider the 9947features of @code{make} in 4.2 BSD systems as a baseline. If you are 9948concerned with writing portable makefiles, you should not use the 9949features of @code{make} listed here, nor the ones in @ref{Missing}. 9950 9951Many features come from the version of @code{make} in System V. 9952 9953@itemize @bullet 9954@item 9955The @code{VPATH} variable and its special meaning. 9956@xref{Directory Search, , Searching Directories for Prerequisites}. 9957This feature exists in System V @code{make}, but is undocumented. 9958It is documented in 4.3 BSD @code{make} (which says it mimics System V's 9959@code{VPATH} feature).@refill 9960 9961@item 9962Included makefiles. @xref{Include, ,Including Other Makefiles}. 9963Allowing multiple files to be included with a single directive is a GNU 9964extension. 9965 9966@item 9967Variables are read from and communicated via the environment. 9968@xref{Environment, ,Variables from the Environment}. 9969 9970@item 9971Options passed through the variable @code{MAKEFLAGS} to recursive 9972invocations of @code{make}. 9973@xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}. 9974 9975@item 9976The automatic variable @code{$%} is set to the member name 9977in an archive reference. @xref{Automatic Variables}. 9978 9979@item 9980The automatic variables @code{$@@}, @code{$*}, @code{$<}, @code{$%}, 9981and @code{$?} have corresponding forms like @code{$(@@F)} and 9982@code{$(@@D)}. We have generalized this to @code{$^} as an obvious 9983extension. @xref{Automatic Variables}.@refill 9984 9985@item 9986Substitution variable references. 9987@xref{Reference, ,Basics of Variable References}. 9988 9989@item 9990The command-line options @samp{-b} and @samp{-m}, accepted and 9991ignored. In System V @code{make}, these options actually do something. 9992 9993@item 9994Execution of recursive commands to run @code{make} via the variable 9995@code{MAKE} even if @samp{-n}, @samp{-q} or @samp{-t} is specified. 9996@xref{Recursion, ,Recursive Use of @code{make}}. 9997 9998@item 9999Support for suffix @samp{.a} in suffix rules. @xref{Archive Suffix 10000Rules}. This feature is obsolete in GNU @code{make}, because the 10001general feature of rule chaining (@pxref{Chained Rules, ,Chains of 10002Implicit Rules}) allows one pattern rule for installing members in an 10003archive (@pxref{Archive Update}) to be sufficient. 10004 10005@item 10006The arrangement of lines and backslash-newline combinations in 10007commands is retained when the commands are printed, so they appear as 10008they do in the makefile, except for the stripping of initial 10009whitespace. 10010@end itemize 10011 10012The following features were inspired by various other versions of 10013@code{make}. In some cases it is unclear exactly which versions inspired 10014which others. 10015 10016@itemize @bullet 10017@item 10018Pattern rules using @samp{%}. 10019This has been implemented in several versions of @code{make}. 10020We're not sure who invented it first, but it's been spread around a bit. 10021@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.@refill 10022 10023@item 10024Rule chaining and implicit intermediate files. 10025This was implemented by Stu Feldman in his version of @code{make} 10026for AT&T Eighth Edition Research Unix, and later by Andrew Hume of 10027AT&T Bell Labs in his @code{mk} program (where he terms it 10028``transitive closure''). We do not really know if 10029we got this from either of them or thought it up ourselves at the 10030same time. @xref{Chained Rules, ,Chains of Implicit Rules}. 10031 10032@item 10033The automatic variable @code{$^} containing a list of all prerequisites 10034of the current target. We did not invent this, but we have no idea who 10035did. @xref{Automatic Variables}. The automatic variable 10036@code{$+} is a simple extension of @code{$^}. 10037 10038@item 10039The ``what if'' flag (@samp{-W} in GNU @code{make}) was (as far as we know) 10040invented by Andrew Hume in @code{mk}. 10041@xref{Instead of Execution, ,Instead of Executing the Commands}. 10042 10043@item 10044The concept of doing several things at once (parallelism) exists in 10045many incarnations of @code{make} and similar programs, though not in the 10046System V or BSD implementations. @xref{Execution, ,Command Execution}. 10047 10048@item 10049Modified variable references using pattern substitution come from 10050SunOS 4. @xref{Reference, ,Basics of Variable References}. 10051This functionality was provided in GNU @code{make} by the 10052@code{patsubst} function before the alternate syntax was implemented 10053for compatibility with SunOS 4. It is not altogether clear who 10054inspired whom, since GNU @code{make} had @code{patsubst} before SunOS 100554 was released.@refill 10056 10057@item 10058The special significance of @samp{+} characters preceding command lines 10059(@pxref{Instead of Execution, ,Instead of Executing the Commands}) is 10060mandated by 10061@cite{IEEE Standard 1003.2-1992} (POSIX.2). 10062 10063@item 10064The @samp{+=} syntax to append to the value of a variable comes from SunOS 100654 @code{make}. @xref{Appending, , Appending More Text to Variables}. 10066 10067@item 10068The syntax @w{@samp{@var{archive}(@var{mem1} @var{mem2}@dots{})}} to list 10069multiple members in a single archive file comes from SunOS 4 @code{make}. 10070@xref{Archive Members}. 10071 10072@item 10073The @code{-include} directive to include makefiles with no error for a 10074nonexistent file comes from SunOS 4 @code{make}. (But note that SunOS 4 10075@code{make} does not allow multiple makefiles to be specified in one 10076@code{-include} directive.) The same feature appears with the name 10077@code{sinclude} in SGI @code{make} and perhaps others. 10078@end itemize 10079 10080The remaining features are inventions new in GNU @code{make}: 10081 10082@itemize @bullet 10083@item 10084Use the @samp{-v} or @samp{--version} option to print version and 10085copyright information. 10086 10087@item 10088Use the @samp{-h} or @samp{--help} option to summarize the options to 10089@code{make}. 10090 10091@item 10092Simply-expanded variables. @xref{Flavors, ,The Two Flavors of Variables}. 10093 10094@item 10095Pass command-line variable assignments automatically through the 10096variable @code{MAKE} to recursive @code{make} invocations. 10097@xref{Recursion, ,Recursive Use of @code{make}}. 10098 10099@item 10100Use the @samp{-C} or @samp{--directory} command option to change 10101directory. @xref{Options Summary, ,Summary of Options}. 10102 10103@item 10104Make verbatim variable definitions with @code{define}. 10105@xref{Defining, ,Defining Variables Verbatim}. 10106 10107@item 10108Declare phony targets with the special target @code{.PHONY}. 10109 10110Andrew Hume of AT&T Bell Labs implemented a similar feature with a 10111different syntax in his @code{mk} program. This seems to be a case of 10112parallel discovery. @xref{Phony Targets, ,Phony Targets}. 10113 10114@item 10115Manipulate text by calling functions. 10116@xref{Functions, ,Functions for Transforming Text}. 10117 10118@item 10119Use the @samp{-o} or @samp{--old-file} 10120option to pretend a file's modification-time is old. 10121@xref{Avoiding Compilation, ,Avoiding Recompilation of Some Files}. 10122 10123@item 10124Conditional execution. 10125 10126This feature has been implemented numerous times in various versions 10127of @code{make}; it seems a natural extension derived from the features 10128of the C preprocessor and similar macro languages and is not a 10129revolutionary concept. @xref{Conditionals, ,Conditional Parts of Makefiles}. 10130 10131@item 10132Specify a search path for included makefiles. 10133@xref{Include, ,Including Other Makefiles}. 10134 10135@item 10136Specify extra makefiles to read with an environment variable. 10137@xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}. 10138 10139@item 10140Strip leading sequences of @samp{./} from file names, so that 10141@file{./@var{file}} and @file{@var{file}} are considered to be the 10142same file.@refill 10143 10144@item 10145Use a special search method for library prerequisites written in the 10146form @samp{-l@var{name}}. 10147@xref{Libraries/Search, ,Directory Search for Link Libraries}. 10148 10149@item 10150Allow suffixes for suffix rules 10151(@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}) to contain any 10152characters. In other versions of @code{make}, they must begin with 10153@samp{.} and not contain any @samp{/} characters. 10154 10155@item 10156Keep track of the current level of @code{make} recursion using the 10157variable @code{MAKELEVEL}. @xref{Recursion, ,Recursive Use of @code{make}}. 10158 10159@item 10160Provide any goals given on the command line in the variable 10161@code{MAKECMDGOALS}. @xref{Goals, ,Arguments to Specify the Goals}. 10162 10163@item 10164Specify static pattern rules. @xref{Static Pattern, ,Static Pattern Rules}. 10165 10166@item 10167Provide selective @code{vpath} search. 10168@xref{Directory Search, ,Searching Directories for Prerequisites}. 10169 10170@item 10171Provide computed variable references. 10172@xref{Reference, ,Basics of Variable References}. 10173 10174@item 10175Update makefiles. @xref{Remaking Makefiles, ,How Makefiles Are Remade}. 10176System V @code{make} has a very, very limited form of this 10177functionality in that it will check out SCCS files for makefiles. 10178 10179@item 10180Various new built-in implicit rules. 10181@xref{Catalogue of Rules, ,Catalogue of Implicit Rules}. 10182 10183@item 10184The built-in variable @samp{MAKE_VERSION} gives the version number of 10185@code{make}. 10186@vindex MAKE_VERSION 10187@end itemize 10188 10189@node Missing, Makefile Conventions, Features, Top 10190@chapter Incompatibilities and Missing Features 10191@cindex incompatibilities 10192@cindex missing features 10193@cindex features, missing 10194 10195The @code{make} programs in various other systems support a few features 10196that are not implemented in GNU @code{make}. The POSIX.2 standard 10197(@cite{IEEE Standard 1003.2-1992}) which specifies @code{make} does not 10198require any of these features.@refill 10199 10200@itemize @bullet 10201@item 10202A target of the form @samp{@var{file}((@var{entry}))} stands for a member 10203of archive file @var{file}. The member is chosen, not by name, but by 10204being an object file which defines the linker symbol @var{entry}.@refill 10205 10206This feature was not put into GNU @code{make} because of the 10207nonmodularity of putting knowledge into @code{make} of the internal 10208format of archive file symbol tables. 10209@xref{Archive Symbols, ,Updating Archive Symbol Directories}. 10210 10211@item 10212Suffixes (used in suffix rules) that end with the character @samp{~} 10213have a special meaning to System V @code{make}; 10214they refer to the SCCS file that corresponds 10215to the file one would get without the @samp{~}. For example, the 10216suffix rule @samp{.c~.o} would make the file @file{@var{n}.o} from 10217the SCCS file @file{s.@var{n}.c}. For complete coverage, a whole 10218series of such suffix rules is required. 10219@xref{Suffix Rules, ,Old-Fashioned Suffix Rules}. 10220 10221In GNU @code{make}, this entire series of cases is handled by two 10222pattern rules for extraction from SCCS, in combination with the 10223general feature of rule chaining. 10224@xref{Chained Rules, ,Chains of Implicit Rules}. 10225 10226@item 10227In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search 10228(@pxref{Directory Search, ,Searching Directories for Prerequisites}) have their names changed inside command 10229strings. We feel it is much cleaner to always use automatic variables 10230and thus make this feature obsolete.@refill 10231 10232@item 10233In some Unix @code{make}s, the automatic variable @code{$*} appearing in 10234the prerequisites of a rule has the amazingly strange ``feature'' of 10235expanding to the full name of the @emph{target of that rule}. We cannot 10236imagine what went on in the minds of Unix @code{make} developers to do 10237this; it is utterly inconsistent with the normal definition of @code{$*}. 10238@vindex * @r{(automatic variable), unsupported bizarre usage} 10239 10240@item 10241In some Unix @code{make}s, implicit rule search 10242(@pxref{Implicit Rules, ,Using Implicit Rules}) is apparently done for 10243@emph{all} targets, not just those without commands. This means you can 10244do:@refill 10245 10246@example 10247@group 10248foo.o: 10249 cc -c foo.c 10250@end group 10251@end example 10252 10253@noindent 10254and Unix @code{make} will intuit that @file{foo.o} depends on 10255@file{foo.c}.@refill 10256 10257We feel that such usage is broken. The prerequisite properties of 10258@code{make} are well-defined (for GNU @code{make}, at least), 10259and doing such a thing simply does not fit the model.@refill 10260 10261@item 10262GNU @code{make} does not include any built-in implicit rules for 10263compiling or preprocessing EFL programs. If we hear of anyone who is 10264using EFL, we will gladly add them. 10265 10266@item 10267It appears that in SVR4 @code{make}, a suffix rule can be specified with 10268no commands, and it is treated as if it had empty commands 10269(@pxref{Empty Commands}). For example: 10270 10271@example 10272.c.a: 10273@end example 10274 10275@noindent 10276will override the built-in @file{.c.a} suffix rule. 10277 10278We feel that it is cleaner for a rule without commands to always simply 10279add to the prerequisite list for the target. The above example can be 10280easily rewritten to get the desired behavior in GNU @code{make}: 10281 10282@example 10283.c.a: ; 10284@end example 10285 10286@item 10287Some versions of @code{make} invoke the shell with the @samp{-e} flag, 10288except under @samp{-k} (@pxref{Testing, ,Testing the Compilation of a 10289Program}). The @samp{-e} flag tells the shell to exit as soon as any 10290program it runs returns a nonzero status. We feel it is cleaner to 10291write each shell command line to stand on its own and not require this 10292special treatment. 10293@end itemize 10294 10295@comment The makefile standards are in a separate file that is also 10296@comment included by standards.texi. 10297@include make-stds.texi 10298 10299@node Quick Reference, Error Messages, Makefile Conventions, Top 10300@appendix Quick Reference 10301 10302This appendix summarizes the directives, text manipulation functions, 10303and special variables which GNU @code{make} understands. 10304@xref{Special Targets}, @ref{Catalogue of Rules, ,Catalogue of Implicit Rules}, 10305and @ref{Options Summary, ,Summary of Options}, 10306for other summaries. 10307 10308Here is a summary of the directives GNU @code{make} recognizes: 10309 10310@table @code 10311@item define @var{variable} 10312@itemx endef 10313 10314Define a multi-line, recursively-expanded variable.@* 10315@xref{Sequences}. 10316 10317@item ifdef @var{variable} 10318@itemx ifndef @var{variable} 10319@itemx ifeq (@var{a},@var{b}) 10320@itemx ifeq "@var{a}" "@var{b}" 10321@itemx ifeq '@var{a}' '@var{b}' 10322@itemx ifneq (@var{a},@var{b}) 10323@itemx ifneq "@var{a}" "@var{b}" 10324@itemx ifneq '@var{a}' '@var{b}' 10325@itemx else 10326@itemx endif 10327 10328Conditionally evaluate part of the makefile.@* 10329@xref{Conditionals}. 10330 10331@item include @var{file} 10332@itemx -include @var{file} 10333@itemx sinclude @var{file} 10334 10335Include another makefile.@* 10336@xref{Include, ,Including Other Makefiles}. 10337 10338@item override @var{variable} = @var{value} 10339@itemx override @var{variable} := @var{value} 10340@itemx override @var{variable} += @var{value} 10341@itemx override @var{variable} ?= @var{value} 10342@itemx override define @var{variable} 10343@itemx endef 10344 10345Define a variable, overriding any previous definition, even one from 10346the command line.@* 10347@xref{Override Directive, ,The @code{override} Directive}. 10348 10349@item export 10350 10351Tell @code{make} to export all variables to child processes by default.@* 10352@xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}. 10353 10354@item export @var{variable} 10355@itemx export @var{variable} = @var{value} 10356@itemx export @var{variable} := @var{value} 10357@itemx export @var{variable} += @var{value} 10358@itemx export @var{variable} ?= @var{value} 10359@itemx unexport @var{variable} 10360Tell @code{make} whether or not to export a particular variable to child 10361processes.@* 10362@xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}. 10363 10364@item vpath @var{pattern} @var{path} 10365Specify a search path for files matching a @samp{%} pattern.@* 10366@xref{Selective Search, , The @code{vpath} Directive}. 10367 10368@item vpath @var{pattern} 10369Remove all search paths previously specified for @var{pattern}. 10370 10371@item vpath 10372Remove all search paths previously specified in any @code{vpath} 10373directive. 10374@end table 10375 10376Here is a summary of the built-in functions (@pxref{Functions}): 10377 10378@table @code 10379@item $(subst @var{from},@var{to},@var{text}) 10380Replace @var{from} with @var{to} in @var{text}.@* 10381@xref{Text Functions, , Functions for String Substitution and Analysis}. 10382 10383@item $(patsubst @var{pattern},@var{replacement},@var{text}) 10384Replace words matching @var{pattern} with @var{replacement} in @var{text}.@* 10385@xref{Text Functions, , Functions for String Substitution and Analysis}. 10386 10387@item $(strip @var{string}) 10388Remove excess whitespace characters from @var{string}.@* 10389@xref{Text Functions, , Functions for String Substitution and Analysis}. 10390 10391@item $(findstring @var{find},@var{text}) 10392Locate @var{find} in @var{text}.@* 10393@xref{Text Functions, , Functions for String Substitution and Analysis}. 10394 10395@item $(filter @var{pattern}@dots{},@var{text}) 10396Select words in @var{text} that match one of the @var{pattern} words.@* 10397@xref{Text Functions, , Functions for String Substitution and Analysis}. 10398 10399@item $(filter-out @var{pattern}@dots{},@var{text}) 10400Select words in @var{text} that @emph{do not} match any of the @var{pattern} words.@* 10401@xref{Text Functions, , Functions for String Substitution and Analysis}. 10402 10403@item $(sort @var{list}) 10404Sort the words in @var{list} lexicographically, removing duplicates.@* 10405@xref{Text Functions, , Functions for String Substitution and Analysis}. 10406 10407@item $(word @var{n},@var{text}) 10408Extract the @var{n}th word (one-origin) of @var{text}.@* 10409@xref{Text Functions, , Functions for String Substitution and Analysis}. 10410 10411@item $(words @var{text}) 10412Count the number of words in @var{text}.@* 10413@xref{Text Functions, , Functions for String Substitution and Analysis}. 10414 10415@item $(wordlist @var{s},@var{e},@var{text}) 10416Returns the list of words in @var{text} from @var{s} to @var{e}.@* 10417@xref{Text Functions, , Functions for String Substitution and Analysis}. 10418 10419@item $(firstword @var{names}@dots{}) 10420Extract the first word of @var{names}.@* 10421@xref{Text Functions, , Functions for String Substitution and Analysis}. 10422 10423@item $(lastword @var{names}@dots{}) 10424Extract the last word of @var{names}.@* 10425@xref{Text Functions, , Functions for String Substitution and Analysis}. 10426 10427@item $(dir @var{names}@dots{}) 10428Extract the directory part of each file name.@* 10429@xref{File Name Functions, ,Functions for File Names}. 10430 10431@item $(notdir @var{names}@dots{}) 10432Extract the non-directory part of each file name.@* 10433@xref{File Name Functions, ,Functions for File Names}. 10434 10435@item $(suffix @var{names}@dots{}) 10436Extract the suffix (the last @samp{.} and following characters) of each file name.@* 10437@xref{File Name Functions, ,Functions for File Names}. 10438 10439@item $(basename @var{names}@dots{}) 10440Extract the base name (name without suffix) of each file name.@* 10441@xref{File Name Functions, ,Functions for File Names}. 10442 10443@item $(addsuffix @var{suffix},@var{names}@dots{}) 10444Append @var{suffix} to each word in @var{names}.@* 10445@xref{File Name Functions, ,Functions for File Names}. 10446 10447@item $(addprefix @var{prefix},@var{names}@dots{}) 10448Prepend @var{prefix} to each word in @var{names}.@* 10449@xref{File Name Functions, ,Functions for File Names}. 10450 10451@item $(join @var{list1},@var{list2}) 10452Join two parallel lists of words.@* 10453@xref{File Name Functions, ,Functions for File Names}. 10454 10455@item $(wildcard @var{pattern}@dots{}) 10456Find file names matching a shell file name pattern (@emph{not} a 10457@samp{%} pattern).@* 10458@xref{Wildcard Function, ,The Function @code{wildcard}}. 10459 10460@item $(realpath @var{names}@dots{}) 10461For each file name in @var{names}, expand to an absolute name that 10462does not contain any @code{.}, @code{..}, nor symlinks.@* 10463@xref{File Name Functions, ,Functions for File Names}. 10464 10465@item $(abspath @var{names}@dots{}) 10466For each file name in @var{names}, expand to an absolute name that 10467does not contain any @code{.} or @code{..} components, but preserves 10468symlinks.@* 10469@xref{File Name Functions, ,Functions for File Names}. 10470 10471@item $(error @var{text}@dots{}) 10472 10473When this function is evaluated, @code{make} generates a fatal error 10474with the message @var{text}.@* 10475@xref{Make Control Functions, ,Functions That Control Make}. 10476 10477@item $(warning @var{text}@dots{}) 10478 10479When this function is evaluated, @code{make} generates a warning with 10480the message @var{text}.@* 10481@xref{Make Control Functions, ,Functions That Control Make}. 10482 10483@item $(shell @var{command}) 10484 10485Execute a shell command and return its output.@* 10486@xref{Shell Function, , The @code{shell} Function}. 10487 10488@item $(origin @var{variable}) 10489 10490Return a string describing how the @code{make} variable @var{variable} was 10491defined.@* 10492@xref{Origin Function, , The @code{origin} Function}. 10493 10494@item $(flavor @var{variable}) 10495 10496Return a string describing the flavor of the @code{make} variable 10497@var{variable}.@* 10498@xref{Flavor Function, , The @code{flavor} Function}. 10499 10500@item $(foreach @var{var},@var{words},@var{text}) 10501 10502Evaluate @var{text} with @var{var} bound to each word in @var{words}, 10503and concatenate the results.@* 10504@xref{Foreach Function, ,The @code{foreach} Function}. 10505 10506@item $(call @var{var},@var{param},@dots{}) 10507 10508Evaluate the variable @var{var} replacing any references to @code{$(1)}, 10509@code{$(2)} with the first, second, etc.@: @var{param} values.@* 10510@xref{Call Function, ,The @code{call} Function}. 10511 10512@item $(eval @var{text}) 10513 10514Evaluate @var{text} then read the results as makefile commands. 10515Expands to the empty string.@* 10516@xref{Eval Function, ,The @code{eval} Function}. 10517 10518@item $(value @var{var}) 10519 10520Evaluates to the contents of the variable @var{var}, with no expansion 10521performed on it.@* 10522@xref{Value Function, ,The @code{value} Function}. 10523@end table 10524 10525Here is a summary of the automatic variables. 10526@xref{Automatic Variables}, 10527for full information. 10528 10529@table @code 10530@item $@@ 10531The file name of the target. 10532 10533@item $% 10534The target member name, when the target is an archive member. 10535 10536@item $< 10537The name of the first prerequisite. 10538 10539@item $? 10540The names of all the prerequisites that are 10541newer than the target, with spaces between them. 10542For prerequisites which are archive members, only 10543the member named is used (@pxref{Archives}). 10544 10545@item $^ 10546@itemx $+ 10547The names of all the prerequisites, with spaces between them. For 10548prerequisites which are archive members, only the member named is used 10549(@pxref{Archives}). The value of @code{$^} omits duplicate 10550prerequisites, while @code{$+} retains them and preserves their order. 10551 10552@item $* 10553The stem with which an implicit rule matches 10554(@pxref{Pattern Match, ,How Patterns Match}). 10555 10556@item $(@@D) 10557@itemx $(@@F) 10558The directory part and the file-within-directory part of @code{$@@}. 10559 10560@item $(*D) 10561@itemx $(*F) 10562The directory part and the file-within-directory part of @code{$*}. 10563 10564@item $(%D) 10565@itemx $(%F) 10566The directory part and the file-within-directory part of @code{$%}. 10567 10568@item $(<D) 10569@itemx $(<F) 10570The directory part and the file-within-directory part of @code{$<}. 10571 10572@item $(^D) 10573@itemx $(^F) 10574The directory part and the file-within-directory part of @code{$^}. 10575 10576@item $(+D) 10577@itemx $(+F) 10578The directory part and the file-within-directory part of @code{$+}. 10579 10580@item $(?D) 10581@itemx $(?F) 10582The directory part and the file-within-directory part of @code{$?}. 10583@end table 10584 10585These variables are used specially by GNU @code{make}: 10586 10587@table @code 10588@item MAKEFILES 10589 10590Makefiles to be read on every invocation of @code{make}.@* 10591@xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}. 10592 10593@item VPATH 10594 10595Directory search path for files not found in the current directory.@* 10596@xref{General Search, , @code{VPATH} Search Path for All Prerequisites}. 10597 10598@item SHELL 10599 10600The name of the system default command interpreter, usually @file{/bin/sh}. 10601You can set @code{SHELL} in the makefile to change the shell used to run 10602commands. @xref{Execution, ,Command Execution}. The @code{SHELL} 10603variable is handled specially when importing from and exporting to the 10604environment. @xref{Choosing the Shell}. 10605 10606@item MAKESHELL 10607 10608On MS-DOS only, the name of the command interpreter that is to be used 10609by @code{make}. This value takes precedence over the value of 10610@code{SHELL}. @xref{Execution, ,MAKESHELL variable}. 10611 10612@item MAKE 10613 10614The name with which @code{make} was invoked. 10615Using this variable in commands has special meaning. 10616@xref{MAKE Variable, ,How the @code{MAKE} Variable Works}. 10617 10618@item MAKELEVEL 10619 10620The number of levels of recursion (sub-@code{make}s).@* 10621@xref{Variables/Recursion}. 10622 10623@item MAKEFLAGS 10624 10625The flags given to @code{make}. You can set this in the environment or 10626a makefile to set flags.@* 10627@xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}. 10628 10629It is @emph{never} appropriate to use @code{MAKEFLAGS} directly on a 10630command line: its contents may not be quoted correctly for use in the 10631shell. Always allow recursive @code{make}'s to obtain these values 10632through the environment from its parent. 10633 10634@item MAKECMDGOALS 10635 10636The targets given to @code{make} on the command line. Setting this 10637variable has no effect on the operation of @code{make}.@* 10638@xref{Goals, ,Arguments to Specify the Goals}. 10639 10640@item CURDIR 10641 10642Set to the pathname of the current working directory (after all 10643@code{-C} options are processed, if any). Setting this variable has no 10644effect on the operation of @code{make}.@* 10645@xref{Recursion, ,Recursive Use of @code{make}}. 10646 10647@item SUFFIXES 10648 10649The default list of suffixes before @code{make} reads any makefiles. 10650 10651@item .LIBPATTERNS 10652Defines the naming of the libraries @code{make} searches for, and their 10653order.@* 10654@xref{Libraries/Search, ,Directory Search for Link Libraries}. 10655@end table 10656 10657@node Error Messages, Complex Makefile, Quick Reference, Top 10658@comment node-name, next, previous, up 10659@appendix Errors Generated by Make 10660 10661Here is a list of the more common errors you might see generated by 10662@code{make}, and some information about what they mean and how to fix 10663them. 10664 10665Sometimes @code{make} errors are not fatal, especially in the presence 10666of a @code{-} prefix on a command script line, or the @code{-k} command 10667line option. Errors that are fatal are prefixed with the string 10668@code{***}. 10669 10670Error messages are all either prefixed with the name of the program 10671(usually @samp{make}), or, if the error is found in a makefile, the name 10672of the file and linenumber containing the problem. 10673 10674In the table below, these common prefixes are left off. 10675 10676@table @samp 10677 10678@item [@var{foo}] Error @var{NN} 10679@itemx [@var{foo}] @var{signal description} 10680These errors are not really @code{make} errors at all. They mean that a 10681program that @code{make} invoked as part of a command script returned a 10682non-0 error code (@samp{Error @var{NN}}), which @code{make} interprets 10683as failure, or it exited in some other abnormal fashion (with a 10684signal of some type). @xref{Errors, ,Errors in Commands}. 10685 10686If no @code{***} is attached to the message, then the subprocess failed 10687but the rule in the makefile was prefixed with the @code{-} special 10688character, so @code{make} ignored the error. 10689 10690@item missing separator. Stop. 10691@itemx missing separator (did you mean TAB instead of 8 spaces?). Stop. 10692This means that @code{make} could not understand much of anything about 10693the command line it just read. GNU @code{make} looks for various kinds 10694of separators (@code{:}, @code{=}, TAB characters, etc.) to help it 10695decide what kind of commandline it's seeing. This means it couldn't 10696find a valid one. 10697 10698One of the most common reasons for this message is that you (or perhaps 10699your oh-so-helpful editor, as is the case with many MS-Windows editors) 10700have attempted to indent your command scripts with spaces instead of a 10701TAB character. In this case, @code{make} will use the second form of 10702the error above. Remember that every line in the command script must 10703begin with a TAB character. Eight spaces do not count. @xref{Rule 10704Syntax}. 10705 10706@item commands commence before first target. Stop. 10707@itemx missing rule before commands. Stop. 10708This means the first thing in the makefile seems to be part of a command 10709script: it begins with a TAB character and doesn't appear to be a legal 10710@code{make} command (such as a variable assignment). Command scripts 10711must always be associated with a target. 10712 10713The second form is generated if the line has a semicolon as the first 10714non-whitespace character; @code{make} interprets this to mean you left 10715out the "target: prerequisite" section of a rule. @xref{Rule Syntax}. 10716 10717@item No rule to make target `@var{xxx}'. 10718@itemx No rule to make target `@var{xxx}', needed by `@var{yyy}'. 10719This means that @code{make} decided it needed to build a target, but 10720then couldn't find any instructions in the makefile on how to do that, 10721either explicit or implicit (including in the default rules database). 10722 10723If you want that file to be built, you will need to add a rule to your 10724makefile describing how that target can be built. Other possible 10725sources of this problem are typos in the makefile (if that filename is 10726wrong) or a corrupted source tree (if that file is not supposed to be 10727built, but rather only a prerequisite). 10728 10729@item No targets specified and no makefile found. Stop. 10730@itemx No targets. Stop. 10731The former means that you didn't provide any targets to be built on the 10732command line, and @code{make} couldn't find any makefiles to read in. 10733The latter means that some makefile was found, but it didn't contain any 10734default goal and none was given on the command line. GNU @code{make} 10735has nothing to do in these situations. 10736@xref{Makefile Arguments, ,Arguments to Specify the Makefile}.@refill 10737 10738@item Makefile `@var{xxx}' was not found. 10739@itemx Included makefile `@var{xxx}' was not found. 10740A makefile specified on the command line (first form) or included 10741(second form) was not found. 10742 10743@item warning: overriding commands for target `@var{xxx}' 10744@itemx warning: ignoring old commands for target `@var{xxx}' 10745GNU @code{make} allows commands to be specified only once per target 10746(except for double-colon rules). If you give commands for a target 10747which already has been defined to have commands, this warning is issued 10748and the second set of commands will overwrite the first set. 10749@xref{Multiple Rules, ,Multiple Rules for One Target}. 10750 10751@item Circular @var{xxx} <- @var{yyy} dependency dropped. 10752This means that @code{make} detected a loop in the dependency graph: 10753after tracing the prerequisite @var{yyy} of target @var{xxx}, and its 10754prerequisites, etc., one of them depended on @var{xxx} again. 10755 10756@item Recursive variable `@var{xxx}' references itself (eventually). Stop. 10757This means you've defined a normal (recursive) @code{make} variable 10758@var{xxx} that, when it's expanded, will refer to itself (@var{xxx}). 10759This is not allowed; either use simply-expanded variables (@code{:=}) or 10760use the append operator (@code{+=}). @xref{Using Variables, ,How to Use 10761Variables}. 10762 10763@item Unterminated variable reference. Stop. 10764This means you forgot to provide the proper closing parenthesis 10765or brace in your variable or function reference. 10766 10767@item insufficient arguments to function `@var{xxx}'. Stop. 10768This means you haven't provided the requisite number of arguments for 10769this function. See the documentation of the function for a description 10770of its arguments. @xref{Functions, ,Functions for Transforming Text}. 10771 10772@item missing target pattern. Stop. 10773@itemx multiple target patterns. Stop. 10774@itemx target pattern contains no `%'. Stop. 10775@itemx mixed implicit and static pattern rules. Stop. 10776These are generated for malformed static pattern rules. The first means 10777there's no pattern in the target section of the rule; the second means 10778there are multiple patterns in the target section; the third means 10779the target doesn't contain a pattern character (@code{%}); and the 10780fourth means that all three parts of the static pattern rule contain 10781pattern characters (@code{%})--only the first two parts should. 10782@xref{Static Usage, ,Syntax of Static Pattern Rules}. 10783 10784@item warning: -jN forced in submake: disabling jobserver mode. 10785This warning and the next are generated if @code{make} detects error 10786conditions related to parallel processing on systems where 10787sub-@code{make}s can communicate (@pxref{Options/Recursion, 10788,Communicating Options to a Sub-@code{make}}). This warning is 10789generated if a recursive invocation of a @code{make} process is forced 10790to have @samp{-j@var{N}} in its argument list (where @var{N} is greater 10791than one). This could happen, for example, if you set the @code{MAKE} 10792environment variable to @samp{make -j2}. In this case, the 10793sub-@code{make} doesn't communicate with other @code{make} processes and 10794will simply pretend it has two jobs of its own. 10795 10796@item warning: jobserver unavailable: using -j1. Add `+' to parent make rule. 10797In order for @code{make} processes to communicate, the parent will pass 10798information to the child. Since this could result in problems if the 10799child process isn't actually a @code{make}, the parent will only do this 10800if it thinks the child is a @code{make}. The parent uses the normal 10801algorithms to determine this (@pxref{MAKE Variable, ,How the @code{MAKE} 10802Variable Works}). If the makefile is constructed such that the parent 10803doesn't know the child is a @code{make} process, then the child will 10804receive only part of the information necessary. In this case, the child 10805will generate this warning message and proceed with its build in a 10806sequential manner. 10807 10808@end table 10809 10810@node Complex Makefile, GNU Free Documentation License, Error Messages, Top 10811@appendix Complex Makefile Example 10812 10813Here is the makefile for the GNU @code{tar} program. This is a 10814moderately complex makefile. 10815 10816Because it is the first target, the default goal is @samp{all}. An 10817interesting feature of this makefile is that @file{testpad.h} is a 10818source file automatically created by the @code{testpad} program, 10819itself compiled from @file{testpad.c}. 10820 10821If you type @samp{make} or @samp{make all}, then @code{make} creates 10822the @file{tar} executable, the @file{rmt} daemon that provides 10823remote tape access, and the @file{tar.info} Info file. 10824 10825If you type @samp{make install}, then @code{make} not only creates 10826@file{tar}, @file{rmt}, and @file{tar.info}, but also installs 10827them. 10828 10829If you type @samp{make clean}, then @code{make} removes the @samp{.o} 10830files, and the @file{tar}, @file{rmt}, @file{testpad}, 10831@file{testpad.h}, and @file{core} files. 10832 10833If you type @samp{make distclean}, then @code{make} not only removes 10834the same files as does @samp{make clean} but also the 10835@file{TAGS}, @file{Makefile}, and @file{config.status} files. 10836(Although it is not evident, this makefile (and 10837@file{config.status}) is generated by the user with the 10838@code{configure} program, which is provided in the @code{tar} 10839distribution, but is not shown here.) 10840 10841If you type @samp{make realclean}, then @code{make} removes the same 10842files as does @samp{make distclean} and also removes the Info files 10843generated from @file{tar.texinfo}. 10844 10845In addition, there are targets @code{shar} and @code{dist} that create 10846distribution kits. 10847 10848@example 10849@group 10850# Generated automatically from Makefile.in by configure. 10851# Un*x Makefile for GNU tar program. 10852# Copyright (C) 1991 Free Software Foundation, Inc. 10853@end group 10854 10855@group 10856# This program is free software; you can redistribute 10857# it and/or modify it under the terms of the GNU 10858# General Public License @dots{} 10859@dots{} 10860@dots{} 10861@end group 10862 10863SHELL = /bin/sh 10864 10865#### Start of system configuration section. #### 10866 10867srcdir = . 10868 10869@group 10870# If you use gcc, you should either run the 10871# fixincludes script that comes with it or else use 10872# gcc with the -traditional option. Otherwise ioctl 10873# calls will be compiled incorrectly on some systems. 10874CC = gcc -O 10875YACC = bison -y 10876INSTALL = /usr/local/bin/install -c 10877INSTALLDATA = /usr/local/bin/install -c -m 644 10878@end group 10879 10880# Things you might add to DEFS: 10881# -DSTDC_HEADERS If you have ANSI C headers and 10882# libraries. 10883# -DPOSIX If you have POSIX.1 headers and 10884# libraries. 10885# -DBSD42 If you have sys/dir.h (unless 10886# you use -DPOSIX), sys/file.h, 10887# and st_blocks in `struct stat'. 10888# -DUSG If you have System V/ANSI C 10889# string and memory functions 10890# and headers, sys/sysmacros.h, 10891# fcntl.h, getcwd, no valloc, 10892# and ndir.h (unless 10893# you use -DDIRENT). 10894# -DNO_MEMORY_H If USG or STDC_HEADERS but do not 10895# include memory.h. 10896# -DDIRENT If USG and you have dirent.h 10897# instead of ndir.h. 10898# -DSIGTYPE=int If your signal handlers 10899# return int, not void. 10900# -DNO_MTIO If you lack sys/mtio.h 10901# (magtape ioctls). 10902# -DNO_REMOTE If you do not have a remote shell 10903# or rexec. 10904# -DUSE_REXEC To use rexec for remote tape 10905# operations instead of 10906# forking rsh or remsh. 10907# -DVPRINTF_MISSING If you lack vprintf function 10908# (but have _doprnt). 10909# -DDOPRNT_MISSING If you lack _doprnt function. 10910# Also need to define 10911# -DVPRINTF_MISSING. 10912# -DFTIME_MISSING If you lack ftime system call. 10913# -DSTRSTR_MISSING If you lack strstr function. 10914# -DVALLOC_MISSING If you lack valloc function. 10915# -DMKDIR_MISSING If you lack mkdir and 10916# rmdir system calls. 10917# -DRENAME_MISSING If you lack rename system call. 10918# -DFTRUNCATE_MISSING If you lack ftruncate 10919# system call. 10920# -DV7 On Version 7 Unix (not 10921# tested in a long time). 10922# -DEMUL_OPEN3 If you lack a 3-argument version 10923# of open, and want to emulate it 10924# with system calls you do have. 10925# -DNO_OPEN3 If you lack the 3-argument open 10926# and want to disable the tar -k 10927# option instead of emulating open. 10928# -DXENIX If you have sys/inode.h 10929# and need it 94 to be included. 10930 10931DEFS = -DSIGTYPE=int -DDIRENT -DSTRSTR_MISSING \ 10932 -DVPRINTF_MISSING -DBSD42 10933# Set this to rtapelib.o unless you defined NO_REMOTE, 10934# in which case make it empty. 10935RTAPELIB = rtapelib.o 10936LIBS = 10937DEF_AR_FILE = /dev/rmt8 10938DEFBLOCKING = 20 10939 10940@group 10941CDEBUG = -g 10942CFLAGS = $(CDEBUG) -I. -I$(srcdir) $(DEFS) \ 10943 -DDEF_AR_FILE=\"$(DEF_AR_FILE)\" \ 10944 -DDEFBLOCKING=$(DEFBLOCKING) 10945LDFLAGS = -g 10946@end group 10947 10948@group 10949prefix = /usr/local 10950# Prefix for each installed program, 10951# normally empty or `g'. 10952binprefix = 10953 10954# The directory to install tar in. 10955bindir = $(prefix)/bin 10956 10957# The directory to install the info files in. 10958infodir = $(prefix)/info 10959@end group 10960 10961#### End of system configuration section. #### 10962 10963SRC1 = tar.c create.c extract.c buffer.c \ 10964 getoldopt.c update.c gnu.c mangle.c 10965SRC2 = version.c list.c names.c diffarch.c \ 10966 port.c wildmat.c getopt.c 10967SRC3 = getopt1.c regex.c getdate.y 10968SRCS = $(SRC1) $(SRC2) $(SRC3) 10969OBJ1 = tar.o create.o extract.o buffer.o \ 10970 getoldopt.o update.o gnu.o mangle.o 10971OBJ2 = version.o list.o names.o diffarch.o \ 10972 port.o wildmat.o getopt.o 10973OBJ3 = getopt1.o regex.o getdate.o $(RTAPELIB) 10974OBJS = $(OBJ1) $(OBJ2) $(OBJ3) 10975@group 10976AUX = README COPYING ChangeLog Makefile.in \ 10977 makefile.pc configure configure.in \ 10978 tar.texinfo tar.info* texinfo.tex \ 10979 tar.h port.h open3.h getopt.h regex.h \ 10980 rmt.h rmt.c rtapelib.c alloca.c \ 10981 msd_dir.h msd_dir.c tcexparg.c \ 10982 level-0 level-1 backup-specs testpad.c 10983@end group 10984 10985.PHONY: all 10986all: tar rmt tar.info 10987 10988@group 10989.PHONY: tar 10990tar: $(OBJS) 10991 $(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS) 10992@end group 10993 10994@group 10995rmt: rmt.c 10996 $(CC) $(CFLAGS) $(LDFLAGS) -o $@@ rmt.c 10997@end group 10998 10999@group 11000tar.info: tar.texinfo 11001 makeinfo tar.texinfo 11002@end group 11003 11004@group 11005.PHONY: install 11006install: all 11007 $(INSTALL) tar $(bindir)/$(binprefix)tar 11008 -test ! -f rmt || $(INSTALL) rmt /etc/rmt 11009 $(INSTALLDATA) $(srcdir)/tar.info* $(infodir) 11010@end group 11011 11012@group 11013$(OBJS): tar.h port.h testpad.h 11014regex.o buffer.o tar.o: regex.h 11015# getdate.y has 8 shift/reduce conflicts. 11016@end group 11017 11018@group 11019testpad.h: testpad 11020 ./testpad 11021@end group 11022 11023@group 11024testpad: testpad.o 11025 $(CC) -o $@@ testpad.o 11026@end group 11027 11028@group 11029TAGS: $(SRCS) 11030 etags $(SRCS) 11031@end group 11032 11033@group 11034.PHONY: clean 11035clean: 11036 rm -f *.o tar rmt testpad testpad.h core 11037@end group 11038 11039@group 11040.PHONY: distclean 11041distclean: clean 11042 rm -f TAGS Makefile config.status 11043@end group 11044 11045@group 11046.PHONY: realclean 11047realclean: distclean 11048 rm -f tar.info* 11049@end group 11050 11051@group 11052.PHONY: shar 11053shar: $(SRCS) $(AUX) 11054 shar $(SRCS) $(AUX) | compress \ 11055 > tar-`sed -e '/version_string/!d' \ 11056 -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \ 11057 -e q 11058 version.c`.shar.Z 11059@end group 11060 11061@group 11062.PHONY: dist 11063dist: $(SRCS) $(AUX) 11064 echo tar-`sed \ 11065 -e '/version_string/!d' \ 11066 -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \ 11067 -e q 11068 version.c` > .fname 11069 -rm -rf `cat .fname` 11070 mkdir `cat .fname` 11071 ln $(SRCS) $(AUX) `cat .fname` 11072 tar chZf `cat .fname`.tar.Z `cat .fname` 11073 -rm -rf `cat .fname` .fname 11074@end group 11075 11076@group 11077tar.zoo: $(SRCS) $(AUX) 11078 -rm -rf tmp.dir 11079 -mkdir tmp.dir 11080 -rm tar.zoo 11081 for X in $(SRCS) $(AUX) ; do \ 11082 echo $$X ; \ 11083 sed 's/$$/^M/' $$X \ 11084 > tmp.dir/$$X ; done 11085 cd tmp.dir ; zoo aM ../tar.zoo * 11086 -rm -rf tmp.dir 11087@end group 11088@end example 11089 11090@raisesections 11091@include fdl.texi 11092@lowersections 11093 11094@node Concept Index, Name Index, GNU Free Documentation License, Top 11095@unnumbered Index of Concepts 11096 11097@printindex cp 11098 11099@node Name Index, , Concept Index, Top 11100@unnumbered Index of Functions, Variables, & Directives 11101 11102@printindex fn 11103 11104@bye 11105