| \input texinfo @c -*- Texinfo -*- |
| @c %**start of header |
| @setfilename make.info |
| |
| @include version.texi |
| @set EDITION 0.73 |
| |
| @settitle GNU @code{make} |
| @setchapternewpage odd |
| @c Combine the variable and function indices: |
| @syncodeindex vr fn |
| @c Combine the program and concept indices: |
| @syncodeindex pg cp |
| @c FSF publishers: format makebook.texi instead of using this file directly. |
| @c ISBN confirmed by Jasimin Huang <jasimin@fsf.org> on 25 Mar 2009 |
| @set ISBN 1-882114-83-3 |
| @c %**end of header |
| |
| @copying |
| This file documents the GNU @code{make} utility, which determines |
| automatically which pieces of a large program need to be recompiled, |
| and issues the commands to recompile them. |
| |
| This is Edition @value{EDITION}, last updated @value{UPDATED}, |
| of @cite{The GNU Make Manual}, for GNU @code{make} version @value{VERSION}. |
| |
| Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, |
| 1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, |
| 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016 Free Software |
| Foundation, Inc. |
| |
| @quotation |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with no |
| Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' |
| and with the Back-Cover Texts as in (a) below. A copy of the |
| license is included in the section entitled ``GNU Free Documentation |
| License.'' |
| |
| (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
| modify this GNU manual. Buying copies from the FSF supports it in |
| developing GNU and promoting software freedom.'' |
| @end quotation |
| @end copying |
| |
| @c finalout |
| |
| @c ISPELL CHECK: done, 10 June 1993 --roland |
| @c ISPELL CHECK: done, 2000-06-25 --Martin Buchholz |
| |
| |
| @dircategory Software development |
| @direntry |
| * Make: (make). Remake files automatically. |
| @end direntry |
| |
| @iftex |
| @shorttitlepage GNU Make |
| @end iftex |
| @titlepage |
| @title GNU Make |
| @subtitle A Program for Directing Recompilation |
| @subtitle GNU @code{make} Version @value{VERSION} |
| @subtitle @value{UPDATED-MONTH} |
| @author Richard M. Stallman, Roland McGrath, Paul D. Smith |
| @page |
| @vskip 0pt plus 1filll |
| @insertcopying |
| @sp 2 |
| Published by the Free Software Foundation @* |
| 51 Franklin St. -- Fifth Floor @* |
| Boston, MA 02110-1301 USA @* |
| ISBN @value{ISBN} @* |
| @sp 2 |
| Cover art by Etienne Suvasa. |
| @end titlepage |
| |
| @summarycontents |
| @contents |
| |
| @ifnottex |
| @node Top, Overview, (dir), (dir) |
| @top GNU @code{make} |
| |
| @insertcopying |
| @end ifnottex |
| |
| @menu |
| * Overview:: Overview of @code{make}. |
| * Introduction:: An introduction to @code{make}. |
| * Makefiles:: Makefiles tell @code{make} what to do. |
| * Rules:: Rules describe when a file must be remade. |
| * Recipes:: Recipes say how to remake a file. |
| * Using Variables:: You can use variables to avoid repetition. |
| * Conditionals:: Use or ignore parts of the makefile based |
| on the values of variables. |
| * Functions:: Many powerful ways to manipulate text. |
| * Invoking make: Running. How to invoke @code{make} on the command line. |
| * Implicit Rules:: Use implicit rules to treat many files alike, |
| based on their file names. |
| * Archives:: How @code{make} can update library archives. |
| * Extending make:: Using extensions to @code{make}. |
| * Features:: Features GNU @code{make} has over other @code{make}s. |
| * Missing:: What GNU @code{make} lacks from other @code{make}s. |
| * Makefile Conventions:: Conventions for writing makefiles for |
| GNU programs. |
| * Quick Reference:: A quick reference for experienced users. |
| * Error Messages:: A list of common errors generated by @code{make}. |
| * Complex Makefile:: A real example of a straightforward, |
| but nontrivial, makefile. |
| |
| * GNU Free Documentation License:: License for copying this manual. |
| * Concept Index:: Index of Concepts. |
| * Name Index:: Index of Functions, Variables, & Directives. |
| |
| @detailmenu |
| --- The Detailed Node Listing --- |
| |
| Overview of @code{make} |
| |
| * Preparing:: Preparing and running @code{make}. |
| * Reading:: On reading this text. |
| * Bugs:: Problems and bugs. |
| |
| An Introduction to Makefiles |
| |
| * Rule Introduction:: What a rule looks like. |
| * Simple Makefile:: A simple makefile. |
| * How Make Works:: How @code{make} processes this makefile. |
| * Variables Simplify:: Variables make makefiles simpler. |
| * make Deduces:: Letting @code{make} deduce the recipes. |
| * Combine By Prerequisite:: Another style of makefile. |
| * Cleanup:: Rules for cleaning the directory. |
| |
| Writing Makefiles |
| |
| * Makefile Contents:: What makefiles contain. |
| * Makefile Names:: How to name your makefile. |
| * Include:: How one makefile can use another makefile. |
| * MAKEFILES Variable:: The environment can specify extra makefiles. |
| * Remaking Makefiles:: How makefiles get remade. |
| * Overriding Makefiles:: How to override part of one makefile |
| with another makefile. |
| * Reading Makefiles:: How makefiles are parsed. |
| * Secondary Expansion:: How and when secondary expansion is performed. |
| |
| What Makefiles Contain |
| |
| * Splitting Lines:: Splitting long lines in makefiles |
| |
| Writing Rules |
| |
| * Rule Example:: An example explained. |
| * Rule Syntax:: General syntax explained. |
| * Prerequisite Types:: There are two types of prerequisites. |
| * Wildcards:: Using wildcard characters such as `*'. |
| * Directory Search:: Searching other directories for source files. |
| * Phony Targets:: Using a target that is not a real file's name. |
| * Force Targets:: You can use a target without a recipe |
| or prerequisites to mark other targets |
| as phony. |
| * Empty Targets:: When only the date matters and the |
| files are empty. |
| * Special Targets:: Targets with special built-in meanings. |
| * Multiple Targets:: When to make use of several targets in a rule. |
| * Multiple Rules:: How to use several rules with the same target. |
| * Static Pattern:: Static pattern rules apply to multiple targets |
| and can vary the prerequisites according to |
| the target name. |
| * Double-Colon:: How to use a special kind of rule to allow |
| several independent rules for one target. |
| * Automatic Prerequisites:: How to automatically generate rules giving |
| prerequisites from source files themselves. |
| |
| Using Wildcard Characters in File Names |
| |
| * Wildcard Examples:: Several examples. |
| * Wildcard Pitfall:: Problems to avoid. |
| * Wildcard Function:: How to cause wildcard expansion where |
| it does not normally take place. |
| |
| Searching Directories for Prerequisites |
| |
| * General Search:: Specifying a search path that applies |
| to every prerequisite. |
| * Selective Search:: Specifying a search path |
| for a specified class of names. |
| * Search Algorithm:: When and how search paths are applied. |
| * Recipes/Search:: How to write recipes that work together |
| with search paths. |
| * Implicit/Search:: How search paths affect implicit rules. |
| * Libraries/Search:: Directory search for link libraries. |
| |
| Static Pattern Rules |
| |
| * Static Usage:: The syntax of static pattern rules. |
| * Static versus Implicit:: When are they better than implicit rules? |
| |
| Writing Recipes in Rules |
| |
| * Recipe Syntax:: Recipe syntax features and pitfalls. |
| * Echoing:: How to control when recipes are echoed. |
| * Execution:: How recipes are executed. |
| * Parallel:: How recipes can be executed in parallel. |
| * Errors:: What happens after a recipe execution error. |
| * Interrupts:: What happens when a recipe is interrupted. |
| * Recursion:: Invoking @code{make} from makefiles. |
| * Canned Recipes:: Defining canned recipes. |
| * Empty Recipes:: Defining useful, do-nothing recipes. |
| |
| Recipe Syntax |
| |
| * Splitting Recipe Lines:: Breaking long recipe lines for readability. |
| * Variables in Recipes:: Using @code{make} variables in recipes. |
| |
| Recipe Execution |
| |
| * One Shell:: One shell for all lines in a recipe. |
| * Choosing the Shell:: How @code{make} chooses the shell used |
| to run recipes. |
| |
| Parallel Execution |
| |
| * Parallel Output:: Handling output during parallel execution |
| * Parallel Input:: Handling input during parallel execution |
| |
| Recursive Use of @code{make} |
| |
| * MAKE Variable:: The special effects of using @samp{$(MAKE)}. |
| * Variables/Recursion:: How to communicate variables to a sub-@code{make}. |
| * Options/Recursion:: How to communicate options to a sub-@code{make}. |
| * -w Option:: How the @samp{-w} or @samp{--print-directory} option |
| helps debug use of recursive @code{make} commands. |
| |
| How to Use Variables |
| |
| * Reference:: How to use the value of a variable. |
| * Flavors:: Variables come in two flavors. |
| * Advanced:: Advanced features for referencing a variable. |
| * Values:: All the ways variables get their values. |
| * Setting:: How to set a variable in the makefile. |
| * Appending:: How to append more text to the old value |
| of a variable. |
| * Override Directive:: How to set a variable in the makefile even if |
| the user has set it with a command argument. |
| * Multi-Line:: An alternate way to set a variable |
| to a multi-line string. |
| * Undefine Directive:: How to undefine a variable so that it appears |
| as if it was never set. |
| * Environment:: Variable values can come from the environment. |
| * Target-specific:: Variable values can be defined on a per-target |
| basis. |
| * Pattern-specific:: Target-specific variable values can be applied |
| to a group of targets that match a pattern. |
| * Suppressing Inheritance:: Suppress inheritance of variables. |
| * Special Variables:: Variables with special meaning or behavior. |
| |
| Advanced Features for Reference to Variables |
| |
| * Substitution Refs:: Referencing a variable with |
| substitutions on the value. |
| * Computed Names:: Computing the name of the variable to refer to. |
| |
| Conditional Parts of Makefiles |
| |
| * Conditional Example:: Example of a conditional |
| * Conditional Syntax:: The syntax of conditionals. |
| * Testing Flags:: Conditionals that test flags. |
| |
| Functions for Transforming Text |
| |
| * Syntax of Functions:: How to write a function call. |
| * Text Functions:: General-purpose text manipulation functions. |
| * File Name Functions:: Functions for manipulating file names. |
| * Conditional Functions:: Functions that implement conditions. |
| * Foreach Function:: Repeat some text with controlled variation. |
| * File Function:: Write text to a file. |
| * Call Function:: Expand a user-defined function. |
| * Value Function:: Return the un-expanded value of a variable. |
| * Eval Function:: Evaluate the arguments as makefile syntax. |
| * Origin Function:: Find where a variable got its value. |
| * Flavor Function:: Find out the flavor of a variable. |
| * Make Control Functions:: Functions that control how make runs. |
| * Shell Function:: Substitute the output of a shell command. |
| * Guile Function:: Use GNU Guile embedded scripting language. |
| |
| How to Run @code{make} |
| |
| * Makefile Arguments:: How to specify which makefile to use. |
| * Goals:: How to use goal arguments to specify which |
| parts of the makefile to use. |
| * Instead of Execution:: How to use mode flags to specify what |
| kind of thing to do with the recipes |
| in the makefile other than simply |
| execute them. |
| * Avoiding Compilation:: How to avoid recompiling certain files. |
| * Overriding:: How to override a variable to specify |
| an alternate compiler and other things. |
| * Testing:: How to proceed past some errors, to |
| test compilation. |
| * Options Summary:: Summary of Options |
| |
| Using Implicit Rules |
| |
| * Using Implicit:: How to use an existing implicit rule |
| to get the recipes for updating a file. |
| * Catalogue of Rules:: A list of built-in rules. |
| * Implicit Variables:: How to change what predefined rules do. |
| * Chained Rules:: How to use a chain of implicit rules. |
| * Pattern Rules:: How to define new implicit rules. |
| * Last Resort:: How to define a recipe for rules which |
| cannot find any. |
| * Suffix Rules:: The old-fashioned style of implicit rule. |
| * Implicit Rule Search:: The precise algorithm for applying |
| implicit rules. |
| |
| Defining and Redefining Pattern Rules |
| |
| * Pattern Intro:: An introduction to pattern rules. |
| * Pattern Examples:: Examples of pattern rules. |
| * Automatic Variables:: How to use automatic variables in the |
| recipe of implicit rules. |
| * Pattern Match:: How patterns match. |
| * Match-Anything Rules:: Precautions you should take prior to |
| defining rules that can match any |
| target file whatever. |
| * Canceling Rules:: How to override or cancel built-in rules. |
| |
| Using @code{make} to Update Archive Files |
| |
| * Archive Members:: Archive members as targets. |
| * Archive Update:: The implicit rule for archive member targets. |
| * Archive Pitfalls:: Dangers to watch out for when using archives. |
| * Archive Suffix Rules:: You can write a special kind of suffix rule |
| for updating archives. |
| |
| Implicit Rule for Archive Member Targets |
| |
| * Archive Symbols:: How to update archive symbol directories. |
| |
| Extending GNU @code{make} |
| |
| * Guile Integration:: Using Guile as an embedded scripting language. |
| * Loading Objects:: Loading dynamic objects as extensions. |
| |
| GNU Guile Integration |
| |
| * Guile Types:: Converting Guile types to @code{make} strings. |
| * Guile Interface:: Invoking @code{make} functions from Guile. |
| * Guile Example:: Example using Guile in @code{make}. |
| |
| Loading Dynamic Objects |
| |
| * load Directive:: Loading dynamic objects as extensions. |
| * Remaking Loaded Objects:: How loaded objects get remade. |
| * Loaded Object API:: Programmatic interface for loaded objects. |
| * Loaded Object Example:: Example of a loaded object |
| |
| @end detailmenu |
| @end menu |
| |
| @node Overview, Introduction, Top, Top |
| @comment node-name, next, previous, up |
| @chapter Overview of @code{make} |
| |
| The @code{make} utility automatically determines which pieces of a large |
| program need to be recompiled, and issues commands to recompile them. |
| This manual describes GNU @code{make}, which was implemented by Richard |
| Stallman and Roland McGrath. Development since Version 3.76 has been |
| handled by Paul D. Smith. |
| |
| GNU @code{make} conforms to section 6.2 of @cite{IEEE Standard |
| 1003.2-1992} (POSIX.2). |
| @cindex POSIX |
| @cindex IEEE Standard 1003.2 |
| @cindex standards conformance |
| |
| Our examples show C programs, since they are most common, but you can use |
| @code{make} with any programming language whose compiler can be run with a |
| shell command. Indeed, @code{make} is not limited to programs. You can |
| use it to describe any task where some files must be updated automatically |
| from others whenever the others change. |
| |
| @menu |
| * Preparing:: Preparing and running @code{make}. |
| * Reading:: On reading this text. |
| * Bugs:: Problems and bugs. |
| @end menu |
| |
| @node Preparing, Reading, Overview, Overview |
| @ifnottex |
| @heading Preparing and Running Make |
| @end ifnottex |
| |
| To prepare to use @code{make}, you must write a file called |
| the @dfn{makefile} that describes the relationships among files |
| in your program and provides commands for updating each file. |
| In a program, typically, the executable file is updated from object |
| files, which are in turn made by compiling source files.@refill |
| |
| Once a suitable makefile exists, each time you change some source files, |
| this simple shell command: |
| |
| @example |
| make |
| @end example |
| |
| @noindent |
| suffices to perform all necessary recompilations. The @code{make} program |
| uses the makefile data base and the last-modification times of the files to |
| decide which of the files need to be updated. For each of those files, it |
| issues the recipes recorded in the data base. |
| |
| You can provide command line arguments to @code{make} to control which |
| files should be recompiled, or how. @xref{Running, ,How to Run |
| @code{make}}. |
| |
| @node Reading, Bugs, Preparing, Overview |
| @section How to Read This Manual |
| |
| If you are new to @code{make}, or are looking for a general |
| introduction, read the first few sections of each chapter, skipping the |
| later sections. In each chapter, the first few sections contain |
| introductory or general information and the later sections contain |
| specialized or technical information. |
| @ifnottex |
| The exception is the second chapter, @ref{Introduction, ,An |
| Introduction to Makefiles}, all of which is introductory. |
| @end ifnottex |
| @iftex |
| The exception is @ref{Introduction, ,An Introduction to Makefiles}, |
| all of which is introductory. |
| @end iftex |
| |
| If you are familiar with other @code{make} programs, see @ref{Features, |
| ,Features of GNU @code{make}}, which lists the enhancements GNU |
| @code{make} has, and @ref{Missing, ,Incompatibilities and Missing |
| Features}, which explains the few things GNU @code{make} lacks that |
| others have. |
| |
| For a quick summary, see @ref{Options Summary}, @ref{Quick Reference}, |
| and @ref{Special Targets}. |
| |
| @node Bugs, , Reading, Overview |
| @section Problems and Bugs |
| @cindex reporting bugs |
| @cindex bugs, reporting |
| @cindex problems and bugs, reporting |
| |
| If you have problems with GNU @code{make} or think you've found a bug, |
| please report it to the developers; we cannot promise to do anything but |
| we might well want to fix it. |
| |
| Before reporting a bug, make sure you've actually found a real bug. |
| Carefully reread the documentation and see if it really says you can do |
| what you're trying to do. If it's not clear whether you should be able |
| to do something or not, report that too; it's a bug in the |
| documentation! |
| |
| Before reporting a bug or trying to fix it yourself, try to isolate it |
| to the smallest possible makefile that reproduces the problem. Then |
| send us the makefile and the exact results @code{make} gave you, |
| including any error or warning messages. Please don't paraphrase |
| these messages: it's best to cut and paste them into your report. |
| When generating this small makefile, be sure to not use any non-free |
| or unusual tools in your recipes: you can almost always emulate what |
| such a tool would do with simple shell commands. Finally, be sure to |
| explain what you expected to occur; this will help us decide whether |
| the problem was really in the documentation. |
| |
| Once you have a precise problem you can report it in one of two ways. |
| Either send electronic mail to: |
| |
| @example |
| bug-make@@gnu.org |
| @end example |
| |
| @noindent |
| or use our Web-based project management tool, at: |
| |
| @example |
| http://savannah.gnu.org/projects/make/ |
| @end example |
| |
| @noindent |
| In addition to the information above, please be careful to include the |
| version number of @code{make} you are using. You can get this |
| information with the command @samp{make --version}. Be sure also to |
| include the type of machine and operating system you are using. One |
| way to obtain this information is by looking at the final lines of |
| output from the command @samp{make --help}. |
| |
| @node Introduction, Makefiles, Overview, Top |
| @comment node-name, next, previous, up |
| @chapter An Introduction to Makefiles |
| |
| You need a file called a @dfn{makefile} to tell @code{make} what to do. |
| Most often, the makefile tells @code{make} how to compile and link a |
| program. |
| @cindex makefile |
| |
| In this chapter, we will discuss a simple makefile that describes how to |
| compile and link a text editor which consists of eight C source files |
| and three header files. The makefile can also tell @code{make} how to |
| run miscellaneous commands when explicitly asked (for example, to remove |
| certain files as a clean-up operation). To see a more complex example |
| of a makefile, see @ref{Complex Makefile}. |
| |
| When @code{make} recompiles the editor, each changed C source file |
| must be recompiled. If a header file has changed, each C source file |
| that includes the header file must be recompiled to be safe. Each |
| compilation produces an object file corresponding to the source file. |
| Finally, if any source file has been recompiled, all the object files, |
| whether newly made or saved from previous compilations, must be linked |
| together to produce the new executable editor. |
| @cindex recompilation |
| @cindex editor |
| |
| @menu |
| * Rule Introduction:: What a rule looks like. |
| * Simple Makefile:: A simple makefile. |
| * How Make Works:: How @code{make} processes this makefile. |
| * Variables Simplify:: Variables make makefiles simpler. |
| * make Deduces:: Letting @code{make} deduce the recipes. |
| * Combine By Prerequisite:: Another style of makefile. |
| * Cleanup:: Rules for cleaning the directory. |
| @end menu |
| |
| @node Rule Introduction, Simple Makefile, Introduction, Introduction |
| @comment node-name, next, previous, up |
| @section What a Rule Looks Like |
| @cindex rule, introduction to |
| @cindex makefile rule parts |
| @cindex parts of makefile rule |
| |
| A simple makefile consists of ``rules'' with the following shape: |
| |
| @cindex targets, introduction to |
| @cindex prerequisites, introduction to |
| @cindex recipes, introduction to |
| @example |
| @group |
| @var{target} @dots{} : @var{prerequisites} @dots{} |
| @var{recipe} |
| @dots{} |
| @dots{} |
| @end group |
| @end example |
| |
| A @dfn{target} is usually the name of a file that is generated by a |
| program; examples of targets are executable or object files. A target |
| can also be the name of an action to carry out, such as @samp{clean} |
| (@pxref{Phony Targets}). |
| |
| A @dfn{prerequisite} is a file that is used as input to create the |
| target. A target often depends on several files. |
| |
| @cindex tabs in rules |
| A @dfn{recipe} is an action that @code{make} carries out. A recipe |
| may have more than one command, either on the same line or each on its |
| own line. @strong{Please note:} you need to put a tab character at |
| the beginning of every recipe line! This is an obscurity that catches |
| the unwary. If you prefer to prefix your recipes with a character |
| other than tab, you can set the @code{.RECIPEPREFIX} variable to an |
| alternate character (@pxref{Special Variables}). |
| |
| Usually a recipe is in a rule with prerequisites and serves to create a |
| target file if any of the prerequisites change. However, the rule that |
| specifies a recipe for the target need not have prerequisites. For |
| example, the rule containing the delete command associated with the |
| target @samp{clean} does not have prerequisites. |
| |
| A @dfn{rule}, then, explains how and when to remake certain files |
| which are the targets of the particular rule. @code{make} carries out |
| the recipe on the prerequisites to create or update the target. A |
| rule can also explain how and when to carry out an action. |
| @xref{Rules, , Writing Rules}. |
| |
| A makefile may contain other text besides rules, but a simple makefile |
| need only contain rules. Rules may look somewhat more complicated |
| than shown in this template, but all fit the pattern more or less. |
| |
| @node Simple Makefile, How Make Works, Rule Introduction, Introduction |
| @section A Simple Makefile |
| @cindex simple makefile |
| @cindex makefile, simple |
| |
| Here is a straightforward makefile that describes the way an |
| executable file called @code{edit} depends on eight object files |
| which, in turn, depend on eight C source and three header files. |
| |
| In this example, all the C files include @file{defs.h}, but only those |
| defining editing commands include @file{command.h}, and only low |
| level files that change the editor buffer include @file{buffer.h}. |
| |
| @example |
| @group |
| edit : main.o kbd.o command.o display.o \ |
| insert.o search.o files.o utils.o |
| cc -o edit main.o kbd.o command.o display.o \ |
| insert.o search.o files.o utils.o |
| |
| main.o : main.c defs.h |
| cc -c main.c |
| kbd.o : kbd.c defs.h command.h |
| cc -c kbd.c |
| command.o : command.c defs.h command.h |
| cc -c command.c |
| display.o : display.c defs.h buffer.h |
| cc -c display.c |
| insert.o : insert.c defs.h buffer.h |
| cc -c insert.c |
| search.o : search.c defs.h buffer.h |
| cc -c search.c |
| files.o : files.c defs.h buffer.h command.h |
| cc -c files.c |
| utils.o : utils.c defs.h |
| cc -c utils.c |
| clean : |
| rm edit main.o kbd.o command.o display.o \ |
| insert.o search.o files.o utils.o |
| @end group |
| @end example |
| |
| @noindent |
| We split each long line into two lines using backslash/newline; this is |
| like using one long line, but is easier to read. @xref{Splitting Lines, |
| , Splitting Long Lines}. |
| @cindex continuation lines |
| @cindex @code{\} (backslash), for continuation lines |
| @cindex backslash (@code{\}), for continuation lines |
| @cindex quoting newline, in makefile |
| @cindex newline, quoting, in makefile |
| |
| To use this makefile to create the executable file called @file{edit}, |
| type: |
| |
| @example |
| make |
| @end example |
| |
| To use this makefile to delete the executable file and all the object |
| files from the directory, type: |
| |
| @example |
| make clean |
| @end example |
| |
| In the example makefile, the targets include the executable file |
| @samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}. The |
| prerequisites are files such as @samp{main.c} and @samp{defs.h}. |
| In fact, each @samp{.o} file is both a target and a prerequisite. |
| Recipes include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}. |
| |
| When a target is a file, it needs to be recompiled or relinked if any |
| of its prerequisites change. In addition, any prerequisites that are |
| themselves automatically generated should be updated first. In this |
| example, @file{edit} depends on each of the eight object files; the |
| object file @file{main.o} depends on the source file @file{main.c} and |
| on the header file @file{defs.h}. |
| |
| A recipe may follow each line that contains a target and |
| prerequisites. These recipes say how to update the target file. A |
| tab character (or whatever character is specified by the |
| @code{.RECIPEPREFIX} variable; @pxref{Special Variables}) must come at |
| the beginning of every line in the recipe to distinguish recipes from |
| other lines in the makefile. (Bear in mind that @code{make} does not |
| know anything about how the recipes work. It is up to you to supply |
| recipes that will update the target file properly. All @code{make} |
| does is execute the recipe you have specified when the target file |
| needs to be updated.)@refill |
| @cindex recipe |
| |
| The target @samp{clean} is not a file, but merely the name of an |
| action. Since you normally do not want to carry out the actions in |
| this rule, @samp{clean} is not a prerequisite of any other rule. |
| Consequently, @code{make} never does anything with it unless you tell |
| it specifically. Note that this rule not only is not a prerequisite, |
| it also does not have any prerequisites, so the only purpose of the |
| rule is to run the specified recipe. Targets that do not refer to |
| files but are just actions are called @dfn{phony targets}. |
| @xref{Phony Targets}, for information about this kind of target. |
| @xref{Errors, , Errors in Recipes}, to see how to cause @code{make} |
| to ignore errors from @code{rm} or any other command. |
| @cindex @code{clean} target |
| @cindex @code{rm} (shell command) |
| |
| @node How Make Works, Variables Simplify, Simple Makefile, Introduction |
| @comment node-name, next, previous, up |
| @section How @code{make} Processes a Makefile |
| @cindex processing a makefile |
| @cindex makefile, how @code{make} processes |
| |
| By default, @code{make} starts with the first target (not targets whose |
| names start with @samp{.}). This is called the @dfn{default goal}. |
| (@dfn{Goals} are the targets that @code{make} strives ultimately to |
| update. You can override this behavior using the command line |
| (@pxref{Goals, , Arguments to Specify the Goals}) or with the |
| @code{.DEFAULT_GOAL} special variable (@pxref{Special Variables, , |
| Other Special Variables}). |
| @cindex default goal |
| @cindex goal, default |
| @cindex goal |
| |
| In the simple example of the previous section, the default goal is to |
| update the executable program @file{edit}; therefore, we put that rule |
| first. |
| |
| Thus, when you give the command: |
| |
| @example |
| make |
| @end example |
| |
| @noindent |
| @code{make} reads the makefile in the current directory and begins by |
| processing the first rule. In the example, this rule is for relinking |
| @file{edit}; but before @code{make} can fully process this rule, it |
| must process the rules for the files that @file{edit} depends on, |
| which in this case are the object files. Each of these files is |
| processed according to its own rule. These rules say to update each |
| @samp{.o} file by compiling its source file. The recompilation must |
| be done if the source file, or any of the header files named as |
| prerequisites, is more recent than the object file, or if the object |
| file does not exist. |
| |
| The other rules are processed because their targets appear as |
| prerequisites of the goal. If some other rule is not depended on by the |
| goal (or anything it depends on, etc.), that rule is not processed, |
| unless you tell @code{make} to do so (with a command such as |
| @w{@code{make clean}}). |
| |
| Before recompiling an object file, @code{make} considers updating its |
| prerequisites, the source file and header files. This makefile does not |
| specify anything to be done for them---the @samp{.c} and @samp{.h} files |
| are not the targets of any rules---so @code{make} does nothing for these |
| files. But @code{make} would update automatically generated C programs, |
| such as those made by Bison or Yacc, by their own rules at this time. |
| |
| After recompiling whichever object files need it, @code{make} decides |
| whether to relink @file{edit}. This must be done if the file |
| @file{edit} does not exist, or if any of the object files are newer than |
| it. If an object file was just recompiled, it is now newer than |
| @file{edit}, so @file{edit} is relinked. |
| @cindex relinking |
| |
| Thus, if we change the file @file{insert.c} and run @code{make}, |
| @code{make} will compile that file to update @file{insert.o}, and then |
| link @file{edit}. If we change the file @file{command.h} and run |
| @code{make}, @code{make} will recompile the object files @file{kbd.o}, |
| @file{command.o} and @file{files.o} and then link the file @file{edit}. |
| |
| @node Variables Simplify, make Deduces, How Make Works, Introduction |
| @section Variables Make Makefiles Simpler |
| @cindex variables |
| @cindex simplifying with variables |
| |
| In our example, we had to list all the object files twice in the rule for |
| @file{edit} (repeated here): |
| |
| @example |
| @group |
| edit : main.o kbd.o command.o display.o \ |
| insert.o search.o files.o utils.o |
| cc -o edit main.o kbd.o command.o display.o \ |
| insert.o search.o files.o utils.o |
| @end group |
| @end example |
| |
| @cindex @code{objects} |
| Such duplication is error-prone; if a new object file is added to the |
| system, we might add it to one list and forget the other. We can eliminate |
| the risk and simplify the makefile by using a variable. @dfn{Variables} |
| allow a text string to be defined once and substituted in multiple places |
| later (@pxref{Using Variables, ,How to Use Variables}). |
| |
| @cindex @code{OBJECTS} |
| @cindex @code{objs} |
| @cindex @code{OBJS} |
| @cindex @code{obj} |
| @cindex @code{OBJ} |
| It is standard practice for every makefile to have a variable named |
| @code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj}, |
| or @code{OBJ} which is a list of all object file names. We would |
| define such a variable @code{objects} with a line like this in the |
| makefile:@refill |
| |
| @example |
| @group |
| objects = main.o kbd.o command.o display.o \ |
| insert.o search.o files.o utils.o |
| @end group |
| @end example |
| |
| @noindent |
| Then, each place we want to put a list of the object file names, we can |
| substitute the variable's value by writing @samp{$(objects)} |
| (@pxref{Using Variables, ,How to Use Variables}). |
| |
| Here is how the complete simple makefile looks when you use a variable |
| for the object files: |
| |
| @example |
| @group |
| objects = main.o kbd.o command.o display.o \ |
| insert.o search.o files.o utils.o |
| |
| edit : $(objects) |
| cc -o edit $(objects) |
| main.o : main.c defs.h |
| cc -c main.c |
| kbd.o : kbd.c defs.h command.h |
| cc -c kbd.c |
| command.o : command.c defs.h command.h |
| cc -c command.c |
| display.o : display.c defs.h buffer.h |
| cc -c display.c |
| insert.o : insert.c defs.h buffer.h |
| cc -c insert.c |
| search.o : search.c defs.h buffer.h |
| cc -c search.c |
| files.o : files.c defs.h buffer.h command.h |
| cc -c files.c |
| utils.o : utils.c defs.h |
| cc -c utils.c |
| clean : |
| rm edit $(objects) |
| @end group |
| @end example |
| |
| @node make Deduces, Combine By Prerequisite, Variables Simplify, Introduction |
| @section Letting @code{make} Deduce the Recipes |
| @cindex deducing recipes (implicit rules) |
| @cindex implicit rule, introduction to |
| @cindex rule, implicit, introduction to |
| |
| It is not necessary to spell out the recipes for compiling the individual |
| C source files, because @code{make} can figure them out: it has an |
| @dfn{implicit rule} for updating a @samp{.o} file from a correspondingly |
| named @samp{.c} file using a @samp{cc -c} command. For example, it will |
| use the recipe @samp{cc -c main.c -o main.o} to compile @file{main.c} into |
| @file{main.o}. We can therefore omit the recipes from the rules for the |
| object files. @xref{Implicit Rules, ,Using Implicit Rules}.@refill |
| |
| When a @samp{.c} file is used automatically in this way, it is also |
| automatically added to the list of prerequisites. We can therefore omit |
| the @samp{.c} files from the prerequisites, provided we omit the recipe. |
| |
| Here is the entire example, with both of these changes, and a variable |
| @code{objects} as suggested above: |
| |
| @example |
| @group |
| objects = main.o kbd.o command.o display.o \ |
| insert.o search.o files.o utils.o |
| |
| edit : $(objects) |
| cc -o edit $(objects) |
| |
| main.o : defs.h |
| kbd.o : defs.h command.h |
| command.o : defs.h command.h |
| display.o : defs.h buffer.h |
| insert.o : defs.h buffer.h |
| search.o : defs.h buffer.h |
| files.o : defs.h buffer.h command.h |
| utils.o : defs.h |
| |
| .PHONY : clean |
| clean : |
| rm edit $(objects) |
| @end group |
| @end example |
| |
| @noindent |
| This is how we would write the makefile in actual practice. (The |
| complications associated with @samp{clean} are described elsewhere. |
| See @ref{Phony Targets}, and @ref{Errors, ,Errors in Recipes}.) |
| |
| Because implicit rules are so convenient, they are important. You |
| will see them used frequently.@refill |
| |
| @node Combine By Prerequisite, Cleanup, make Deduces, Introduction |
| @section Another Style of Makefile |
| @cindex combining rules by prerequisite |
| |
| When the objects of a makefile are created only by implicit rules, an |
| alternative style of makefile is possible. In this style of makefile, |
| you group entries by their prerequisites instead of by their targets. |
| Here is what one looks like: |
| |
| @example |
| @group |
| objects = main.o kbd.o command.o display.o \ |
| insert.o search.o files.o utils.o |
| |
| edit : $(objects) |
| cc -o edit $(objects) |
| |
| $(objects) : defs.h |
| kbd.o command.o files.o : command.h |
| display.o insert.o search.o files.o : buffer.h |
| @end group |
| @end example |
| |
| @noindent |
| Here @file{defs.h} is given as a prerequisite of all the object files; |
| @file{command.h} and @file{buffer.h} are prerequisites of the specific |
| object files listed for them. |
| |
| Whether this is better is a matter of taste: it is more compact, but some |
| people dislike it because they find it clearer to put all the information |
| about each target in one place. |
| |
| @node Cleanup, , Combine By Prerequisite, Introduction |
| @section Rules for Cleaning the Directory |
| @cindex cleaning up |
| @cindex removing, to clean up |
| |
| Compiling a program is not the only thing you might want to write rules |
| for. Makefiles commonly tell how to do a few other things besides |
| compiling a program: for example, how to delete all the object files |
| and executables so that the directory is @samp{clean}. |
| |
| @cindex @code{clean} target |
| Here is how we |
| could write a @code{make} rule for cleaning our example editor: |
| |
| @example |
| @group |
| clean: |
| rm edit $(objects) |
| @end group |
| @end example |
| |
| In practice, we might want to write the rule in a somewhat more |
| complicated manner to handle unanticipated situations. We would do this: |
| |
| @example |
| @group |
| .PHONY : clean |
| clean : |
| -rm edit $(objects) |
| @end group |
| @end example |
| |
| @noindent |
| This prevents @code{make} from getting confused by an actual file |
| called @file{clean} and causes it to continue in spite of errors from |
| @code{rm}. (See @ref{Phony Targets}, and @ref{Errors, ,Errors in |
| Recipes}.) |
| |
| @noindent |
| A rule such as this should not be placed at the beginning of the |
| makefile, because we do not want it to run by default! Thus, in the |
| example makefile, we want the rule for @code{edit}, which recompiles |
| the editor, to remain the default goal. |
| |
| Since @code{clean} is not a prerequisite of @code{edit}, this rule will not |
| run at all if we give the command @samp{make} with no arguments. In |
| order to make the rule run, we have to type @samp{make clean}. |
| @xref{Running, ,How to Run @code{make}}. |
| |
| @node Makefiles, Rules, Introduction, Top |
| @chapter Writing Makefiles |
| |
| @cindex makefile, how to write |
| The information that tells @code{make} how to recompile a system comes from |
| reading a data base called the @dfn{makefile}. |
| |
| @menu |
| * Makefile Contents:: What makefiles contain. |
| * Makefile Names:: How to name your makefile. |
| * Include:: How one makefile can use another makefile. |
| * MAKEFILES Variable:: The environment can specify extra makefiles. |
| * Remaking Makefiles:: How makefiles get remade. |
| * Overriding Makefiles:: How to override part of one makefile |
| with another makefile. |
| * Reading Makefiles:: How makefiles are parsed. |
| * Secondary Expansion:: How and when secondary expansion is performed. |
| @end menu |
| |
| @node Makefile Contents, Makefile Names, Makefiles, Makefiles |
| @section What Makefiles Contain |
| |
| Makefiles contain five kinds of things: @dfn{explicit rules}, |
| @dfn{implicit rules}, @dfn{variable definitions}, @dfn{directives}, |
| and @dfn{comments}. Rules, variables, and directives are described at |
| length in later chapters.@refill |
| |
| @itemize @bullet |
| @cindex rule, explicit, definition of |
| @cindex explicit rule, definition of |
| @item |
| An @dfn{explicit rule} says when and how to remake one or more files, |
| called the rule's @dfn{targets}. It lists the other files that the |
| targets depend on, called the @dfn{prerequisites} of the target, and |
| may also give a recipe to use to create or update the targets. |
| @xref{Rules, ,Writing Rules}. |
| |
| @cindex rule, implicit, definition of |
| @cindex implicit rule, definition of |
| @item |
| An @dfn{implicit rule} says when and how to remake a class of files |
| based on their names. It describes how a target may depend on a file |
| with a name similar to the target and gives a recipe to create or |
| update such a target. @xref{Implicit Rules, ,Using Implicit Rules}. |
| |
| @cindex variable definition |
| @item |
| A @dfn{variable definition} is a line that specifies a text string |
| value for a variable that can be substituted into the text later. The |
| simple makefile example shows a variable definition for @code{objects} |
| as a list of all object files (@pxref{Variables Simplify, , Variables |
| Make Makefiles Simpler}). |
| |
| @cindex directive |
| @item |
| A @dfn{directive} is an instruction for @code{make} to do something |
| special while reading the makefile. These include: |
| |
| @itemize @bullet |
| @item |
| Reading another makefile (@pxref{Include, ,Including Other Makefiles}). |
| |
| @item |
| Deciding (based on the values of variables) whether to use or |
| ignore a part of the makefile (@pxref{Conditionals, ,Conditional Parts of Makefiles}). |
| |
| @item |
| Defining a variable from a verbatim string containing multiple lines |
| (@pxref{Multi-Line, ,Defining Multi-Line Variables}). |
| @end itemize |
| |
| @cindex comments, in makefile |
| @cindex @code{#} (comments), in makefile |
| @item |
| @samp{#} in a line of a makefile starts a @dfn{comment}. It and the |
| rest of the line are ignored, except that a trailing backslash not |
| escaped by another backslash will continue the comment across multiple |
| lines. A line containing just a comment (with perhaps spaces before |
| it) is effectively blank, and is ignored. If you want a literal |
| @code{#}, escape it with a backslash (e.g., @code{\#}). Comments may |
| appear on any line in the makefile, although they are treated |
| specially in certain situations. |
| |
| You cannot use comments within variable references or function calls: |
| any instance of @code{#} will be treated literally (rather than as the |
| start of a comment) inside a variable reference or function call. |
| |
| Comments within a recipe are passed to the shell, just as with any |
| other recipe text. The shell decides how to interpret it: whether or |
| not this is a comment is up to the shell. |
| |
| Within a @code{define} directive, comments are not ignored during the |
| definition of the variable, but rather kept intact in the value of the |
| variable. When the variable is expanded they will either be treated |
| as @code{make} comments or as recipe text, depending on the context in |
| which the variable is evaluated. |
| @end itemize |
| |
| @menu |
| * Splitting Lines:: Splitting long lines in makefiles |
| @end menu |
| |
| @node Splitting Lines, , Makefile Contents, Makefile Contents |
| @subsection Splitting Long Lines |
| @cindex splitting long lines |
| @cindex long lines, splitting |
| @cindex backslash (@code{\}), to quote newlines |
| |
| Makefiles use a ``line-based'' syntax in which the newline character |
| is special and marks the end of a statement. GNU @code{make} has no |
| limit on the length of a statement line, up to the amount of memory in |
| your computer. |
| |
| However, it is difficult to read lines which are too long to display |
| without wrapping or scrolling. So, you can format your makefiles for |
| readability by adding newlines into the middle of a statement: you do |
| this by escaping the internal newlines with a backslash (@code{\}) |
| character. Where we need to make a distinction we will refer to |
| ``physical lines'' as a single line ending with a newline (regardless |
| of whether it is escaped) and a ``logical line'' being a complete |
| statement including all escaped newlines up to the first non-escaped |
| newline. |
| |
| The way in which backslash/newline combinations are handled depends on |
| whether the statement is a recipe line or a non-recipe line. Handling |
| of backslash/newline in a recipe line is discussed later |
| (@pxref{Splitting Recipe Lines}). |
| |
| Outside of recipe lines, backslash/newlines are converted into a |
| single space character. Once that is done, all whitespace around the |
| backslash/newline is condensed into a single space: this includes all |
| whitespace preceding the backslash, all whitespace at the beginning of |
| the line after the backslash/newline, and any consecutive |
| backslash/newline combinations. |
| |
| If the @code{.POSIX} special target is defined then backslash/newline |
| handling is modified slightly to conform to POSIX.2: first, whitespace |
| preceding a backslash is not removed and second, consecutive |
| backslash/newlines are not condensed. |
| |
| @node Makefile Names, Include, Makefile Contents, Makefiles |
| @section What Name to Give Your Makefile |
| @cindex makefile name |
| @cindex name of makefile |
| @cindex default makefile name |
| @cindex file name of makefile |
| |
| @c following paragraph rewritten to avoid overfull hbox |
| By default, when @code{make} looks for the makefile, it tries the |
| following names, in order: @file{GNUmakefile}, @file{makefile} |
| and @file{Makefile}.@refill |
| @findex Makefile |
| @findex GNUmakefile |
| @findex makefile |
| |
| @cindex @code{README} |
| Normally you should call your makefile either @file{makefile} or |
| @file{Makefile}. (We recommend @file{Makefile} because it appears |
| prominently near the beginning of a directory listing, right near other |
| important files such as @file{README}.) The first name checked, |
| @file{GNUmakefile}, is not recommended for most makefiles. You should |
| use this name if you have a makefile that is specific to GNU |
| @code{make}, and will not be understood by other versions of |
| @code{make}. Other @code{make} programs look for @file{makefile} and |
| @file{Makefile}, but not @file{GNUmakefile}. |
| |
| If @code{make} finds none of these names, it does not use any makefile. |
| Then you must specify a goal with a command argument, and @code{make} |
| will attempt to figure out how to remake it using only its built-in |
| implicit rules. @xref{Implicit Rules, ,Using Implicit Rules}. |
| |
| @cindex @code{-f} |
| @cindex @code{--file} |
| @cindex @code{--makefile} |
| If you want to use a nonstandard name for your makefile, you can specify |
| the makefile name with the @samp{-f} or @samp{--file} option. The |
| arguments @w{@samp{-f @var{name}}} or @w{@samp{--file=@var{name}}} tell |
| @code{make} to read the file @var{name} as the makefile. If you use |
| more than one @samp{-f} or @samp{--file} option, you can specify several |
| makefiles. All the makefiles are effectively concatenated in the order |
| specified. The default makefile names @file{GNUmakefile}, |
| @file{makefile} and @file{Makefile} are not checked automatically if you |
| specify @samp{-f} or @samp{--file}.@refill |
| @cindex specifying makefile name |
| @cindex makefile name, how to specify |
| @cindex name of makefile, how to specify |
| @cindex file name of makefile, how to specify |
| |
| @node Include, MAKEFILES Variable, Makefile Names, Makefiles |
| @section Including Other Makefiles |
| @cindex including other makefiles |
| @cindex makefile, including |
| |
| @findex include |
| The @code{include} directive tells @code{make} to suspend reading the |
| current makefile and read one or more other makefiles before continuing. |
| The directive is a line in the makefile that looks like this: |
| |
| @example |
| include @var{filenames}@dots{} |
| @end example |
| |
| @noindent |
| @var{filenames} can contain shell file name patterns. If |
| @var{filenames} is empty, nothing is included and no error is printed. |
| @cindex shell file name pattern (in @code{include}) |
| @cindex shell wildcards (in @code{include}) |
| @cindex wildcard, in @code{include} |
| |
| Extra spaces are allowed and ignored at the beginning of the line, but |
| the first character must not be a tab (or the value of |
| @code{.RECIPEPREFIX})---if the line begins with a tab, it will be |
| considered a recipe line. Whitespace is required between |
| @code{include} and the file names, and between file names; extra |
| whitespace is ignored there and at the end of the directive. A |
| comment starting with @samp{#} is allowed at the end of the line. If |
| the file names contain any variable or function references, they are |
| expanded. @xref{Using Variables, ,How to Use Variables}. |
| |
| For example, if you have three @file{.mk} files, @file{a.mk}, |
| @file{b.mk}, and @file{c.mk}, and @code{$(bar)} expands to |
| @code{bish bash}, then the following expression |
| |
| @example |
| include foo *.mk $(bar) |
| @end example |
| |
| is equivalent to |
| |
| @example |
| include foo a.mk b.mk c.mk bish bash |
| @end example |
| |
| When @code{make} processes an @code{include} directive, it suspends |
| reading of the containing makefile and reads from each listed file in |
| turn. When that is finished, @code{make} resumes reading the |
| makefile in which the directive appears. |
| |
| One occasion for using @code{include} directives is when several programs, |
| handled by individual makefiles in various directories, need to use a |
| common set of variable definitions |
| (@pxref{Setting, ,Setting Variables}) or pattern rules |
| (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}). |
| |
| Another such occasion is when you want to generate prerequisites from |
| source files automatically; the prerequisites can be put in a file that |
| is included by the main makefile. This practice is generally cleaner |
| than that of somehow appending the prerequisites to the end of the main |
| makefile as has been traditionally done with other versions of |
| @code{make}. @xref{Automatic Prerequisites}. |
| @cindex prerequisites, automatic generation |
| @cindex automatic generation of prerequisites |
| @cindex generating prerequisites automatically |
| |
| @cindex @code{-I} |
| @cindex @code{--include-dir} |
| @cindex included makefiles, default directories |
| @cindex default directories for included makefiles |
| @findex /usr/gnu/include |
| @findex /usr/local/include |
| @findex /usr/include |
| If the specified name does not start with a slash, and the file is not |
| found in the current directory, several other directories are searched. |
| First, any directories you have specified with the @samp{-I} or |
| @samp{--include-dir} option are searched |
| (@pxref{Options Summary, ,Summary of Options}). |
| Then the following directories (if they exist) |
| are searched, in this order: |
| @file{@var{prefix}/include} (normally @file{/usr/local/include} |
| @footnote{GNU Make compiled for MS-DOS and MS-Windows behaves as if |
| @var{prefix} has been defined to be the root of the DJGPP tree |
| hierarchy.}) |
| @file{/usr/gnu/include}, |
| @file{/usr/local/include}, @file{/usr/include}. |
| |
| If an included makefile cannot be found in any of these directories, a |
| warning message is generated, but it is not an immediately fatal error; |
| processing of the makefile containing the @code{include} continues. |
| Once it has finished reading makefiles, @code{make} will try to remake |
| any that are out of date or don't exist. |
| @xref{Remaking Makefiles, ,How Makefiles Are Remade}. |
| Only after it has tried to find a way to remake a makefile and failed, |
| will @code{make} diagnose the missing makefile as a fatal error. |
| |
| If you want @code{make} to simply ignore a makefile which does not exist |
| or cannot be remade, with no error message, use the @w{@code{-include}} |
| directive instead of @code{include}, like this: |
| |
| @example |
| -include @var{filenames}@dots{} |
| @end example |
| |
| This acts like @code{include} in every way except that there is no |
| error (not even a warning) if any of the @var{filenames} (or any |
| prerequisites of any of the @var{filenames}) do not exist or cannot be |
| remade. |
| |
| For compatibility with some other @code{make} implementations, |
| @code{sinclude} is another name for @w{@code{-include}}. |
| |
| @node MAKEFILES Variable, Remaking Makefiles, Include, Makefiles |
| @section The Variable @code{MAKEFILES} |
| @cindex makefile, and @code{MAKEFILES} variable |
| @cindex including (@code{MAKEFILES} variable) |
| |
| @vindex MAKEFILES |
| If the environment variable @code{MAKEFILES} is defined, @code{make} |
| considers its value as a list of names (separated by whitespace) of |
| additional makefiles to be read before the others. This works much |
| like the @code{include} directive: various directories are searched |
| for those files (@pxref{Include, ,Including Other Makefiles}). In |
| addition, the default goal is never taken from one of these makefiles |
| (or any makefile included by them) and it is not an error if the files |
| listed in @code{MAKEFILES} are not found.@refill |
| |
| @cindex recursion, and @code{MAKEFILES} variable |
| The main use of @code{MAKEFILES} is in communication between recursive |
| invocations of @code{make} (@pxref{Recursion, ,Recursive Use of |
| @code{make}}). It usually is not desirable to set the environment |
| variable before a top-level invocation of @code{make}, because it is |
| usually better not to mess with a makefile from outside. However, if |
| you are running @code{make} without a specific makefile, a makefile in |
| @code{MAKEFILES} can do useful things to help the built-in implicit |
| rules work better, such as defining search paths (@pxref{Directory Search}). |
| |
| Some users are tempted to set @code{MAKEFILES} in the environment |
| automatically on login, and program makefiles to expect this to be done. |
| This is a very bad idea, because such makefiles will fail to work if run by |
| anyone else. It is much better to write explicit @code{include} directives |
| in the makefiles. @xref{Include, , Including Other Makefiles}. |
| |
| @node Remaking Makefiles, Overriding Makefiles, MAKEFILES Variable, Makefiles |
| @section How Makefiles Are Remade |
| @cindex updating makefiles |
| @cindex remaking makefiles |
| @cindex makefile, remaking of |
| Sometimes makefiles can be remade from other files, such as RCS or SCCS |
| files. If a makefile can be remade from other files, you probably want |
| @code{make} to get an up-to-date version of the makefile to read in. |
| |
| To this end, after reading in all makefiles, @code{make} will consider |
| each as a goal target and attempt to update it. If a makefile has a |
| rule which says how to update it (found either in that very makefile or |
| in another one) or if an implicit rule applies to it (@pxref{Implicit |
| Rules, ,Using Implicit Rules}), it will be updated if necessary. After |
| all makefiles have been checked, if any have actually been changed, |
| @code{make} starts with a clean slate and reads all the makefiles over |
| again. (It will also attempt to update each of them over again, but |
| normally this will not change them again, since they are already up to |
| date.)@refill |
| |
| If you know that one or more of your makefiles cannot be remade and |
| you want to keep @code{make} from performing an implicit rule search |
| on them, perhaps for efficiency reasons, you can use any normal method |
| of preventing implicit rule look-up to do so. For example, you can |
| write an explicit rule with the makefile as the target, and an empty |
| recipe (@pxref{Empty Recipes, ,Using Empty Recipes}). |
| |
| If the makefiles specify a double-colon rule to remake a file with |
| a recipe but no prerequisites, that file will always be remade |
| (@pxref{Double-Colon}). In the case of makefiles, a makefile that has a |
| double-colon rule with a recipe but no prerequisites will be remade every |
| time @code{make} is run, and then again after @code{make} starts over |
| and reads the makefiles in again. This would cause an infinite loop: |
| @code{make} would constantly remake the makefile, and never do anything |
| else. So, to avoid this, @code{make} will @strong{not} attempt to |
| remake makefiles which are specified as targets of a double-colon rule |
| with a recipe but no prerequisites.@refill |
| |
| If you do not specify any makefiles to be read with @samp{-f} or |
| @samp{--file} options, @code{make} will try the default makefile names; |
| @pxref{Makefile Names, ,What Name to Give Your Makefile}. Unlike |
| makefiles explicitly requested with @samp{-f} or @samp{--file} options, |
| @code{make} is not certain that these makefiles should exist. However, |
| if a default makefile does not exist but can be created by running |
| @code{make} rules, you probably want the rules to be run so that the |
| makefile can be used. |
| |
| Therefore, if none of the default makefiles exists, @code{make} will try |
| to make each of them in the same order in which they are searched for |
| (@pxref{Makefile Names, ,What Name to Give Your Makefile}) |
| until it succeeds in making one, or it runs out of names to try. Note |
| that it is not an error if @code{make} cannot find or make any makefile; |
| a makefile is not always necessary.@refill |
| |
| When you use the @samp{-t} or @samp{--touch} option |
| (@pxref{Instead of Execution, ,Instead of Executing Recipes}), |
| you would not want to use an out-of-date makefile to decide which |
| targets to touch. So the @samp{-t} option has no effect on updating |
| makefiles; they are really updated even if @samp{-t} is specified. |
| Likewise, @samp{-q} (or @samp{--question}) and @samp{-n} (or |
| @samp{--just-print}) do not prevent updating of makefiles, because an |
| out-of-date makefile would result in the wrong output for other targets. |
| Thus, @samp{make -f mfile -n foo} will update @file{mfile}, read it in, |
| and then print the recipe to update @file{foo} and its prerequisites |
| without running it. The recipe printed for @file{foo} will be the one |
| specified in the updated contents of @file{mfile}. |
| |
| However, on occasion you might actually wish to prevent updating of even |
| the makefiles. You can do this by specifying the makefiles as goals in |
| the command line as well as specifying them as makefiles. When the |
| makefile name is specified explicitly as a goal, the options @samp{-t} |
| and so on do apply to them. |
| |
| Thus, @samp{make -f mfile -n mfile foo} would read the makefile |
| @file{mfile}, print the recipe needed to update it without actually |
| running it, and then print the recipe needed to update @file{foo} |
| without running that. The recipe for @file{foo} will be the one |
| specified by the existing contents of @file{mfile}. |
| |
| @node Overriding Makefiles, Reading Makefiles, Remaking Makefiles, Makefiles |
| @section Overriding Part of Another Makefile |
| |
| @cindex overriding makefiles |
| @cindex makefile, overriding |
| Sometimes it is useful to have a makefile that is mostly just like |
| another makefile. You can often use the @samp{include} directive to |
| include one in the other, and add more targets or variable definitions. |
| However, it is invalid for two makefiles to give different recipes for |
| the same target. But there is another way. |
| |
| @cindex match-anything rule, used to override |
| In the containing makefile (the one that wants to include the other), |
| you can use a match-anything pattern rule to say that to remake any |
| target that cannot be made from the information in the containing |
| makefile, @code{make} should look in another makefile. |
| @xref{Pattern Rules}, for more information on pattern rules. |
| |
| For example, if you have a makefile called @file{Makefile} that says how |
| to make the target @samp{foo} (and other targets), you can write a |
| makefile called @file{GNUmakefile} that contains: |
| |
| @example |
| foo: |
| frobnicate > foo |
| |
| %: force |
| @@$(MAKE) -f Makefile $@@ |
| force: ; |
| @end example |
| |
| If you say @samp{make foo}, @code{make} will find @file{GNUmakefile}, |
| read it, and see that to make @file{foo}, it needs to run the recipe |
| @samp{frobnicate > foo}. If you say @samp{make bar}, @code{make} will |
| find no way to make @file{bar} in @file{GNUmakefile}, so it will use the |
| recipe from the pattern rule: @samp{make -f Makefile bar}. If |
| @file{Makefile} provides a rule for updating @file{bar}, @code{make} |
| will apply the rule. And likewise for any other target that |
| @file{GNUmakefile} does not say how to make. |
| |
| The way this works is that the pattern rule has a pattern of just |
| @samp{%}, so it matches any target whatever. The rule specifies a |
| prerequisite @file{force}, to guarantee that the recipe will be run even |
| if the target file already exists. We give the @file{force} target an |
| empty recipe to prevent @code{make} from searching for an implicit rule to |
| build it---otherwise it would apply the same match-anything rule to |
| @file{force} itself and create a prerequisite loop! |
| |
| @node Reading Makefiles, Secondary Expansion, Overriding Makefiles, Makefiles |
| @section How @code{make} Reads a Makefile |
| @cindex reading makefiles |
| @cindex makefile, parsing |
| |
| GNU @code{make} does its work in two distinct phases. During the first |
| phase it reads all the makefiles, included makefiles, etc. and |
| internalizes all the variables and their values, implicit and explicit |
| rules, and constructs a dependency graph of all the targets and their |
| prerequisites. During the second phase, @code{make} uses these internal |
| structures to determine what targets will need to be rebuilt and to |
| invoke the rules necessary to do so. |
| |
| It's important to understand this two-phase approach because it has a |
| direct impact on how variable and function expansion happens; this is |
| often a source of some confusion when writing makefiles. Here we will |
| present a summary of the phases in which expansion happens for different |
| constructs within the makefile. We say that expansion is |
| @dfn{immediate} if it happens during the first phase: in this case |
| @code{make} will expand any variables or functions in that section of a |
| construct as the makefile is parsed. We say that expansion is |
| @dfn{deferred} if expansion is not performed immediately. Expansion of |
| a deferred construct is not performed until either the construct appears |
| later in an immediate context, or until the second phase. |
| |
| You may not be familiar with some of these constructs yet. You can |
| reference this section as you become familiar with them, in later |
| chapters. |
| |
| @subheading Variable Assignment |
| @cindex +=, expansion |
| @cindex =, expansion |
| @cindex ?=, expansion |
| @cindex +=, expansion |
| @cindex !=, expansion |
| @cindex define, expansion |
| |
| Variable definitions are parsed as follows: |
| |
| @example |
| @var{immediate} = @var{deferred} |
| @var{immediate} ?= @var{deferred} |
| @var{immediate} := @var{immediate} |
| @var{immediate} ::= @var{immediate} |
| @var{immediate} += @var{deferred} or @var{immediate} |
| @var{immediate} != @var{immediate} |
| |
| define @var{immediate} |
| @var{deferred} |
| endef |
| |
| define @var{immediate} = |
| @var{deferred} |
| endef |
| |
| define @var{immediate} ?= |
| @var{deferred} |
| endef |
| |
| define @var{immediate} := |
| @var{immediate} |
| endef |
| |
| define @var{immediate} ::= |
| @var{immediate} |
| endef |
| |
| define @var{immediate} += |
| @var{deferred} or @var{immediate} |
| endef |
| |
| define @var{immediate} != |
| @var{immediate} |
| endef |
| @end example |
| |
| For the append operator, @samp{+=}, the right-hand side is considered |
| immediate if the variable was previously set as a simple variable |
| (@samp{:=} or @samp{::=}), and deferred otherwise. |
| |
| For the shell assignment operator, @samp{!=}, the right-hand side is |
| evaluated immediately and handed to the shell. The result is stored in the |
| variable named on the left, and that variable becomes a simple variable |
| (and will thus be re-evaluated on each reference). |
| |
| @subheading Conditional Directives |
| @cindex ifdef, expansion |
| @cindex ifeq, expansion |
| @cindex ifndef, expansion |
| @cindex ifneq, expansion |
| |
| Conditional directives are parsed immediately. This means, for |
| example, that automatic variables cannot be used in conditional |
| directives, as automatic variables are not set until the recipe for |
| that rule is invoked. If you need to use automatic variables in a |
| conditional directive you @emph{must} move the condition into the |
| recipe and use shell conditional syntax instead. |
| |
| @subheading Rule Definition |
| @cindex target, expansion |
| @cindex prerequisite, expansion |
| @cindex implicit rule, expansion |
| @cindex pattern rule, expansion |
| @cindex explicit rule, expansion |
| |
| A rule is always expanded the same way, regardless of the form: |
| |
| @example |
| @var{immediate} : @var{immediate} ; @var{deferred} |
| @var{deferred} |
| @end example |
| |
| That is, the target and prerequisite sections are expanded immediately, |
| and the recipe used to construct the target is always deferred. This |
| general rule is true for explicit rules, pattern rules, suffix rules, |
| static pattern rules, and simple prerequisite definitions. |
| |
| @node Secondary Expansion, , Reading Makefiles, Makefiles |
| @section Secondary Expansion |
| @cindex secondary expansion |
| @cindex expansion, secondary |
| |
| @findex .SECONDEXPANSION |
| In the previous section we learned that GNU @code{make} works in two |
| distinct phases: a read-in phase and a target-update phase |
| (@pxref{Reading Makefiles, , How @code{make} Reads a Makefile}). GNU |
| make also has the ability to enable a @emph{second expansion} of the |
| prerequisites (only) for some or all targets defined in the makefile. |
| In order for this second expansion to occur, the special target |
| @code{.SECONDEXPANSION} must be defined before the first prerequisite |
| list that makes use of this feature. |
| |
| If that special target is defined then in between the two phases |
| mentioned above, right at the end of the read-in phase, all the |
| prerequisites of the targets defined after the special target are |
| expanded a @emph{second time}. In most circumstances this secondary |
| expansion will have no effect, since all variable and function |
| references will have been expanded during the initial parsing of the |
| makefiles. In order to take advantage of the secondary expansion |
| phase of the parser, then, it's necessary to @emph{escape} the |
| variable or function reference in the makefile. In this case the |
| first expansion merely un-escapes the reference but doesn't expand it, |
| and expansion is left to the secondary expansion phase. For example, |
| consider this makefile: |
| |
| @example |
| .SECONDEXPANSION: |
| ONEVAR = onefile |
| TWOVAR = twofile |
| myfile: $(ONEVAR) $$(TWOVAR) |
| @end example |
| |
| After the first expansion phase the prerequisites list of the |
| @file{myfile} target will be @code{onefile} and @code{$(TWOVAR)}; the |
| first (unescaped) variable reference to @var{ONEVAR} is expanded, |
| while the second (escaped) variable reference is simply unescaped, |
| without being recognized as a variable reference. Now during the |
| secondary expansion the first word is expanded again but since it |
| contains no variable or function references it remains the value |
| @file{onefile}, while the second word is now a normal reference to the |
| variable @var{TWOVAR}, which is expanded to the value @file{twofile}. |
| The final result is that there are two prerequisites, @file{onefile} |
| and @file{twofile}. |
| |
| Obviously, this is not a very interesting case since the same result |
| could more easily have been achieved simply by having both variables |
| appear, unescaped, in the prerequisites list. One difference becomes |
| apparent if the variables are reset; consider this example: |
| |
| @example |
| .SECONDEXPANSION: |
| AVAR = top |
| onefile: $(AVAR) |
| twofile: $$(AVAR) |
| AVAR = bottom |
| @end example |
| |
| Here the prerequisite of @file{onefile} will be expanded immediately, |
| and resolve to the value @file{top}, while the prerequisite of |
| @file{twofile} will not be full expanded until the secondary expansion |
| and yield a value of @file{bottom}. |
| |
| This is marginally more exciting, but the true power of this feature |
| only becomes apparent when you discover that secondary expansions |
| always take place within the scope of the automatic variables for that |
| target. This means that you can use variables such as @code{$@@}, |
| @code{$*}, etc. during the second expansion and they will have their |
| expected values, just as in the recipe. All you have to do is defer |
| the expansion by escaping the @code{$}. Also, secondary expansion |
| occurs for both explicit and implicit (pattern) rules. Knowing this, |
| the possible uses for this feature increase dramatically. For |
| example: |
| |
| @example |
| .SECONDEXPANSION: |
| main_OBJS := main.o try.o test.o |
| lib_OBJS := lib.o api.o |
| |
| main lib: $$($$@@_OBJS) |
| @end example |
| |
| Here, after the initial expansion the prerequisites of both the |
| @file{main} and @file{lib} targets will be @code{$($@@_OBJS)}. During |
| the secondary expansion, the @code{$@@} variable is set to the name of |
| the target and so the expansion for the @file{main} target will yield |
| @code{$(main_OBJS)}, or @code{main.o try.o test.o}, while the |
| secondary expansion for the @file{lib} target will yield |
| @code{$(lib_OBJS)}, or @code{lib.o api.o}. |
| |
| You can also mix in functions here, as long as they are properly escaped: |
| |
| @example |
| main_SRCS := main.c try.c test.c |
| lib_SRCS := lib.c api.c |
| |
| .SECONDEXPANSION: |
| main lib: $$(patsubst %.c,%.o,$$($$@@_SRCS)) |
| @end example |
| |
| This version allows users to specify source files rather than object |
| files, but gives the same resulting prerequisites list as the previous |
| example. |
| |
| Evaluation of automatic variables during the secondary expansion |
| phase, especially of the target name variable @code{$$@@}, behaves |
| similarly to evaluation within recipes. However, there are some |
| subtle differences and ``corner cases'' which come into play for the |
| different types of rule definitions that @code{make} understands. The |
| subtleties of using the different automatic variables are described |
| below. |
| |
| @subheading Secondary Expansion of Explicit Rules |
| @cindex secondary expansion and explicit rules |
| @cindex explicit rules, secondary expansion of |
| |
| During the secondary expansion of explicit rules, @code{$$@@} and |
| @code{$$%} evaluate, respectively, to the file name of the target and, |
| when the target is an archive member, the target member name. The |
| @code{$$<} variable evaluates to the first prerequisite in the first |
| rule for this target. @code{$$^} and @code{$$+} evaluate to the list |
| of all prerequisites of rules @emph{that have already appeared} for |
| the same target (@code{$$+} with repetitions and @code{$$^} |
| without). The following example will help illustrate these behaviors: |
| |
| @example |
| .SECONDEXPANSION: |
| |
| foo: foo.1 bar.1 $$< $$^ $$+ # line #1 |
| |
| foo: foo.2 bar.2 $$< $$^ $$+ # line #2 |
| |
| foo: foo.3 bar.3 $$< $$^ $$+ # line #3 |
| @end example |
| |
| In the first prerequisite list, all three variables (@code{$$<}, |
| @code{$$^}, and @code{$$+}) expand to the empty string. In the |
| second, they will have values @code{foo.1}, @code{foo.1 bar.1}, and |
| @code{foo.1 bar.1} respectively. In the third they will have values |
| @code{foo.1}, @code{foo.1 bar.1 foo.2 bar.2}, and @code{foo.1 bar.1 |
| foo.2 bar.2 foo.1 foo.1 bar.1 foo.1 bar.1} respectively. |
| |
| Rules undergo secondary expansion in makefile order, except that |
| the rule with the recipe is always evaluated last. |
| |
| The variables @code{$$?} and @code{$$*} are not available and expand |
| to the empty string. |
| |
| @subheading Secondary Expansion of Static Pattern Rules |
| @cindex secondary expansion and static pattern rules |
| @cindex static pattern rules, secondary expansion of |
| |
| Rules for secondary expansion of static pattern rules are identical to |
| those for explicit rules, above, with one exception: for static |
| pattern rules the @code{$$*} variable is set to the pattern stem. As |
| with explicit rules, @code{$$?} is not available and expands to the |
| empty string. |
| |
| @subheading Secondary Expansion of Implicit Rules |
| @cindex secondary expansion and implicit rules |
| @cindex implicit rules, secondary expansion of |
| |
| As @code{make} searches for an implicit rule, it substitutes the stem |
| and then performs secondary expansion for every rule with a matching |
| target pattern. The value of the automatic variables is derived in |
| the same fashion as for static pattern rules. As an example: |
| |
| @example |
| .SECONDEXPANSION: |
| |
| foo: bar |
| |
| foo foz: fo%: bo% |
| |
| %oo: $$< $$^ $$+ $$* |
| @end example |
| |
| When the implicit rule is tried for target @file{foo}, @code{$$<} |
| expands to @file{bar}, @code{$$^} expands to @file{bar boo}, |
| @code{$$+} also expands to @file{bar boo}, and @code{$$*} expands to |
| @file{f}. |
| |
| Note that the directory prefix (D), as described in @ref{Implicit Rule |
| Search, ,Implicit Rule Search Algorithm}, is appended (after |
| expansion) to all the patterns in the prerequisites list. As an |
| example:@refill |
| |
| @example |
| .SECONDEXPANSION: |
| |
| /tmp/foo.o: |
| |
| %.o: $$(addsuffix /%.c,foo bar) foo.h |
| @@echo $^ |
| @end example |
| |
| The prerequisite list printed, after the secondary expansion and |
| directory prefix reconstruction, will be @file{/tmp/foo/foo.c |
| /tmp/bar/foo.c foo.h}. If you are not interested in this |
| reconstruction, you can use @code{$$*} instead of @code{%} in the |
| prerequisites list. |
| |
| @node Rules, Recipes, Makefiles, Top |
| @chapter Writing Rules |
| @cindex writing rules |
| @cindex rule, how to write |
| @cindex target |
| @cindex prerequisite |
| |
| A @dfn{rule} appears in the makefile and says when and how to remake |
| certain files, called the rule's @dfn{targets} (most often only one per rule). |
| It lists the other files that are the @dfn{prerequisites} of the target, and |
| the @dfn{recipe} to use to create or update the target. |
| |
| @cindex default goal |
| @cindex goal, default |
| The order of rules is not significant, except for determining the |
| @dfn{default goal}: the target for @code{make} to consider, if you do |
| not otherwise specify one. The default goal is the target of the first |
| rule in the first makefile. If the first rule has multiple targets, |
| only the first target is taken as the default. There are two |
| exceptions: a target starting with a period is not a default unless it |
| contains one or more slashes, @samp{/}, as well; and, a target that |
| defines a pattern rule has no effect on the default goal. |
| (@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.) |
| |
| Therefore, we usually write the makefile so that the first rule is the |
| one for compiling the entire program or all the programs described by |
| the makefile (often with a target called @samp{all}). |
| @xref{Goals, ,Arguments to Specify the Goals}. |
| |
| @menu |
| * Rule Example:: An example explained. |
| * Rule Syntax:: General syntax explained. |
| * Prerequisite Types:: There are two types of prerequisites. |
| * Wildcards:: Using wildcard characters such as `*'. |
| * Directory Search:: Searching other directories for source files. |
| * Phony Targets:: Using a target that is not a real file's name. |
| * Force Targets:: You can use a target without a recipe |
| or prerequisites to mark other targets |
| as phony. |
| * Empty Targets:: When only the date matters and the |
| files are empty. |
| * Special Targets:: Targets with special built-in meanings. |
| * Multiple Targets:: When to make use of several targets in a rule. |
| * Multiple Rules:: How to use several rules with the same target. |
| * Static Pattern:: Static pattern rules apply to multiple targets |
| and can vary the prerequisites according to |
| the target name. |
| * Double-Colon:: How to use a special kind of rule to allow |
| several independent rules for one target. |
| * Automatic Prerequisites:: How to automatically generate rules giving |
| prerequisites from source files themselves. |
| @end menu |
| |
| @ifnottex |
| @node Rule Example, Rule Syntax, Rules, Rules |
| @section Rule Example |
| |
| Here is an example of a rule: |
| |
| @example |
| foo.o : foo.c defs.h # module for twiddling the frobs |
| cc -c -g foo.c |
| @end example |
| |
| Its target is @file{foo.o} and its prerequisites are @file{foo.c} and |
| @file{defs.h}. It has one command in the recipe: @samp{cc -c -g foo.c}. |
| The recipe starts with a tab to identify it as a recipe. |
| |
| This rule says two things: |
| |
| @itemize @bullet |
| @item |
| How to decide whether @file{foo.o} is out of date: it is out of date |
| if it does not exist, or if either @file{foo.c} or @file{defs.h} is |
| more recent than it. |
| |
| @item |
| How to update the file @file{foo.o}: by running @code{cc} as stated. |
| The recipe does not explicitly mention @file{defs.h}, but we presume |
| that @file{foo.c} includes it, and that that is why @file{defs.h} was |
| added to the prerequisites. |
| @end itemize |
| @end ifnottex |
| |
| @node Rule Syntax, Prerequisite Types, Rule Example, Rules |
| @section Rule Syntax |
| |
| @cindex rule syntax |
| @cindex syntax of rules |
| In general, a rule looks like this: |
| |
| @example |
| @var{targets} : @var{prerequisites} |
| @var{recipe} |
| @dots{} |
| @end example |
| |
| @noindent |
| or like this: |
| |
| @example |
| @var{targets} : @var{prerequisites} ; @var{recipe} |
| @var{recipe} |
| @dots{} |
| @end example |
| |
| @cindex targets |
| @cindex rule targets |
| The @var{targets} are file names, separated by spaces. Wildcard |
| characters may be used (@pxref{Wildcards, ,Using Wildcard Characters |
| in File Names}) and a name of the form @file{@var{a}(@var{m})} |
| represents member @var{m} in archive file @var{a} |
| (@pxref{Archive Members, ,Archive Members as Targets}). |
| Usually there is only one |
| target per rule, but occasionally there is a reason to have more |
| (@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill |
| |
| @cindex recipes |
| @cindex tab character (in commands) |
| The @var{recipe} lines start with a tab character (or the first |
| character in the value of the @code{.RECIPEPREFIX} variable; |
| @pxref{Special Variables}). The first recipe line may appear on the line |
| after the prerequisites, with a tab character, or may appear on the |
| same line, with a semicolon. Either way, the effect is the same. |
| There are other differences in the syntax of recipes. |
| @xref{Recipes, ,Writing Recipes in Rules}. |
| |
| @cindex dollar sign (@code{$}), in rules |
| @cindex @code{$}, in rules |
| @cindex rules, and @code{$} |
| Because dollar signs are used to start @code{make} variable |
| references, if you really want a dollar sign in a target or |
| prerequisite you must write two of them, @samp{$$} (@pxref{Using |
| Variables, ,How to Use Variables}). If you have enabled secondary |
| expansion (@pxref{Secondary Expansion}) and you want a literal dollar |
| sign in the prerequisites list, you must actually write @emph{four} |
| dollar signs (@samp{$$$$}). |
| |
| You may split a long line by inserting a backslash followed by a |
| newline, but this is not required, as @code{make} places no limit on |
| the length of a line in a makefile. |
| |
| A rule tells @code{make} two things: when the targets are out of date, |
| and how to update them when necessary. |
| |
| @cindex prerequisites |
| @cindex rule prerequisites |
| The criterion for being out of date is specified in terms of the |
| @var{prerequisites}, which consist of file names separated by spaces. |
| (Wildcards and archive members (@pxref{Archives}) are allowed here too.) |
| A target is out of date if it does not exist or if it is older than any |
| of the prerequisites (by comparison of last-modification times). The |
| idea is that the contents of the target file are computed based on |
| information in the prerequisites, so if any of the prerequisites changes, |
| the contents of the existing target file are no longer necessarily |
| valid. |
| |
| How to update is specified by a @var{recipe}. This is one or more |
| lines to be executed by the shell (normally @samp{sh}), but with some |
| extra features (@pxref{Recipes, ,Writing Recipes in Rules}). |
| |
| @node Prerequisite Types, Wildcards, Rule Syntax, Rules |
| @comment node-name, next, previous, up |
| @section Types of Prerequisites |
| @cindex prerequisite types |
| @cindex types of prerequisites |
| |
| @cindex prerequisites, normal |
| @cindex normal prerequisites |
| @cindex prerequisites, order-only |
| @cindex order-only prerequisites |
| There are actually two different types of prerequisites understood by |
| GNU @code{make}: normal prerequisites such as described in the |
| previous section, and @dfn{order-only} prerequisites. A normal |
| prerequisite makes two statements: first, it imposes an order in which |
| recipes will be invoked: the recipes for all prerequisites of a target |
| will be completed before the recipe for the target is run. Second, it |
| imposes a dependency relationship: if any prerequisite is newer than |
| the target, then the target is considered out-of-date and must be |
| rebuilt. |
| |
| Normally, this is exactly what you want: if a target's prerequisite is |
| updated, then the target should also be updated. |
| |
| Occasionally, however, you have a situation where you want to impose a |
| specific ordering on the rules to be invoked @emph{without} forcing |
| the target to be updated if one of those rules is executed. In that |
| case, you want to define @dfn{order-only} prerequisites. Order-only |
| prerequisites can be specified by placing a pipe symbol (@code{|}) |
| in the prerequisites list: any prerequisites to the left of the pipe |
| symbol are normal; any prerequisites to the right are order-only: |
| |
| @example |
| @var{targets} : @var{normal-prerequisites} | @var{order-only-prerequisites} |
| @end example |
| |
| The normal prerequisites section may of course be empty. Also, you |
| may still declare multiple lines of prerequisites for the same target: |
| they are appended appropriately (normal prerequisites are appended to |
| the list of normal prerequisites; order-only prerequisites are |
| appended to the list of order-only prerequisites). Note that if you |
| declare the same file to be both a normal and an order-only |
| prerequisite, the normal prerequisite takes precedence (since they |
| have a strict superset of the behavior of an order-only prerequisite). |
| |
| Consider an example where your targets are to be placed in a separate |
| directory, and that directory might not exist before @code{make} is |
| run. In this situation, you want the directory to be created before |
| any targets are placed into it but, because the timestamps on |
| directories change whenever a file is added, removed, or renamed, we |
| certainly don't want to rebuild all the targets whenever the |
| directory's timestamp changes. One way to manage this is with |
| order-only prerequisites: make the directory an order-only |
| prerequisite on all the targets: |
| |
| @example |
| OBJDIR := objdir |
| OBJS := $(addprefix $(OBJDIR)/,foo.o bar.o baz.o) |
| |
| $(OBJDIR)/%.o : %.c |
| $(COMPILE.c) $(OUTPUT_OPTION) $< |
| |
| all: $(OBJS) |
| |
| $(OBJS): | $(OBJDIR) |
| |
| $(OBJDIR): |
| mkdir $(OBJDIR) |
| @end example |
| |
| Now the rule to create the @file{objdir} directory will be run, if |
| needed, before any @samp{.o} is built, but no @samp{.o} will be built |
| because the @file{objdir} directory timestamp changed. |
| |
| @node Wildcards, Directory Search, Prerequisite Types, Rules |
| @section Using Wildcard Characters in File Names |
| @cindex wildcard |
| @cindex file name with wildcards |
| @cindex globbing (wildcards) |
| |
| @cindex @code{*} (wildcard character) |
| @cindex @code{?} (wildcard character) |
| @cindex @code{[@dots{}]} (wildcard characters) |
| A single file name can specify many files using @dfn{wildcard characters}. |
| The wildcard characters in @code{make} are @samp{*}, @samp{?} and |
| @samp{[@dots{}]}, the same as in the Bourne shell. For example, @file{*.c} |
| specifies a list of all the files (in the working directory) whose names |
| end in @samp{.c}.@refill |
| |
| @cindex @code{~} (tilde) |
| @cindex tilde (@code{~}) |
| @cindex home directory |
| The character @samp{~} at the beginning of a file name also has special |
| significance. If alone, or followed by a slash, it represents your home |
| directory. For example @file{~/bin} expands to @file{/home/you/bin}. |
| If the @samp{~} is followed by a word, the string represents the home |
| directory of the user named by that word. For example @file{~john/bin} |
| expands to @file{/home/john/bin}. On systems which don't have a home |
| directory for each user (such as MS-DOS or MS-Windows), this |
| functionality can be simulated by setting the environment variable |
| @var{HOME}.@refill |
| |
| Wildcard expansion is performed by @code{make} automatically in |
| targets and in prerequisites. In recipes, the shell is responsible |
| for wildcard expansion. In other contexts, wildcard expansion happens |
| only if you request it explicitly with the @code{wildcard} function. |
| |
| The special significance of a wildcard character can be turned off by |
| preceding it with a backslash. Thus, @file{foo\*bar} would refer to a |
| specific file whose name consists of @samp{foo}, an asterisk, and |
| @samp{bar}.@refill |
| |
| @menu |
| * Wildcard Examples:: Several examples. |
| * Wildcard Pitfall:: Problems to avoid. |
| * Wildcard Function:: How to cause wildcard expansion where |
| it does not normally take place. |
| @end menu |
| |
| @node Wildcard Examples, Wildcard Pitfall, Wildcards, Wildcards |
| @subsection Wildcard Examples |
| |
| Wildcards can be used in the recipe of a rule, where they are expanded |
| by the shell. For example, here is a rule to delete all the object files: |
| |
| @example |
| @group |
| clean: |
| rm -f *.o |
| @end group |
| @end example |
| @cindex @code{rm} (shell command) |
| |
| Wildcards are also useful in the prerequisites of a rule. With the |
| following rule in the makefile, @samp{make print} will print all the |
| @samp{.c} files that have changed since the last time you printed them: |
| |
| @example |
| print: *.c |
| lpr -p $? |
| touch print |
| @end example |
| |
| @cindex @code{print} target |
| @cindex @code{lpr} (shell command) |
| @cindex @code{touch} (shell command) |
| @noindent |
| This rule uses @file{print} as an empty target file; see @ref{Empty |
| Targets, ,Empty Target Files to Record Events}. (The automatic variable |
| @samp{$?} is used to print only those files that have changed; see |
| @ref{Automatic Variables}.)@refill |
| |
| Wildcard expansion does not happen when you define a variable. Thus, if |
| you write this: |
| |
| @example |
| objects = *.o |
| @end example |
| |
| @noindent |
| then the value of the variable @code{objects} is the actual string |
| @samp{*.o}. However, if you use the value of @code{objects} in a |
| target or prerequisite, wildcard expansion will take place there. If |
| you use the value of @code{objects} in a recipe, the shell may perform |
| wildcard expansion when the recipe runs. To set @code{objects} to the |
| expansion, instead use: |
| |
| @example |
| objects := $(wildcard *.o) |
| @end example |
| |
| @noindent |
| @xref{Wildcard Function}. |
| |
| @node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards |
| @subsection Pitfalls of Using Wildcards |
| @cindex wildcard pitfalls |
| @cindex pitfalls of wildcards |
| @cindex mistakes with wildcards |
| @cindex errors with wildcards |
| @cindex problems with wildcards |
| |
| Now here is an example of a naive way of using wildcard expansion, that |
| does not do what you would intend. Suppose you would like to say that the |
| executable file @file{foo} is made from all the object files in the |
| directory, and you write this: |
| |
| @example |
| objects = *.o |
| |
| foo : $(objects) |
| cc -o foo $(CFLAGS) $(objects) |
| @end example |
| |
| @noindent |
| The value of @code{objects} is the actual string @samp{*.o}. Wildcard |
| expansion happens in the rule for @file{foo}, so that each @emph{existing} |
| @samp{.o} file becomes a prerequisite of @file{foo} and will be recompiled if |
| necessary. |
| |
| But what if you delete all the @samp{.o} files? When a wildcard matches |
| no files, it is left as it is, so then @file{foo} will depend on the |
| oddly-named file @file{*.o}. Since no such file is likely to exist, |
| @code{make} will give you an error saying it cannot figure out how to |
| make @file{*.o}. This is not what you want! |
| |
| Actually it is possible to obtain the desired result with wildcard |
| expansion, but you need more sophisticated techniques, including the |
| @code{wildcard} function and string substitution. |
| @ifnottex |
| @xref{Wildcard Function, ,The Function @code{wildcard}}. |
| @end ifnottex |
| @iftex |
| These are described in the following section. |
| @end iftex |
| |
| @cindex wildcards and MS-DOS/MS-Windows backslashes |
| @cindex backslashes in pathnames and wildcard expansion |
| |
| Microsoft operating systems (MS-DOS and MS-Windows) use backslashes to |
| separate directories in pathnames, like so: |
| |
| @example |
| c:\foo\bar\baz.c |
| @end example |
| |
| This is equivalent to the Unix-style @file{c:/foo/bar/baz.c} (the |
| @file{c:} part is the so-called drive letter). When @code{make} runs on |
| these systems, it supports backslashes as well as the Unix-style forward |
| slashes in pathnames. However, this support does @emph{not} include the |
| wildcard expansion, where backslash is a quote character. Therefore, |
| you @emph{must} use Unix-style slashes in these cases. |
| |
| |
| @node Wildcard Function, , Wildcard Pitfall, Wildcards |
| @subsection The Function @code{wildcard} |
| @findex wildcard |
| |
| Wildcard expansion happens automatically in rules. But wildcard expansion |
| does not normally take place when a variable is set, or inside the |
| arguments of a function. If you want to do wildcard expansion in such |
| places, you need to use the @code{wildcard} function, like this: |
| |
| @example |
| $(wildcard @var{pattern}@dots{}) |
| @end example |
| |
| @noindent |
| This string, used anywhere in a makefile, is replaced by a |
| space-separated list of names of existing files that match one of the |
| given file name patterns. If no existing file name matches a pattern, |
| then that pattern is omitted from the output of the @code{wildcard} |
| function. Note that this is different from how unmatched wildcards |
| behave in rules, where they are used verbatim rather than ignored |
| (@pxref{Wildcard Pitfall}). |
| |
| One use of the @code{wildcard} function is to get a list of all the C source |
| files in a directory, like this: |
| |
| @example |
| $(wildcard *.c) |
| @end example |
| |
| We can change the list of C source files into a list of object files by |
| replacing the @samp{.c} suffix with @samp{.o} in the result, like this: |
| |
| @example |
| $(patsubst %.c,%.o,$(wildcard *.c)) |
| @end example |
| |
| @noindent |
| (Here we have used another function, @code{patsubst}. |
| @xref{Text Functions, ,Functions for String Substitution and Analysis}.)@refill |
| |
| Thus, a makefile to compile all C source files in the directory and then |
| link them together could be written as follows: |
| |
| @example |
| objects := $(patsubst %.c,%.o,$(wildcard *.c)) |
| |
| foo : $(objects) |
| cc -o foo $(objects) |
| @end example |
| |
| @noindent |
| (This takes advantage of the implicit rule for compiling C programs, so |
| there is no need to write explicit rules for compiling the files. |
| @xref{Flavors, ,The Two Flavors of Variables}, for an explanation of |
| @samp{:=}, which is a variant of @samp{=}.) |
| |
| @node Directory Search, Phony Targets, Wildcards, Rules |
| @section Searching Directories for Prerequisites |
| @vindex VPATH |
| @findex vpath |
| @cindex vpath |
| @cindex search path for prerequisites (@code{VPATH}) |
| @cindex directory search (@code{VPATH}) |
| |
| For large systems, it is often desirable to put sources in a separate |
| directory from the binaries. The @dfn{directory search} features of |
| @code{make} facilitate this by searching several directories |
| automatically to find a prerequisite. When you redistribute the files |
| among directories, you do not need to change the individual rules, |
| just the search paths. |
| |
| @menu |
| * General Search:: Specifying a search path that applies |
| to every prerequisite. |
| * Selective Search:: Specifying a search path |
| for a specified class of names. |
| * Search Algorithm:: When and how search paths are applied. |
| * Recipes/Search:: How to write recipes that work together |
| with search paths. |
| * Implicit/Search:: How search paths affect implicit rules. |
| * Libraries/Search:: Directory search for link libraries. |
| @end menu |
| |
| @node General Search, Selective Search, Directory Search, Directory Search |
| @subsection @code{VPATH}: Search Path for All Prerequisites |
| @vindex VPATH |
| |
| The value of the @code{make} variable @code{VPATH} specifies a list of |
| directories that @code{make} should search. Most often, the |
| directories are expected to contain prerequisite files that are not in the |
| current directory; however, @code{make} uses @code{VPATH} as a search |
| list for both prerequisites and targets of rules. |
| |
| Thus, if a file that is listed as a target or prerequisite does not exist |
| in the current directory, @code{make} searches the directories listed in |
| @code{VPATH} for a file with that name. If a file is found in one of |
| them, that file may become the prerequisite (see below). Rules may then |
| specify the names of files in the prerequisite list as if they all |
| existed in the current directory. @xref{Recipes/Search, ,Writing Recipes with Directory Search}. |
| |
| In the @code{VPATH} variable, directory names are separated by colons or |
| blanks. The order in which directories are listed is the order followed |
| by @code{make} in its search. (On MS-DOS and MS-Windows, semi-colons |
| are used as separators of directory names in @code{VPATH}, since the |
| colon can be used in the pathname itself, after the drive letter.) |
| |
| For example, |
| |
| @example |
| VPATH = src:../headers |
| @end example |
| |
| @noindent |
| specifies a path containing two directories, @file{src} and |
| @file{../headers}, which @code{make} searches in that order. |
| |
| With this value of @code{VPATH}, the following rule, |
| |
| @example |
| foo.o : foo.c |
| @end example |
| |
| @noindent |
| is interpreted as if it were written like this: |
| |
| @example |
| foo.o : src/foo.c |
| @end example |
| |
| @noindent |
| assuming the file @file{foo.c} does not exist in the current directory but |
| is found in the directory @file{src}. |
| |
| @node Selective Search, Search Algorithm, General Search, Directory Search |
| @subsection The @code{vpath} Directive |
| @findex vpath |
| |
| Similar to the @code{VPATH} variable, but more selective, is the |
| @code{vpath} directive (note lower case), which allows you to specify a |
| search path for a particular class of file names: those that match a |
| particular pattern. Thus you can supply certain search directories for |
| one class of file names and other directories (or none) for other file |
| names. |
| |
| There are three forms of the @code{vpath} directive: |
| |
| @table @code |
| @item vpath @var{pattern} @var{directories} |
| Specify the search path @var{directories} for file names that match |
| @var{pattern}. |
| |
| The search path, @var{directories}, is a list of directories to be |
| searched, separated by colons (semi-colons on MS-DOS and MS-Windows) or |
| blanks, just like the search path used in the @code{VPATH} variable. |
| |
| @item vpath @var{pattern} |
| Clear out the search path associated with @var{pattern}. |
| |
| @c Extra blank line makes sure this gets two lines. |
| @item vpath |
| |
| Clear all search paths previously specified with @code{vpath} directives. |
| @end table |
| |
| A @code{vpath} pattern is a string containing a @samp{%} character. The |
| string must match the file name of a prerequisite that is being searched |
| for, the @samp{%} character matching any sequence of zero or more |
| characters (as in pattern rules; @pxref{Pattern Rules, ,Defining and |
| Redefining Pattern Rules}). For example, @code{%.h} matches files that |
| end in @code{.h}. (If there is no @samp{%}, the pattern must match the |
| prerequisite exactly, which is not useful very often.) |
| |
| @cindex @code{%}, quoting in @code{vpath} |
| @cindex @code{%}, quoting with @code{\} (backslash) |
| @cindex @code{\} (backslash), to quote @code{%} |
| @cindex backslash (@code{\}), to quote @code{%} |
| @cindex quoting @code{%}, in @code{vpath} |
| @samp{%} characters in a @code{vpath} directive's pattern can be quoted |
| with preceding backslashes (@samp{\}). Backslashes that would otherwise |
| quote @samp{%} characters can be quoted with more backslashes. |
| Backslashes that quote @samp{%} characters or other backslashes are |
| removed from the pattern before it is compared to file names. Backslashes |
| that are not in danger of quoting @samp{%} characters go unmolested.@refill |
| |
| When a prerequisite fails to exist in the current directory, if the |
| @var{pattern} in a @code{vpath} directive matches the name of the |
| prerequisite file, then the @var{directories} in that directive are searched |
| just like (and before) the directories in the @code{VPATH} variable. |
| |
| For example, |
| |
| @example |
| vpath %.h ../headers |
| @end example |
| |
| @noindent |
| tells @code{make} to look for any prerequisite whose name ends in @file{.h} |
| in the directory @file{../headers} if the file is not found in the current |
| directory. |
| |
| If several @code{vpath} patterns match the prerequisite file's name, then |
| @code{make} processes each matching @code{vpath} directive one by one, |
| searching all the directories mentioned in each directive. @code{make} |
| handles multiple @code{vpath} directives in the order in which they |
| appear in the makefile; multiple directives with the same pattern are |
| independent of each other. |
| |
| @need 750 |
| Thus, |
| |
| @example |
| @group |
| vpath %.c foo |
| vpath % blish |
| vpath %.c bar |
| @end group |
| @end example |
| |
| @noindent |
| will look for a file ending in @samp{.c} in @file{foo}, then |
| @file{blish}, then @file{bar}, while |
| |
| @example |
| @group |
| vpath %.c foo:bar |
| vpath % blish |
| @end group |
| @end example |
| |
| @noindent |
| will look for a file ending in @samp{.c} in @file{foo}, then |
| @file{bar}, then @file{blish}. |
| |
| @node Search Algorithm, Recipes/Search, Selective Search, Directory Search |
| @subsection How Directory Searches are Performed |
| @cindex algorithm for directory search |
| @cindex directory search algorithm |
| |
| When a prerequisite is found through directory search, regardless of type |
| (general or selective), the pathname located may not be the one that |
| @code{make} actually provides you in the prerequisite list. Sometimes |
| the path discovered through directory search is thrown away. |
| |
| The algorithm @code{make} uses to decide whether to keep or abandon a |
| path found via directory search is as follows: |
| |
| @enumerate |
| @item |
| If a target file does not exist at the path specified in the makefile, |
| directory search is performed. |
| |
| @item |
| If the directory search is successful, that path is kept and this file |
| is tentatively stored as the target. |
| |
| @item |
| All prerequisites of this target are examined using this same method. |
| |
| @item |
| After processing the prerequisites, the target may or may not need to be |
| rebuilt: |
| |
| @enumerate a |
| @item |
| If the target does @emph{not} need to be rebuilt, the path to the file |
| found during directory search is used for any prerequisite lists which |
| contain this target. In short, if @code{make} doesn't need to rebuild |
| the target then you use the path found via directory search. |
| |
| @item |
| If the target @emph{does} need to be rebuilt (is out-of-date), the |
| pathname found during directory search is @emph{thrown away}, and the |
| target is rebuilt using the file name specified in the makefile. In |
| short, if @code{make} must rebuild, then the target is rebuilt locally, |
| not in the directory found via directory search. |
| @end enumerate |
| @end enumerate |
| |
| This algorithm may seem complex, but in practice it is quite often |
| exactly what you want. |
| |
| @cindex traditional directory search (GPATH) |
| @cindex directory search, traditional (GPATH) |
| Other versions of @code{make} use a simpler algorithm: if the file does |
| not exist, and it is found via directory search, then that pathname is |
| always used whether or not the target needs to be built. Thus, if the |
| target is rebuilt it is created at the pathname discovered during |
| directory search. |
| |
| @vindex GPATH |
| If, in fact, this is the behavior you want for some or all of your |
| directories, you can use the @code{GPATH} variable to indicate this to |
| @code{make}. |
| |
| @code{GPATH} has the same syntax and format as @code{VPATH} (that is, a |
| space- or colon-delimited list of pathnames). If an out-of-date target |
| is found by directory search in a directory that also appears in |
| @code{GPATH}, then that pathname is not thrown away. The target is |
| rebuilt using the expanded path. |
| |
| @node Recipes/Search, Implicit/Search, Search Algorithm, Directory Search |
| @subsection Writing Recipes with Directory Search |
| @cindex recipes, and directory search |
| @cindex directory search (@code{VPATH}), and recipes |
| |
| When a prerequisite is found in another directory through directory search, |
| this cannot change the recipe of the rule; they will execute as written. |
| Therefore, you must write the recipe with care so that it will look for |
| the prerequisite in the directory where @code{make} finds it. |
| |
| This is done with the @dfn{automatic variables} such as @samp{$^} |
| (@pxref{Automatic Variables}). |
| For instance, the value of @samp{$^} is a |
| list of all the prerequisites of the rule, including the names of |
| the directories in which they were found, and the value of |
| @samp{$@@} is the target. Thus:@refill |
| |
| @example |
| foo.o : foo.c |
| cc -c $(CFLAGS) $^ -o $@@ |
| @end example |
| |
| @noindent |
| (The variable @code{CFLAGS} exists so you can specify flags for C |
| compilation by implicit rules; we use it here for consistency so it will |
| affect all C compilations uniformly; |
| @pxref{Implicit Variables, ,Variables Used by Implicit Rules}.) |
| |
| Often the prerequisites include header files as well, which you do not |
| want to mention in the recipe. The automatic variable @samp{$<} is |
| just the first prerequisite: |
| |
| @example |
| VPATH = src:../headers |
| foo.o : foo.c defs.h hack.h |
| cc -c $(CFLAGS) $< -o $@@ |
| @end example |
| |
| @node Implicit/Search, Libraries/Search, Recipes/Search, Directory Search |
| @subsection Directory Search and Implicit Rules |
| @cindex @code{VPATH}, and implicit rules |
| @cindex directory search (@code{VPATH}), and implicit rules |
| @cindex search path for prerequisites (@code{VPATH}), and implicit rules |
| @cindex implicit rule, and directory search |
| @cindex implicit rule, and @code{VPATH} |
| @cindex rule, implicit, and directory search |
| @cindex rule, implicit, and @code{VPATH} |
| |
| The search through the directories specified in @code{VPATH} or with |
| @code{vpath} also happens during consideration of implicit rules |
| (@pxref{Implicit Rules, ,Using Implicit Rules}). |
| |
| For example, when a file @file{foo.o} has no explicit rule, @code{make} |
| considers implicit rules, such as the built-in rule to compile |
| @file{foo.c} if that file exists. If such a file is lacking in the |
| current directory, the appropriate directories are searched for it. If |
| @file{foo.c} exists (or is mentioned in the makefile) in any of the |
| directories, the implicit rule for C compilation is applied. |
| |
| The recipes of implicit rules normally use automatic variables as a |
| matter of necessity; consequently they will use the file names found by |
| directory search with no extra effort. |
| |
| @node Libraries/Search, , Implicit/Search, Directory Search |
| @subsection Directory Search for Link Libraries |
| @cindex link libraries, and directory search |
| @cindex libraries for linking, directory search |
| @cindex directory search (@code{VPATH}), and link libraries |
| @cindex @code{VPATH}, and link libraries |
| @cindex search path for prerequisites (@code{VPATH}), and link libraries |
| @cindex @code{-l} (library search) |
| @cindex link libraries, patterns matching |
| @cindex @code{.LIBPATTERNS}, and link libraries |
| @vindex .LIBPATTERNS |
| |
| Directory search applies in a special way to libraries used with the |
| linker. This special feature comes into play when you write a prerequisite |
| whose name is of the form @samp{-l@var{name}}. (You can tell something |
| strange is going on here because the prerequisite is normally the name of a |
| file, and the @emph{file name} of a library generally looks like |
| @file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill |
| |
| When a prerequisite's name has the form @samp{-l@var{name}}, @code{make} |
| handles it specially by searching for the file @file{lib@var{name}.so}, |
| and, if it is not found, for the file @file{lib@var{name}.a} in the current |
| directory, in directories specified by matching @code{vpath} |
| search paths and the @code{VPATH} search path, and then in the |
| directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib} |
| (normally @file{/usr/local/lib}, but MS-DOS/MS-Windows versions of |
| @code{make} behave as if @var{prefix} is defined to be the root of the |
| DJGPP installation tree). |
| |
| For example, if there is a @file{/usr/lib/libcurses.a} library on your |
| system (and no @file{/usr/lib/libcurses.so} file), then |
| |
| @example |
| @group |
| foo : foo.c -lcurses |
| cc $^ -o $@@ |
| @end group |
| @end example |
| |
| @noindent |
| would cause the command @samp{cc foo.c /usr/lib/libcurses.a -o foo} to |
| be executed when @file{foo} is older than @file{foo.c} or than |
| @file{/usr/lib/libcurses.a}.@refill |
| |
| Although the default set of files to be searched for is |
| @file{lib@var{name}.so} and @file{lib@var{name}.a}, this is customizable |
| via the @code{.LIBPATTERNS} variable. Each word in the value of this |
| variable is a pattern string. When a prerequisite like |
| @samp{-l@var{name}} is seen, @code{make} will replace the percent in |
| each pattern in the list with @var{name} and perform the above directory |
| searches using each library file name. |
| |
| The default value for @code{.LIBPATTERNS} is @samp{lib%.so lib%.a}, |
| which provides the default behavior described above. |
| |
| You can turn off link library expansion completely by setting this |
| variable to an empty value. |
| |
| @node Phony Targets, Force Targets, Directory Search, Rules |
| @section Phony Targets |
| @cindex phony targets |
| @cindex targets, phony |
| @cindex targets without a file |
| |
| A phony target is one that is not really the name of a file; rather it |
| is just a name for a recipe to be executed when you make an explicit |
| request. There are two reasons to use a phony target: to avoid a |
| conflict with a file of the same name, and to improve performance. |
| |
| If you write a rule whose recipe will not create the target file, the |
| recipe will be executed every time the target comes up for remaking. |
| Here is an example: |
| |
| @example |
| @group |
| clean: |
| rm *.o temp |
| @end group |
| @end example |
| |
| @noindent |
| Because the @code{rm} command does not create a file named @file{clean}, |
| probably no such file will ever exist. Therefore, the @code{rm} command |
| will be executed every time you say @samp{make clean}. |
| @cindex @code{rm} (shell command) |
| |
| @findex .PHONY |
| In this example, the @file{clean} target will not work properly if a |
| file named @file{clean} is ever created in this directory. Since it |
| has no prerequisites, @file{clean} would always be considered up to |
| date and its recipe would not be executed. To avoid this problem you |
| can explicitly declare the target to be phony by making it a |
| prerequisite of the special target @code{.PHONY} |
| (@pxref{Special Targets, ,Special Built-in Target Names}) as follows: |
| |
| @example |
| @group |
| .PHONY: clean |
| clean: |
| rm *.o temp |
| @end group |
| @end example |
| |
| @noindent |
| Once this is done, @samp{make clean} will run the recipe regardless of |
| whether there is a file named @file{clean}. |
| |
| Phony targets are also useful in conjunction with recursive |
| invocations of @code{make} (@pxref{Recursion, ,Recursive Use of @code{make}}). |
| In this situation the makefile will often contain a variable which |
| lists a number of sub-directories to be built. A simplistic way to |
| handle this is to define one rule with a recipe that loops over the |
| sub-directories, like this: |
| |
| @example |
| @group |
| SUBDIRS = foo bar baz |
| |
| subdirs: |
| for dir in $(SUBDIRS); do \ |
| $(MAKE) -C $$dir; \ |
| done |
| @end group |
| @end example |
| |
| There are problems with this method, however. First, any error |
| detected in a sub-make is ignored by this rule, so it will continue |
| to build the rest of the directories even when one fails. This can be |
| overcome by adding shell commands to note the error and exit, but then |
| it will do so even if @code{make} is invoked with the @code{-k} |
| option, which is unfortunate. Second, and perhaps more importantly, |
| you cannot take advantage of @code{make}'s ability to build targets in |
| parallel (@pxref{Parallel, ,Parallel Execution}), since there is only |
| one rule. |
| |
| By declaring the sub-directories as @code{.PHONY} targets (you must do |
| this as the sub-directory obviously always exists; otherwise it won't |
| be built) you can remove these problems: |
| |
| @example |
| @group |
| SUBDIRS = foo bar baz |
| |
| .PHONY: subdirs $(SUBDIRS) |
| |
| subdirs: $(SUBDIRS) |
| |
| $(SUBDIRS): |
| $(MAKE) -C $@@ |
| |
| foo: baz |
| @end group |
| @end example |
| |
| Here we've also declared that the @file{foo} sub-directory cannot be |
| built until after the @file{baz} sub-directory is complete; this kind of |
| relationship declaration is particularly important when attempting |
| parallel builds. |
| |
| The implicit rule search (@pxref{Implicit Rules}) is skipped for |
| @code{.PHONY} targets. This is why declaring a target as |
| @code{.PHONY} is good for performance, even if you are not worried |
| about the actual file existing. |
| |
| A phony target should not be a prerequisite of a real target file; if it |
| is, its recipe will be run every time @code{make} goes to update that |
| file. As long as a phony target is never a prerequisite of a real |
| target, the phony target recipe will be executed only when the phony |
| target is a specified goal (@pxref{Goals, ,Arguments to Specify the |
| Goals}). |
| |
| Phony targets can have prerequisites. When one directory contains multiple |
| programs, it is most convenient to describe all of the programs in one |
| makefile @file{./Makefile}. Since the target remade by default will be the |
| first one in the makefile, it is common to make this a phony target named |
| @samp{all} and give it, as prerequisites, all the individual programs. For |
| example: |
| |
| @example |
| all : prog1 prog2 prog3 |
| .PHONY : all |
| |
| prog1 : prog1.o utils.o |
| cc -o prog1 prog1.o utils.o |
| |
| prog2 : prog2.o |
| cc -o prog2 prog2.o |
| |
| prog3 : prog3.o sort.o utils.o |
| cc -o prog3 prog3.o sort.o utils.o |
| @end example |
| |
| @noindent |
| Now you can say just @samp{make} to remake all three programs, or |
| specify as arguments the ones to remake (as in @samp{make prog1 |
| prog3}). Phoniness is not inherited: the prerequisites of a phony |
| target are not themselves phony, unless explicitly declared to be so. |
| |
| When one phony target is a prerequisite of another, it serves as a subroutine |
| of the other. For example, here @samp{make cleanall} will delete the |
| object files, the difference files, and the file @file{program}: |
| |
| @example |
| .PHONY: cleanall cleanobj cleandiff |
| |
| cleanall : cleanobj cleandiff |
| rm program |
| |
| cleanobj : |
| rm *.o |
| |
| cleandiff : |
| rm *.diff |
| @end example |
| |
| @node Force Targets, Empty Targets, Phony Targets, Rules |
| @section Rules without Recipes or Prerequisites |
| @cindex force targets |
| @cindex targets, force |
| @cindex @code{FORCE} |
| @cindex rule, no recipe or prerequisites |
| |
| If a rule has no prerequisites or recipe, and the target of the rule |
| is a nonexistent file, then @code{make} imagines this target to have |
| been updated whenever its rule is run. This implies that all targets |
| depending on this one will always have their recipe run. |
| |
| An example will illustrate this: |
| |
| @example |
| @group |
| clean: FORCE |
| rm $(objects) |
| FORCE: |
| @end group |
| @end example |
| |
| Here the target @samp{FORCE} satisfies the special conditions, so the |
| target @file{clean} that depends on it is forced to run its recipe. |
| There is nothing special about the name @samp{FORCE}, but that is one |
| name commonly used this way. |
| |
| As you can see, using @samp{FORCE} this way has the same results as using |
| @samp{.PHONY: clean}. |
| |
| Using @samp{.PHONY} is more explicit and more efficient. However, |
| other versions of @code{make} do not support @samp{.PHONY}; thus |
| @samp{FORCE} appears in many makefiles. @xref{Phony Targets}. |
| |
| @node Empty Targets, Special Targets, Force Targets, Rules |
| @section Empty Target Files to Record Events |
| @cindex empty targets |
| @cindex targets, empty |
| @cindex recording events with empty targets |
| |
| The @dfn{empty target} is a variant of the phony target; it is used to hold |
| recipes for an action that you request explicitly from time to time. |
| Unlike a phony target, this target file can really exist; but the file's |
| contents do not matter, and usually are empty. |
| |
| The purpose of the empty target file is to record, with its |
| last-modification time, when the rule's recipe was last executed. It |
| does so because one of the commands in the recipe is a @code{touch} |
| command to update the target file. |
| |
| The empty target file should have some prerequisites (otherwise it |
| doesn't make sense). When you ask to remake the empty target, the |
| recipe is executed if any prerequisite is more recent than the target; |
| in other words, if a prerequisite has changed since the last time you |
| remade the target. Here is an example: |
| |
| @example |
| print: foo.c bar.c |
| lpr -p $? |
| touch print |
| @end example |
| @cindex @code{print} target |
| @cindex @code{lpr} (shell command) |
| @cindex @code{touch} (shell command) |
| |
| @noindent |
| With this rule, @samp{make print} will execute the @code{lpr} command if |
| either source file has changed since the last @samp{make print}. The |
| automatic variable @samp{$?} is used to print only those files that have |
| changed (@pxref{Automatic Variables}). |
| |
| @node Special Targets, Multiple Targets, Empty Targets, Rules |
| @section Special Built-in Target Names |
| @cindex special targets |
| @cindex built-in special targets |
| @cindex targets, built-in special |
| |
| Certain names have special meanings if they appear as targets. |
| |
| @table @code |
| @findex .PHONY |
| @item .PHONY |
| |
| The prerequisites of the special target @code{.PHONY} are considered to |
| be phony targets. When it is time to consider such a target, |
| @code{make} will run its recipe unconditionally, regardless of |
| whether a file with that name exists or what its last-modification |
| time is. @xref{Phony Targets, ,Phony Targets}. |
| |
| @findex .SUFFIXES |
| @item .SUFFIXES |
| |
| The prerequisites of the special target @code{.SUFFIXES} are the list |
| of suffixes to be used in checking for suffix rules. |
| @xref{Suffix Rules, , Old-Fashioned Suffix Rules}. |
| |
| @findex .DEFAULT |
| @item .DEFAULT |
| |
| The recipe specified for @code{.DEFAULT} is used for any target for |
| which no rules are found (either explicit rules or implicit rules). |
| @xref{Last Resort}. If a @code{.DEFAULT} recipe is specified, every |
| file mentioned as a prerequisite, but not as a target in a rule, will have |
| that recipe executed on its behalf. @xref{Implicit Rule Search, |
| ,Implicit Rule Search Algorithm}. |
| |
| @findex .PRECIOUS |
| @item .PRECIOUS |
| @cindex precious targets |
| @cindex preserving with @code{.PRECIOUS} |
| |
| The targets which @code{.PRECIOUS} depends on are given the following |
| special treatment: if @code{make} is killed or interrupted during the |
| execution of their recipes, the target is not deleted. |
| @xref{Interrupts, ,Interrupting or Killing @code{make}}. Also, if the |
| target is an intermediate file, it will not be deleted after it is no |
| longer needed, as is normally done. @xref{Chained Rules, ,Chains of |
| Implicit Rules}. In this latter respect it overlaps with the |
| @code{.SECONDARY} special target. |
| |
| You can also list the target pattern of an implicit rule (such as |
| @samp{%.o}) as a prerequisite file of the special target @code{.PRECIOUS} |
| to preserve intermediate files created by rules whose target patterns |
| match that file's name. |
| |
| @findex .INTERMEDIATE |
| @item .INTERMEDIATE |
| @cindex intermediate targets, explicit |
| |
| The targets which @code{.INTERMEDIATE} depends on are treated as |
| intermediate files. @xref{Chained Rules, ,Chains of Implicit Rules}. |
| @code{.INTERMEDIATE} with no prerequisites has no effect. |
| |
| @findex .SECONDARY |
| @item .SECONDARY |
| @cindex secondary targets |
| @cindex preserving with @code{.SECONDARY} |
| |
| The targets which @code{.SECONDARY} depends on are treated as |
| intermediate files, except that they are never automatically deleted. |
| @xref{Chained Rules, ,Chains of Implicit Rules}. |
| |
| @code{.SECONDARY} with no prerequisites causes all targets to be treated |
| as secondary (i.e., no target is removed because it is considered |
| intermediate). |
| |
| @findex .SECONDEXPANSION |
| @item .SECONDEXPANSION |
| |
| If @code{.SECONDEXPANSION} is mentioned as a target anywhere in the |
| makefile, then all prerequisite lists defined @emph{after} it appears |
| will be expanded a second time after all makefiles have been read in. |
| @xref{Secondary Expansion, ,Secondary Expansion}. |
| |
| @findex .DELETE_ON_ERROR |
| @item .DELETE_ON_ERROR |
| @cindex removing targets on failure |
| |
| If @code{.DELETE_ON_ERROR} is mentioned as a target anywhere in the |
| makefile, then @code{make} will delete the target of a rule if it has |
| changed and its recipe exits with a nonzero exit status, just as it |
| does when it receives a signal. @xref{Errors, ,Errors in Recipes}. |
| |
| @findex .IGNORE |
| @item .IGNORE |
| |
| If you specify prerequisites for @code{.IGNORE}, then @code{make} will |
| ignore errors in execution of the recipe for those particular files. |
| The recipe for @code{.IGNORE} (if any) is ignored. |
| |
| If mentioned as a target with no prerequisites, @code{.IGNORE} says to |
| ignore errors in execution of recipes for all files. This usage of |
| @samp{.IGNORE} is supported only for historical compatibility. Since |
| this affects every recipe in the makefile, it is not very useful; we |
| recommend you use the more selective ways to ignore errors in specific |
| recipes. @xref{Errors, ,Errors in Recipes}. |
| |
| @findex .LOW_RESOLUTION_TIME |
| @item .LOW_RESOLUTION_TIME |
| |
| If you specify prerequisites for @code{.LOW_RESOLUTION_TIME}, |
| @command{make} assumes that these files are created by commands that |
| generate low resolution time stamps. The recipe for the |
| @code{.LOW_RESOLUTION_TIME} target are ignored. |
| |
| The high resolution file time stamps of many modern file systems |
| lessen the chance of @command{make} incorrectly concluding that a file |
| is up to date. Unfortunately, some hosts do not provide a way to set a |
| high resolution file time stamp, so commands like @samp{cp -p} that |
| explicitly set a file's time stamp must discard its sub-second part. |
| If a file is created by such a command, you should list it as a |
| prerequisite of @code{.LOW_RESOLUTION_TIME} so that @command{make} |
| does not mistakenly conclude that the file is out of date. For |
| example: |
| |
| @example |
| @group |
| .LOW_RESOLUTION_TIME: dst |
| dst: src |
| cp -p src dst |
| @end group |
| @end example |
| |
| Since @samp{cp -p} discards the sub-second part of @file{src}'s time |
| stamp, @file{dst} is typically slightly older than @file{src} even when |
| it is up to date. The @code{.LOW_RESOLUTION_TIME} line causes |
| @command{make} to consider @file{dst} to be up to date if its time stamp |
| is at the start of the same second that @file{src}'s time stamp is in. |
| |
| Due to a limitation of the archive format, archive member time stamps |
| are always low resolution. You need not list archive members as |
| prerequisites of @code{.LOW_RESOLUTION_TIME}, as @command{make} does this |
| automatically. |
| |
| @findex .SILENT |
| @item .SILENT |
| |
| If you specify prerequisites for @code{.SILENT}, then @code{make} will |
| not print the recipe used to remake those particular files before |
| executing them. The recipe for @code{.SILENT} is ignored. |
| |
| If mentioned as a target with no prerequisites, @code{.SILENT} says not |
| to print any recipes before executing them. This usage of |
| @samp{.SILENT} is supported only for historical compatibility. We |
| recommend you use the more selective ways to silence specific recipes. |
| @xref{Echoing, ,Recipe Echoing}. If you want to silence all recipes |
| for a particular run of @code{make}, use the @samp{-s} or |
| @w{@samp{--silent}} option (@pxref{Options Summary}). |
| |
| @findex .EXPORT_ALL_VARIABLES |
| @item .EXPORT_ALL_VARIABLES |
| |
| Simply by being mentioned as a target, this tells @code{make} to |
| export all variables to child processes by default. |
| @xref{Variables/Recursion, ,Communicating Variables to a |
| Sub-@code{make}}. |
| |
| @findex .NOTPARALLEL |
| @item .NOTPARALLEL |
| @cindex parallel execution, overriding |
| |
| If @code{.NOTPARALLEL} is mentioned as a target, then this invocation |
| of @code{make} will be run serially, even if the @samp{-j} option is |
| given. Any recursively invoked @code{make} command will still run |
| recipes in parallel (unless its makefile also contains this target). |
| Any prerequisites on this target are ignored. |
| |
| @findex .ONESHELL |
| @item .ONESHELL |
| @cindex recipe execution, single invocation |
| |
| If @code{.ONESHELL} is mentioned as a target, then when a target is |
| built all lines of the recipe will be given to a single invocation of |
| the shell rather than each line being invoked separately |
| (@pxref{Execution, ,Recipe Execution}). |
| |
| @findex .POSIX |
| @item .POSIX |
| @cindex POSIX-conforming mode, setting |
| |
| If @code{.POSIX} is mentioned as a target, then the makefile will be |
| parsed and run in POSIX-conforming mode. This does @emph{not} mean |
| that only POSIX-conforming makefiles will be accepted: all advanced |
| GNU @code{make} features are still available. Rather, this target |
| causes @code{make} to behave as required by POSIX in those areas |
| where @code{make}'s default behavior differs. |
| |
| In particular, if this target is mentioned then recipes will be |
| invoked as if the shell had been passed the @code{-e} flag: the first |
| failing command in a recipe will cause the recipe to fail immediately. |
| @end table |
| |
| Any defined implicit rule suffix also counts as a special target if it |
| appears as a target, and so does the concatenation of two suffixes, such |
| as @samp{.c.o}. These targets are suffix rules, an obsolete way of |
| defining implicit rules (but a way still widely used). In principle, any |
| target name could be special in this way if you break it in two and add |
| both pieces to the suffix list. In practice, suffixes normally begin with |
| @samp{.}, so these special target names also begin with @samp{.}. |
| @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}. |
| |
| @node Multiple Targets, Multiple Rules, Special Targets, Rules |
| @section Multiple Targets in a Rule |
| @cindex multiple targets |
| @cindex several targets in a rule |
| @cindex targets, multiple |
| @cindex rule, with multiple targets |
| |
| A rule with multiple targets is equivalent to writing many rules, each with |
| one target, and all identical aside from that. The same recipe applies to |
| all the targets, but its effect may vary because you can substitute the |
| actual target name into the recipe using @samp{$@@}. The rule contributes |
| the same prerequisites to all the targets also. |
| |
| This is useful in two cases. |
| |
| @itemize @bullet |
| @item |
| You want just prerequisites, no recipe. For example: |
| |
| @example |
| kbd.o command.o files.o: command.h |
| @end example |
| |
| @noindent |
| gives an additional prerequisite to each of the three object files |
| mentioned. |
| |
| @item |
| Similar recipes work for all the targets. The recipes do not need |
| to be absolutely identical, since the automatic variable @samp{$@@} |
| can be used to substitute the particular target to be remade into the |
| commands (@pxref{Automatic Variables}). For example: |
| |
| @example |
| @group |
| bigoutput littleoutput : text.g |
| generate text.g -$(subst output,,$@@) > $@@ |
| @end group |
| @end example |
| @findex subst |
| |
| @noindent |
| is equivalent to |
| |
| @example |
| bigoutput : text.g |
| generate text.g -big > bigoutput |
| littleoutput : text.g |
| generate text.g -little > littleoutput |
| @end example |
| |
| @noindent |
| Here we assume the hypothetical program @code{generate} makes two |
| types of output, one if given @samp{-big} and one if given |
| @samp{-little}. |
| @xref{Text Functions, ,Functions for String Substitution and Analysis}, |
| for an explanation of the @code{subst} function. |
| @end itemize |
| |
| Suppose you would like to vary the prerequisites according to the |
| target, much as the variable @samp{$@@} allows you to vary the recipe. |
| You cannot do this with multiple targets in an ordinary rule, but you |
| can do it with a @dfn{static pattern rule}. @xref{Static Pattern, |
| ,Static Pattern Rules}. |
| |
| @node Multiple Rules, Static Pattern, Multiple Targets, Rules |
| @section Multiple Rules for One Target |
| @cindex multiple rules for one target |
| @cindex several rules for one target |
| @cindex rule, multiple for one target |
| @cindex target, multiple rules for one |
| |
| One file can be the target of several rules. All the prerequisites |
| mentioned in all the rules are merged into one list of prerequisites for |
| the target. If the target is older than any prerequisite from any rule, |
| the recipe is executed. |
| |
| There can only be one recipe to be executed for a file. If more than |
| one rule gives a recipe for the same file, @code{make} uses the last |
| one given and prints an error message. (As a special case, if the |
| file's name begins with a dot, no error message is printed. This odd |
| behavior is only for compatibility with other implementations of |
| @code{make}@dots{} you should avoid using it). Occasionally it is |
| useful to have the same target invoke multiple recipes which are |
| defined in different parts of your makefile; you can use |
| @dfn{double-colon rules} (@pxref{Double-Colon}) for this. |
| |
| An extra rule with just prerequisites can be used to give a few extra |
| prerequisites to many files at once. For example, makefiles often |
| have a variable, such as @code{objects}, containing a list of all the |
| compiler output files in the system being made. An easy way to say |
| that all of them must be recompiled if @file{config.h} changes is to |
| write the following: |
| |
| @example |
| objects = foo.o bar.o |
| foo.o : defs.h |
| bar.o : defs.h test.h |
| $(objects) : config.h |
| @end example |
| |
| This could be inserted or taken out without changing the rules that really |
| specify how to make the object files, making it a convenient form to use if |
| you wish to add the additional prerequisite intermittently. |
| |
| Another wrinkle is that the additional prerequisites could be |
| specified with a variable that you set with a command line argument to |
| @code{make} (@pxref{Overriding, ,Overriding Variables}). For example, |
| |
| @example |
| @group |
| extradeps= |
| $(objects) : $(extradeps) |
| @end group |
| @end example |
| |
| @noindent |
| means that the command @samp{make extradeps=foo.h} will consider |
| @file{foo.h} as a prerequisite of each object file, but plain @samp{make} |
| will not. |
| |
| If none of the explicit rules for a target has a recipe, then @code{make} |
| searches for an applicable implicit rule to find one |
| @pxref{Implicit Rules, ,Using Implicit Rules}). |
| |
| @node Static Pattern, Double-Colon, Multiple Rules, Rules |
| @section Static Pattern Rules |
| @cindex static pattern rule |
| @cindex rule, static pattern |
| @cindex pattern rules, static (not implicit) |
| @cindex varying prerequisites |
| @cindex prerequisites, varying (static pattern) |
| |
| @dfn{Static pattern rules} are rules which specify multiple targets and |
| construct the prerequisite names for each target based on the target name. |
| They are more general than ordinary rules with multiple targets because the |
| targets do not have to have identical prerequisites. Their prerequisites must |
| be @emph{analogous}, but not necessarily @emph{identical}. |
| |
| @menu |
| * Static Usage:: The syntax of static pattern rules. |
| * Static versus Implicit:: When are they better than implicit rules? |
| @end menu |
| |
| @node Static Usage, Static versus Implicit, Static Pattern, Static Pattern |
| @subsection Syntax of Static Pattern Rules |
| @cindex static pattern rule, syntax of |
| @cindex pattern rules, static, syntax of |
| |
| Here is the syntax of a static pattern rule: |
| |
| @example |
| @var{targets} @dots{}: @var{target-pattern}: @var{prereq-patterns} @dots{} |
| @var{recipe} |
| @dots{} |
| @end example |
| |
| @noindent |
| The @var{targets} list specifies the targets that the rule applies to. |
| The targets can contain wildcard characters, just like the targets of |
| ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File |
| Names}). |
| |
| @cindex target pattern, static (not implicit) |
| @cindex stem |
| The @var{target-pattern} and @var{prereq-patterns} say how to compute the |
| prerequisites of each target. Each target is matched against the |
| @var{target-pattern} to extract a part of the target name, called the |
| @dfn{stem}. This stem is substituted into each of the @var{prereq-patterns} |
| to make the prerequisite names (one from each @var{prereq-pattern}). |
| |
| Each pattern normally contains the character @samp{%} just once. When the |
| @var{target-pattern} matches a target, the @samp{%} can match any part of |
| the target name; this part is called the @dfn{stem}. The rest of the |
| pattern must match exactly. For example, the target @file{foo.o} matches |
| the pattern @samp{%.o}, with @samp{foo} as the stem. The targets |
| @file{foo.c} and @file{foo.out} do not match that pattern.@refill |
| |
| @cindex prerequisite pattern, static (not implicit) |
| The prerequisite names for each target are made by substituting the stem |
| for the @samp{%} in each prerequisite pattern. For example, if one |
| prerequisite pattern is @file{%.c}, then substitution of the stem |
| @samp{foo} gives the prerequisite name @file{foo.c}. It is legitimate |
| to write a prerequisite pattern that does not contain @samp{%}; then this |
| prerequisite is the same for all targets. |
| |
| @cindex @code{%}, quoting in static pattern |
| @cindex @code{%}, quoting with @code{\} (backslash) |
| @cindex @code{\} (backslash), to quote @code{%} |
| @cindex backslash (@code{\}), to quote @code{%} |
| @cindex quoting @code{%}, in static pattern |
| @samp{%} characters in pattern rules can be quoted with preceding |
| backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%} |
| characters can be quoted with more backslashes. Backslashes that quote |
| @samp{%} characters or other backslashes are removed from the pattern |
| before it is compared to file names or has a stem substituted into it. |
| Backslashes that are not in danger of quoting @samp{%} characters go |
| unmolested. For example, the pattern @file{the\%weird\\%pattern\\} has |
| @samp{the%weird\} preceding the operative @samp{%} character, and |
| @samp{pattern\\} following it. The final two backslashes are left alone |
| because they cannot affect any @samp{%} character.@refill |
| |
| Here is an example, which compiles each of @file{foo.o} and @file{bar.o} |
| from the corresponding @file{.c} file: |
| |
| @example |
| @group |
| objects = foo.o bar.o |
| |
| all: $(objects) |
| |
| $(objects): %.o: %.c |
| $(CC) -c $(CFLAGS) $< -o $@@ |
| @end group |
| @end example |
| |
| @noindent |
| Here @samp{$<} is the automatic variable that holds the name of the |
| prerequisite and @samp{$@@} is the automatic variable that holds the name |
| of the target; see @ref{Automatic Variables}. |
| |
| Each target specified must match the target pattern; a warning is issued |
| for each target that does not. If you have a list of files, only some of |
| which will match the pattern, you can use the @code{filter} function to |
| remove non-matching file names (@pxref{Text Functions, ,Functions for String Substitution and Analysis}): |
| |
| @example |
| files = foo.elc bar.o lose.o |
| |
| $(filter %.o,$(files)): %.o: %.c |
| $(CC) -c $(CFLAGS) $< -o $@@ |
| $(filter %.elc,$(files)): %.elc: %.el |
| emacs -f batch-byte-compile $< |
| @end example |
| |
| @noindent |
| In this example the result of @samp{$(filter %.o,$(files))} is |
| @file{bar.o lose.o}, and the first static pattern rule causes each of |
| these object files to be updated by compiling the corresponding C source |
| file. The result of @w{@samp{$(filter %.elc,$(files))}} is |
| @file{foo.elc}, so that file is made from @file{foo.el}.@refill |
| |
| Another example shows how to use @code{$*} in static pattern rules: |
| @vindex $*@r{, and static pattern} |
| |
| @example |
| @group |
| bigoutput littleoutput : %output : text.g |
| generate text.g -$* > $@@ |
| @end group |
| @end example |
| |
| @noindent |
| When the @code{generate} command is run, @code{$*} will expand to the |
| stem, either @samp{big} or @samp{little}. |
| |
| @node Static versus Implicit, , Static Usage, Static Pattern |
| @subsection Static Pattern Rules versus Implicit Rules |
| @cindex rule, static pattern versus implicit |
| @cindex static pattern rule, versus implicit |
| |
| A static pattern rule has much in common with an implicit rule defined as a |
| pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}). |
| Both have a pattern for the target and patterns for constructing the |
| names of prerequisites. The difference is in how @code{make} decides |
| @emph{when} the rule applies. |
| |
| An implicit rule @emph{can} apply to any target that matches its pattern, |
| but it @emph{does} apply only when the target has no recipe otherwise |
| specified, and only when the prerequisites can be found. If more than one |
| implicit rule appears applicable, only one applies; the choice depends on |
| the order of rules. |
| |
| By contrast, a static pattern rule applies to the precise list of targets |
| that you specify in the rule. It cannot apply to any other target and it |
| invariably does apply to each of the targets specified. If two conflicting |
| rules apply, and both have recipes, that's an error. |
| |
| The static pattern rule can be better than an implicit rule for these |
| reasons: |
| |
| @itemize @bullet |
| @item |
| You may wish to override the usual implicit rule for a few |
| files whose names cannot be categorized syntactically but |
| can be given in an explicit list. |
| |
| @item |
| If you cannot be sure of the precise contents of the directories |
| you are using, you may not be sure which other irrelevant files |
| might lead @code{make} to use the wrong implicit rule. The choice |
| might depend on the order in which the implicit rule search is done. |
| With static pattern rules, there is no uncertainty: each rule applies |
| to precisely the targets specified. |
| @end itemize |
| |
| @node Double-Colon, Automatic Prerequisites, Static Pattern, Rules |
| @section Double-Colon Rules |
| @cindex double-colon rules |
| @cindex rule, double-colon (@code{::}) |
| @cindex multiple rules for one target (@code{::}) |
| @cindex @code{::} rules (double-colon) |
| |
| @dfn{Double-colon} rules are explicit rules written with @samp{::} |
| instead of @samp{:} after the target names. They are handled |
| differently from ordinary rules when the same target appears in more |
| than one rule. Pattern rules with double-colons have an entirely |
| different meaning (@pxref{Match-Anything Rules}). |
| |
| When a target appears in multiple rules, all the rules must be the same |
| type: all ordinary, or all double-colon. If they are double-colon, each |
| of them is independent of the others. Each double-colon rule's recipe |
| is executed if the target is older than any prerequisites of that rule. |
| If there are no prerequisites for that rule, its recipe is always |
| executed (even if the target already exists). This can result in |
| executing none, any, or all of the double-colon rules. |
| |
| Double-colon rules with the same target are in fact completely separate |
| from one another. Each double-colon rule is processed individually, just |
| as rules with different targets are processed. |
| |
| The double-colon rules for a target are executed in the order they appear |
| in the makefile. However, the cases where double-colon rules really make |
| sense are those where the order of executing the recipes would not matter. |
| |
| Double-colon rules are somewhat obscure and not often very useful; they |
| provide a mechanism for cases in which the method used to update a target |
| differs depending on which prerequisite files caused the update, and such |
| cases are rare. |
| |
| Each double-colon rule should specify a recipe; if it does not, an |
| implicit rule will be used if one applies. |
| @xref{Implicit Rules, ,Using Implicit Rules}. |
| |
| @node Automatic Prerequisites, , Double-Colon, Rules |
| @section Generating Prerequisites Automatically |
| @cindex prerequisites, automatic generation |
| @cindex automatic generation of prerequisites |
| @cindex generating prerequisites automatically |
| |
| In the makefile for a program, many of the rules you need to write often |
| say only that some object file depends on some header |
| file. For example, if @file{main.c} uses @file{defs.h} via an |
| @code{#include}, you would write: |
| |
| @example |
| main.o: defs.h |
| @end example |
| |
| @noindent |
| You need this rule so that @code{make} knows that it must remake |
| @file{main.o} whenever @file{defs.h} changes. You can see that for a |
| large program you would have to write dozens of such rules in your |
| makefile. And, you must always be very careful to update the makefile |
| every time you add or remove an @code{#include}. |
| @cindex @code{#include} |
| |
| @cindex @code{-M} (to compiler) |
| To avoid this hassle, most modern C compilers can write these rules for |
| you, by looking at the @code{#include} lines in the source files. |
| Usually this is done with the @samp{-M} option to the compiler. |
| For example, the command: |
| |
| @example |
| cc -M main.c |
| @end example |
| |
| @noindent |
| generates the output: |
| |
| @example |
| main.o : main.c defs.h |
| @end example |
| |
| @noindent |
| Thus you no longer have to write all those rules yourself. |
| The compiler will do it for you. |
| |
| Note that such a rule constitutes mentioning @file{main.o} in a |
| makefile, so it can never be considered an intermediate file by |
| implicit rule search. This means that @code{make} won't ever remove |
| the file after using it; @pxref{Chained Rules, ,Chains of Implicit |
| Rules}. |
| |
| @cindex @code{make depend} |
| With old @code{make} programs, it was traditional practice to use this |
| compiler feature to generate prerequisites on demand with a command like |
| @samp{make depend}. That command would create a file @file{depend} |
| containing all the automatically-generated prerequisites; then the |
| makefile could use @code{include} to read them in (@pxref{Include}). |
| |
| In GNU @code{make}, the feature of remaking makefiles makes this |
| practice obsolete---you need never tell @code{make} explicitly to |
| regenerate the prerequisites, because it always regenerates any makefile |
| that is out of date. @xref{Remaking Makefiles}. |
| |
| The practice we recommend for automatic prerequisite generation is to have |
| one makefile corresponding to each source file. For each source file |
| @file{@var{name}.c} there is a makefile @file{@var{name}.d} which lists |
| what files the object file @file{@var{name}.o} depends on. That way |
| only the source files that have changed need to be rescanned to produce |
| the new prerequisites. |
| |
| Here is the pattern rule to generate a file of prerequisites (i.e., a makefile) |
| called @file{@var{name}.d} from a C source file called @file{@var{name}.c}: |
| |
| @smallexample |
| @group |
| %.d: %.c |
| @@set -e; rm -f $@@; \ |
| $(CC) -M $(CPPFLAGS) $< > $@@.$$$$; \ |
| sed 's,\($*\)\.o[ :]*,\1.o $@@ : ,g' < $@@.$$$$ > $@@; \ |
| rm -f $@@.$$$$ |
| @end group |
| @end smallexample |
| |
| @noindent |
| @xref{Pattern Rules}, for information on defining pattern rules. The |
| @samp{-e} flag to the shell causes it to exit immediately if the |
| @code{$(CC)} command (or any other command) fails (exits with a |
| nonzero status). |
| @cindex @code{-e} (shell flag) |
| |
| @cindex @code{-MM} (to GNU compiler) |
| With the GNU C compiler, you may wish to use the @samp{-MM} flag instead |
| of @samp{-M}. This omits prerequisites on system header files. |
| @xref{Preprocessor Options, , Options Controlling the Preprocessor, |
| gcc, Using GNU CC}, for details. |
| |
| @cindex @code{sed} (shell command) |
| The purpose of the @code{sed} command is to translate (for example): |
| |
| @example |
| main.o : main.c defs.h |
| @end example |
| |
| @noindent |
| into: |
| |
| @example |
| main.o main.d : main.c defs.h |
| @end example |
| |
| @noindent |
| @cindex @code{.d} |
| This makes each @samp{.d} file depend on all the source and header files |
| that the corresponding @samp{.o} file depends on. @code{make} then |
| knows it must regenerate the prerequisites whenever any of the source or |
| header files changes. |
| |
| Once you've defined the rule to remake the @samp{.d} files, |
| you then use the @code{include} directive to read them all in. |
| @xref{Include}. For example: |
| |
| @example |
| @group |
| sources = foo.c bar.c |
| |
| include $(sources:.c=.d) |
| @end group |
| @end example |
| |
| @noindent |
| (This example uses a substitution variable reference to translate the |
| list of source files @samp{foo.c bar.c} into a list of prerequisite |
| makefiles, @samp{foo.d bar.d}. @xref{Substitution Refs}, for full |
| information on substitution references.) Since the @samp{.d} files are |
| makefiles like any others, @code{make} will remake them as necessary |
| with no further work from you. @xref{Remaking Makefiles}. |
| |
| Note that the @samp{.d} files contain target definitions; you should |
| be sure to place the @code{include} directive @emph{after} the first, |
| default goal in your makefiles or run the risk of having a random |
| object file become the default goal. |
| @xref{How Make Works}. |
| |
| @node Recipes, Using Variables, Rules, Top |
| @chapter Writing Recipes in Rules |
| @cindex recipes |
| @cindex recipes, how to write |
| @cindex writing recipes |
| |
| The recipe of a rule consists of one or more shell command lines to |
| be executed, one at a time, in the order they appear. Typically, the |
| result of executing these commands is that the target of the rule is |
| brought up to date. |
| |
| Users use many different shell programs, but recipes in makefiles are |
| always interpreted by @file{/bin/sh} unless the makefile specifies |
| otherwise. @xref{Execution, ,Recipe Execution}. |
| |
| @menu |
| * Recipe Syntax:: Recipe syntax features and pitfalls. |
| * Echoing:: How to control when recipes are echoed. |
| * Execution:: How recipes are executed. |
| * Parallel:: How recipes can be executed in parallel. |
| * Errors:: What happens after a recipe execution error. |
| * Interrupts:: What happens when a recipe is interrupted. |
| * Recursion:: Invoking @code{make} from makefiles. |
| * Canned Recipes:: Defining canned recipes. |
| * Empty Recipes:: Defining useful, do-nothing recipes. |
| @end menu |
| |
| @node Recipe Syntax, Echoing, Recipes, Recipes |
| @section Recipe Syntax |
| @cindex recipe syntax |
| @cindex syntax of recipe |
| |
| Makefiles have the unusual property that there are really two distinct |
| syntaxes in one file. Most of the makefile uses @code{make} syntax |
| (@pxref{Makefiles, ,Writing Makefiles}). However, recipes are meant |
| to be interpreted by the shell and so they are written using shell |
| syntax. The @code{make} program does not try to understand shell |
| syntax: it performs only a very few specific translations on the |
| content of the recipe before handing it to the shell. |
| |
| Each line in the recipe must start with a tab (or the first character |
| in the value of the @code{.RECIPEPREFIX} variable; @pxref{Special |
| Variables}), except that the first recipe line may be attached to the |
| target-and-prerequisites line with a semicolon in between. @emph{Any} |
| line in the makefile that begins with a tab and appears in a ``rule |
| context'' (that is, after a rule has been started until another rule |
| or variable definition) will be considered part of a recipe for that |
| rule. Blank lines and lines of just comments may appear among the |
| recipe lines; they are ignored. |
| |
| Some consequences of these rules include: |
| |
| @itemize @bullet |
| @item |
| A blank line that begins with a tab is not blank: it's an empty |
| recipe (@pxref{Empty Recipes}). |
| |
| @cindex comments, in recipes |
| @cindex recipes, comments in |
| @cindex @code{#} (comments), in recipes |
| @item |
| A comment in a recipe is not a @code{make} comment; it will be |
| passed to the shell as-is. Whether the shell treats it as a comment |
| or not depends on your shell. |
| |
| @item |
| A variable definition in a ``rule context'' which is indented by a tab |
| as the first character on the line, will be considered part of a |
| recipe, not a @code{make} variable definition, and passed to the |
| shell. |
| |
| @item |
| A conditional expression (@code{ifdef}, @code{ifeq}, |
| etc. @pxref{Conditional Syntax, ,Syntax of Conditionals}) in a ``rule |
| context'' which is indented by a tab as the first character on the |
| line, will be considered part of a recipe and be passed to the shell. |
| |
| @end itemize |
| |
| @menu |
| * Splitting Recipe Lines:: Breaking long recipe lines for readability. |
| * Variables in Recipes:: Using @code{make} variables in recipes. |
| @end menu |
| |
| @node Splitting Recipe Lines, Variables in Recipes, Recipe Syntax, Recipe Syntax |
| @subsection Splitting Recipe Lines |
| @cindex recipes, splitting |
| @cindex splitting recipes |
| @cindex recipes, backslash (@code{\}) in |
| @cindex recipes, quoting newlines in |
| @cindex backslash (@code{\}), in recipes |
| @cindex @code{\} (backslash), in recipes |
| @cindex quoting newline, in recipes |
| @cindex newline, quoting, in recipes |
| |
| One of the few ways in which @code{make} does interpret recipes is |
| checking for a backslash just before the newline. As in normal |
| makefile syntax, a single logical recipe line can be split into |
| multiple physical lines in the makefile by placing a backslash before |
| each newline. A sequence of lines like this is considered a single |
| recipe line, and one instance of the shell will be invoked to run it. |
| |
| However, in contrast to how they are treated in other places in a |
| makefile (@pxref{Splitting Lines, , Splitting Long Lines}), |
| backslash/newline pairs are @emph{not} removed from the recipe. Both |
| the backslash and the newline characters are preserved and passed to |
| the shell. How the backslash/newline is interpreted depends on your |
| shell. If the first character of the next line after the |
| backslash/newline is the recipe prefix character (a tab by default; |
| @pxref{Special Variables}), then that character (and only that |
| character) is removed. Whitespace is never added to the recipe. |
| |
| For example, the recipe for the all target in this makefile: |
| |
| @example |
| @group |
| all : |
| @@echo no\ |
| space |
| @@echo no\ |
| space |
| @@echo one \ |
| space |
| @@echo one\ |
| space |
| @end group |
| @end example |
| |
| @noindent |
| consists of four separate shell commands where the output is: |
| |
| @example |
| @group |
| nospace |
| nospace |
| one space |
| one space |
| @end group |
| @end example |
| |
| As a more complex example, this makefile: |
| |
| @example |
| @group |
| all : ; @@echo 'hello \ |
| world' ; echo "hello \ |
| world" |
| @end group |
| @end example |
| |
| @noindent |
| will invoke one shell with a command of: |
| |
| @example |
| @group |
| echo 'hello \ |
| world' ; echo "hello \ |
| world" |
| @end group |
| @end example |
| |
| @noindent |
| which, according to shell quoting rules, will yield the following output: |
| |
| @example |
| @group |
| hello \ |
| world |
| hello world |
| @end group |
| @end example |
| |
| @noindent |
| Notice how the backslash/newline pair was removed inside the string |
| quoted with double quotes (@code{"@dots{}"}), but not from the string |
| quoted with single quotes (@code{'@dots{}'}). This is the way the |
| default shell (@file{/bin/sh}) handles backslash/newline pairs. If |
| you specify a different shell in your makefiles it may treat them |
| differently. |
| |
| Sometimes you want to split a long line inside of single quotes, but |
| you don't want the backslash/newline to appear in the quoted content. |
| This is often the case when passing scripts to languages such as Perl,<
|