make

最新推荐文章于 2024-09-14 22:00:00 发布
最新推荐文章于 2024-09-14 22:00:00 发布
阅读量3.1k 收藏 1
点赞数
分类专栏： Linux 文章标签： variables makefile file wildcard command function

GNU `make'

Short Contents

Table of Contents

Next:  ,Previous:  (dir),Up:  (dir)

GNU make

This file documents the GNU make utility, which determinesautomatically which pieces of a large program need to be recompiled,and issues the commands to recompile them.

This is Edition 0.71, last updated 19 July 2010,of The GNU Make Manual, for GNUmake version 3.82.

Copyright © 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007,2008, 2009, 2010 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.2 orany later version published by the Free Software Foundation; with noInvariant Sections, with the Front-Cover Texts being “A GNU Manual,”and with the Back-Cover Texts as in (a) below. A copy of thelicense is included in the section entitled “GNU Free DocumentationLicense.”

(a) The FSF's Back-Cover Text is: “You have the freedom to copy andmodify this GNU manual. Buying copies from the FSF supports it indeveloping GNU and promoting software freedom.”

--- The Detailed Node Listing ---

Overview of make

An Introduction to Makefiles

Writing Makefiles

Writing Rules

Using Wildcard Characters in File Names

Searching Directories for Prerequisites

Static Pattern Rules

Writing Recipes in Rules

Recipe Syntax

Recipe Execution

Recursive Use of make

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.
  • 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

Conditional Parts of Makefiles

Functions for Transforming Text

How to Run 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

Defining and Redefining Pattern Rules

Using make to Update Archive Files

Implicit Rule for Archive Member Targets

Next:  ,Previous:  Top,Up:  Top

1 Overview of make

The make utility automatically determines which pieces of a largeprogram need to be recompiled, and issues commands to recompile them. This manual describes GNUmake, which was implemented by RichardStallman and Roland McGrath. Development since Version 3.76 has beenhandled by Paul D. Smith.

GNU make conforms to section 6.2 of IEEE Standard1003.2-1992 (POSIX.2).Our examples show C programs, since they are most common, but you can usemake with any programming language whose compiler can be run with ashell command. Indeed, make is not limited to programs. You canuse it to describe any task where some files must be updated automaticallyfrom others whenever the others change.

Next:  ,Previous:  Overview,Up:  Overview

Preparing and Running Make

To prepare to use make, you must write a file calledthe makefile that describes the relationships among filesin your program and provides commands for updating each file. In a program, typically, the executable file is updated from objectfiles, which are in turn made by compiling source files.

Once a suitable makefile exists, each time you change some source files,this simple shell command:

     make

suffices to perform all necessary recompilations. The make programuses the makefile data base and the last-modification times of the files todecide which of the files need to be updated. For each of those files, itissues the recipes recorded in the data base.

You can provide command line arguments to make to control whichfiles should be recompiled, or how. SeeHow to Run make.

Next:  ,Previous:  Preparing,Up:  Overview

1.1 How to Read This Manual

If you are new to make, or are looking for a generalintroduction, read the first few sections of each chapter, skipping thelater sections. In each chapter, the first few sections containintroductory or general information and the later sections containspecialized or technical information. The exception is the second chapter,An Introduction to Makefiles, all of which is introductory.

If you are familiar with other make programs, see Features of GNU make, which lists the enhancements GNUmake has, andIncompatibilities and Missing Features, which explains the few things GNUmake lacks thatothers have.

For a quick summary, see Options Summary, Quick Reference,and Special Targets.

Previous:  Reading,Up:  Overview

1.2 Problems and Bugs

If you have problems with GNUmake or think you've found a bug,please report it to the developers; we cannot promise to do anything butwe 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 dowhat you're trying to do. If it's not clear whether you should be ableto do something or not, report that too; it's a bug in thedocumentation!

Before reporting a bug or trying to fix it yourself, try to isolate itto the smallest possible makefile that reproduces the problem. Thensend us the makefile and the exact resultsmake gave you,including any error or warning messages. Please don't paraphrasethese messages: it's best to cut and paste them into your report. When generating this small makefile, be sure to not use any non-freeor unusual tools in your recipes: you can almost always emulate whatsuch a tool would do with simple shell commands. Finally, be sure toexplain what you expected to occur; this will help us decide whetherthe 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:

         bug-make@gnu.org

or use our Web-based project management tool, at:

         http://savannah.gnu.org/projects/make/

In addition to the information above, please be careful to include theversion number ofmake you are using. You can get thisinformation with the command ‘make --version’. Be sure also toinclude the type of machine and operating system you are using. Oneway to obtain this information is by looking at the final lines ofoutput from the command ‘make --help’.

Next:  ,Previous:  Overview,Up:  Top

2 An Introduction to Makefiles

You need a file called a makefile to tell make what to do. Most often, the makefile tellsmake how to compile and link aprogram. In this chapter, we will discuss a simple makefile that describes how tocompile and link a text editor which consists of eight C source filesand three header files. The makefile can also tell make how torun miscellaneous commands when explicitly asked (for example, to removecertain files as a clean-up operation). To see a more complex exampleof a makefile, seeComplex Makefile.

When make recompiles the editor, each changed C source filemust be recompiled. If a header file has changed, each C source filethat includes the header file must be recompiled to be safe. Eachcompilation 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 linkedtogether to produce the new executable editor.

Next:  ,Previous:  Introduction,Up:  Introduction

2.1 What a Rule Looks Like

A simple makefile consists of “rules” with the following shape:

     target ... : prerequisites ...
             recipe
             ...
             ...

A target is usually the name of a file that is generated by aprogram; examples of targets are executable or object files. A targetcan also be the name of an action to carry out, such as ‘clean’(seePhony Targets).

A prerequisite is a file that is used as input to create thetarget. A target often depends on several files.

A recipe is an action that make carries out. A recipemay have more than one command, either on the same line or each on itsown line.Please note: you need to put a tab character atthe beginning of every recipe line! This is an obscurity that catchesthe unwary. If you prefer to prefix your recipes with a characterother than tab, you can set the.RECIPEPREFIX variable to analternate character (see Special Variables).

Usually a recipe is in a rule with prerequisites and serves to create atarget file if any of the prerequisites change. However, the rule thatspecifies a recipe for the target need not have prerequisites. Forexample, the rule containing the delete command associated with thetarget ‘clean’ does not have prerequisites.

A rule, then, explains how and when to remake certain fileswhich are the targets of the particular rule.make carries outthe recipe on the prerequisites to create or update the target. Arule can also explain how and when to carry out an action. SeeWriting Rules.

A makefile may contain other text besides rules, but a simple makefileneed only contain rules. Rules may look somewhat more complicatedthan shown in this template, but all fit the pattern more or less.

Next:  ,Previous:  Rule Introduction,Up:  Introduction

2.2 A Simple Makefile

Here is a straightforward makefile that describes the way anexecutable file callededit depends on eight object fileswhich, in turn, depend on eight C source and three header files.

In this example, all the C files include defs.h, but only thosedefining editing commands includecommand.h, and only lowlevel files that change the editor buffer includebuffer.h.

     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

We split each long line into two lines using backslash-newline; this islike using one long line, but is easier to read.To use this makefile to create the executable file called edit,type:

     make

To use this makefile to delete the executable file and all the objectfiles from the directory, type:

     make clean

In the example makefile, the targets include the executable file‘edit’, and the object files ‘main.o’ and ‘kbd.o’. Theprerequisites are files such as ‘main.c’ and ‘defs.h’. In fact, each ‘.o’ file is both a target and a prerequisite. Recipes include ‘cc -c main.c’ and ‘cc -c kbd.c’.

When a target is a file, it needs to be recompiled or relinked if anyof its prerequisites change. In addition, any prerequisites that arethemselves automatically generated should be updated first. In thisexample,edit depends on each of the eight object files; theobject filemain.o depends on the source file main.c andon the header filedefs.h.

A recipe may follow each line that contains a target andprerequisites. These recipes say how to update the target file. Atab character (or whatever character is specified by the.RECIPEPREFIX variable; seeSpecial Variables) must come atthe beginning of every line in the recipe to distinguish recipes fromother lines in the makefile. (Bear in mind thatmake does notknow anything about how the recipes work. It is up to you to supplyrecipes that will update the target file properly. Allmakedoes is execute the recipe you have specified when the target fileneeds to be updated.)The target ‘clean’ is not a file, but merely the name of anaction. Since you normally do not want to carry out the actions inthis rule, ‘clean’ is not a prerequisite of any other rule. Consequently, make never does anything with it unless you tellit specifically. Note that this rule not only is not a prerequisite,it also does not have any prerequisites, so the only purpose of therule is to run the specified recipe. Targets that do not refer tofiles but are just actions are calledphony targets. See Phony Targets, for information about this kind of target. SeeErrors in Recipes, to see how to cause maketo ignore errors fromrm or any other command.

Next:  ,Previous:  Simple Makefile,Up:  Introduction

2.3 How make Processes a Makefile

By default,make starts with the first target (not targets whosenames start with ‘.’). This is called thedefault goal. (Goals are the targets that make strives ultimately toupdate. You can override this behavior using the command line(seeArguments to Specify the Goals) or with the.DEFAULT_GOAL special variable (seeOther Special Variables). In the simple example of the previous section, the default goal is toupdate the executable programedit; therefore, we put that rulefirst.

Thus, when you give the command:

     make

make reads the makefile in the current directory and begins byprocessing the first rule. In the example, this rule is for relinkingedit; but beforemake can fully process this rule, itmust process the rules for the files thatedit depends on,which in this case are the object files. Each of these files isprocessed according to its own rule. These rules say to update each‘.o’ file by compiling its source file. The recompilation mustbe done if the source file, or any of the header files named asprerequisites, is more recent than the object file, or if the objectfile does not exist.

The other rules are processed because their targets appear asprerequisites of the goal. If some other rule is not depended on by thegoal (or anything it depends on, etc.), that rule is not processed,unless you tellmake to do so (with a command such asmake clean).

Before recompiling an object file, make considers updating itsprerequisites, the source file and header files. This makefile does notspecify anything to be done for them—the ‘.c’ and ‘.h’ filesare not the targets of any rules—so make does nothing for thesefiles. Butmake 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, make decideswhether to relinkedit. This must be done if the fileedit does not exist, or if any of the object files are newer thanit. If an object file was just recompiled, it is now newer thanedit, so edit is relinked. Thus, if we change the file insert.c and runmake,make will compile that file to update insert.o, and thenlinkedit. If we change the file command.h and runmake,make will recompile the object files kbd.o,command.o andfiles.o and then link the file edit.

Next:  ,Previous:  How Make Works,Up:  Introduction

2.4 Variables Make Makefiles Simpler

In our example, we had to list all the object files twice in the rule foredit (repeated here):

     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

Such duplication is error-prone; if a new object file is added to thesystem, we might add it to one list and forget the other. We can eliminatethe risk and simplify the makefile by using a variable.Variablesallow a text string to be defined once and substituted in multiple placeslater (seeHow to Use Variables).

It is standard practice for every makefile to have a variable namedobjects,OBJECTS, objs, OBJS, obj,or OBJ which is a list of all object file names. We woulddefine such a variableobjects with a line like this in themakefile:

     objects = main.o kbd.o command.o display.o \
               insert.o search.o files.o utils.o

Then, each place we want to put a list of the object file names, we cansubstitute the variable's value by writing ‘$(objects)’(seeHow to Use Variables).

Here is how the complete simple makefile looks when you use a variablefor the object files:

     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)

Next:  ,Previous:  Variables Simplify,Up:  Introduction

2.5 Letting make Deduce the Recipes

It is not necessary to spell out the recipes for compiling the individualC source files, because make can figure them out: it has animplicit rule for updating a ‘.o’ file from a correspondinglynamed ‘.c’ file using a ‘cc -c’ command. For example, it willuse the recipe ‘cc -c main.c -o main.o’ to compilemain.c intomain.o. We can therefore omit the recipes from the rules for theobject files. SeeUsing Implicit Rules.

When a ‘.c’ file is used automatically in this way, it is alsoautomatically added to the list of prerequisites. We can therefore omitthe ‘.c’ files from the prerequisites, provided we omit the recipe.

Here is the entire example, with both of these changes, and a variableobjects as suggested above:

     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)

This is how we would write the makefile in actual practice. (Thecomplications associated with ‘clean’ are described elsewhere. SeePhony Targets, and Errors in Recipes.)

Because implicit rules are so convenient, they are important. Youwill see them used frequently.

Next:  ,Previous:  make Deduces,Up:  Introduction

2.6 Another Style of Makefile

When the objects of a makefile are created only by implicit rules, analternative 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:

     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

Here defs.h is given as a prerequisite of all the object files;command.h andbuffer.h are prerequisites of the specificobject files listed for them.

Whether this is better is a matter of taste: it is more compact, but somepeople dislike it because they find it clearer to put all the informationabout each target in one place.

Previous:  Combine By Prerequisite,Up:  Introduction

2.7 Rules for Cleaning the Directory

Compiling a program is not the only thing you might want to write rulesfor. Makefiles commonly tell how to do a few other things besidescompiling a program: for example, how to delete all the object filesand executables so that the directory is ‘clean’.

Here is how wecould write amake rule for cleaning our example editor:

     clean:
             rm edit $(objects)

In practice, we might want to write the rule in a somewhat morecomplicated manner to handle unanticipated situations. We would do this:

     .PHONY : clean
     clean :
             -rm edit $(objects)

This prevents make from getting confused by an actual filecalledclean and causes it to continue in spite of errors fromrm. (SeePhony Targets, and Errors in Recipes.)

A rule such as this should not be placed at the beginning of themakefile, because we do not want it to run by default! Thus, in theexample makefile, we want the rule foredit, which recompilesthe editor, to remain the default goal.

Since clean is not a prerequisite of edit, this rule will notrun at all if we give the command ‘make’ with no arguments. Inorder to make the rule run, we have to type ‘make clean’. See How to Run make.

Next:  ,Previous:  Introduction,Up:  Top

3 Writing Makefiles

The information that tells make how to recompile a system comes fromreading a data base called the makefile.

Next:  ,Previous:  Makefiles,Up:  Makefiles

3.1 What Makefiles Contain

Makefiles contain five kinds of things: explicit rules,implicit rules,variable definitions, directives,and comments. Rules, variables, and directives are described atlength in later chapters.

  • An explicit rule says when and how to remake one or more files,called the rule'stargets. It lists the other files that thetargets depend on, called theprerequisites of the target, andmay also give a recipe to use to create or update the targets. SeeWriting Rules.

  • An implicit rule says when and how to remake a class of filesbased on their names. It describes how a target may depend on a filewith a name similar to the target and gives a recipe to create orupdate such a target. SeeUsing Implicit Rules.

  • A variable definition is a line that specifies a text stringvalue for a variable that can be substituted into the text later. Thesimple makefile example shows a variable definition forobjectsas a list of all object files (see Variables Make Makefiles Simpler).

  • A directive is an instruction for make to do somethingspecial while reading the makefile. These include:

  • ‘#’ in a line of a makefile starts a comment. It and therest of the line are ignored, except that a trailing backslash notescaped by another backslash will continue the comment across multiplelines. A line containing just a comment (with perhaps spaces beforeit) is effectively blank, and is ignored. If you want a literal#, escape it with a backslash (e.g.,\#). Comments mayappear on any line in the makefile, although they are treatedspecially in certain situations.

    You cannot use comments within variable references or function calls:any instance of# will be treated literally (rather than as thestart of a comment) inside a variable reference or function call.

    Comments within a recipe are passed to the shell, just as with anyother recipe text. The shell decides how to interpret it: whether ornot this is a comment is up to the shell.

    Within a define directive, comments are not ignored during thedefinition of the variable, but rather kept intact in the value of thevariable. When the variable is expanded they will either be treatedasmake comments or as recipe text, depending on the context inwhich the variable is evaluated.

Next:  ,Previous:  Makefile Contents,Up:  Makefiles

3.2 What Name to Give Your Makefile

By default, whenmake looks for the makefile, it tries thefollowing names, in order: GNUmakefile, makefileandMakefile. Normally you should call your makefile eithermakefile orMakefile. (We recommendMakefile because it appearsprominently near the beginning of a directory listing, right near otherimportant files such asREADME.) The first name checked,GNUmakefile, is not recommended for most makefiles. You shoulduse this name if you have a makefile that is specific to GNUmake, and will not be understood by other versions ofmake. Other make programs look formakefile andMakefile, but notGNUmakefile.

If make finds none of these names, it does not use any makefile. Then you must specify a goal with a command argument, andmakewill attempt to figure out how to remake it using only its built-inimplicit rules. SeeUsing Implicit Rules.

If you want to use a nonstandard name for your makefile, you can specifythe makefile name with the ‘-f’ or ‘--file’ option. Thearguments ‘-f name’ or ‘--file=name’ tellmake to read the file name as the makefile. If you usemore than one ‘-f’ or ‘--file’ option, you can specify severalmakefiles. All the makefiles are effectively concatenated in the orderspecified. The default makefile names GNUmakefile,makefile andMakefile are not checked automatically if youspecify ‘-f’ or ‘--file’.

Next:  ,Previous:  Makefile Names,Up:  Makefiles

3.3 Including Other Makefiles

Theinclude directive tells make to suspend reading thecurrent makefile and read one or more other makefiles before continuing. The directive is a line in the makefile that looks like this:

     include filenames...

filenames can contain shell file name patterns. Iffilenames is empty, nothing is included and no error is printed.Extra spaces are allowed and ignored at the beginning of the line, butthe first character must not be a tab (or the value of.RECIPEPREFIX)—if the line begins with a tab, it will beconsidered a recipe line. Whitespace is required betweeninclude and the file names, and between file names; extrawhitespace is ignored there and at the end of the directive. Acomment starting with ‘#’ is allowed at the end of the line. Ifthe file names contain any variable or function references, they areexpanded. SeeHow to Use Variables.

For example, if you have three .mk files,a.mk,b.mk, andc.mk, and $(bar) expands tobish bash, then the following expression

     include foo *.mk $(bar)

is equivalent to

     include foo a.mk b.mk c.mk bish bash

When make processes an include directive, it suspendsreading of the containing makefile and reads from each listed file inturn. When that is finished,make resumes reading themakefile in which the directive appears.

One occasion for using include directives is when several programs,handled by individual makefiles in various directories, need to use acommon set of variable definitions(seeSetting Variables) or pattern rules(see Defining and Redefining Pattern Rules).

Another such occasion is when you want to generate prerequisites fromsource files automatically; the prerequisites can be put in a file thatis included by the main makefile. This practice is generally cleanerthan that of somehow appending the prerequisites to the end of the mainmakefile as has been traditionally done with other versions ofmake. SeeAutomatic Prerequisites. If the specified name does not start with a slash, and the file is notfound in the current directory, several other directories are searched. First, any directories you have specified with the ‘-I’ or‘--include-dir’ option are searched(see Summary of Options). Then the following directories (if they exist)are searched, in this order:prefix/include (normally/usr/local/include1)/usr/gnu/include,/usr/local/include,/usr/include.

If an included makefile cannot be found in any of these directories, awarning message is generated, but it is not an immediately fatal error;processing of the makefile containing theinclude continues. Once it has finished reading makefiles, make will try to remakeany that are out of date or don't exist. SeeHow Makefiles Are Remade. Only after it has tried to find a way to remake a makefile and failed,willmake diagnose the missing makefile as a fatal error.

If you want make to simply ignore a makefile which does not existor cannot be remade, with no error message, use the-includedirective instead of include, like this:

     -include filenames...

This acts like include in every way except that there is noerror (not even a warning) if any of thefilenames (or anyprerequisites of any of the filenames) do not exist or cannot beremade.

For compatibility with some other make implementations,sinclude is another name for-include.

Next:  ,Previous:  Include,Up:  Makefiles

3.4 The Variable MAKEFILES

If the environment variableMAKEFILES is defined, makeconsiders its value as a list of names (separated by whitespace) ofadditional makefiles to be read before the others. This works muchlike theinclude directive: various directories are searchedfor those files (seeIncluding Other Makefiles). Inaddition, 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 fileslisted inMAKEFILES are not found.

The main use ofMAKEFILES is in communication between recursiveinvocations of make (see Recursive Use of make). It usually is not desirable to set the environmentvariable before a top-level invocation ofmake, because it isusually better not to mess with a makefile from outside. However, ifyou are runningmake without a specific makefile, a makefile inMAKEFILES can do useful things to help the built-in implicitrules work better, such as defining search paths (seeDirectory Search).

Some users are tempted to set MAKEFILES in the environmentautomatically 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 byanyone else. It is much better to write explicit include directivesin the makefiles. See Including Other Makefiles.

Next:  ,Previous:  MAKEFILES Variable,Up:  Makefiles

3.5 How Makefiles Are Remade

Sometimes makefiles can be remade from other files, such as RCS or SCCSfiles. If a makefile can be remade from other files, you probably wantmake to get an up-to-date version of the makefile to read in.

To this end, after reading in all makefiles, make will considereach as a goal target and attempt to update it. If a makefile has arule which says how to update it (found either in that very makefile orin another one) or if an implicit rule applies to it (see Using Implicit Rules), it will be updated if necessary. Afterall makefiles have been checked, if any have actually been changed,make starts with a clean slate and reads all the makefiles overagain. (It will also attempt to update each of them over again, butnormally this will not change them again, since they are already up todate.)

If you know that one or more of your makefiles cannot be remade andyou want to keepmake from performing an implicit rule searchon them, perhaps for efficiency reasons, you can use any normal methodof preventing implicit rule lookup to do so. For example, you canwrite an explicit rule with the makefile as the target, and an emptyrecipe (see Using Empty Recipes).

If the makefiles specify a double-colon rule to remake a file witha recipe but no prerequisites, that file will always be remade(seeDouble-Colon). In the case of makefiles, a makefile that has adouble-colon rule with a recipe but no prerequisites will be remade everytimemake is run, and then again after make starts overand reads the makefiles in again. This would cause an infinite loop:make would constantly remake the makefile, and never do anythingelse. So, to avoid this,make will not attempt toremake makefiles which are specified as targets of a double-colon rulewith a recipe but no prerequisites.

If you do not specify any makefiles to be read with ‘-f’ or‘--file’ options,make will try the default makefile names;see What Name to Give Your Makefile. Unlikemakefiles explicitly requested with ‘-f’ or ‘--file’ options,make is not certain that these makefiles should exist. However,if a default makefile does not exist but can be created by runningmake rules, you probably want the rules to be run so that themakefile can be used.

Therefore, if none of the default makefiles exists, make will tryto make each of them in the same order in which they are searched for(seeWhat Name to Give Your Makefile)until it succeeds in making one, or it runs out of names to try. Notethat it is not an error ifmake cannot find or make any makefile;a makefile is not always necessary.

When you use the ‘-t’ or ‘--touch’ option(seeInstead of Executing Recipes),you would not want to use an out-of-date makefile to decide whichtargets to touch. So the ‘-t’ option has no effect on updatingmakefiles; they are really updated even if ‘-t’ is specified. Likewise, ‘-q’ (or ‘--question’) and ‘-n’ (or‘--just-print’) do not prevent updating of makefiles, because anout-of-date makefile would result in the wrong output for other targets. Thus, ‘make -f mfile -n foo’ will updatemfile, read it in,and then print the recipe to updatefoo and its prerequisiteswithout running it. The recipe printed forfoo will be the onespecified in the updated contents ofmfile.

However, on occasion you might actually wish to prevent updating of eventhe makefiles. You can do this by specifying the makefiles as goals inthe command line as well as specifying them as makefiles. When themakefile name is specified explicitly as a goal, the options ‘-t’and so on do apply to them.

Thus, ‘make -f mfile -n mfile foo’ would read the makefilemfile, print the recipe needed to update it without actuallyrunning it, and then print the recipe needed to updatefoowithout running that. The recipe for foo will be the onespecified by the existing contents ofmfile.

Next:  ,Previous:  Remaking Makefiles,Up:  Makefiles

3.6 Overriding Part of Another Makefile

Sometimes it is useful to have a makefile that is mostly just likeanother makefile. You can often use the ‘include’ directive toinclude one in the other, and add more targets or variable definitions. However, it is illegal for two makefiles to give different recipes forthe same target. But there is another way.

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 anytarget that cannot be made from the information in the containingmakefile, make should look in another makefile. See Pattern Rules, for more information on pattern rules.

For example, if you have a makefile called Makefile that says howto make the target ‘foo’ (and other targets), you can write amakefile calledGNUmakefile that contains:

     foo:
             frobnicate > foo
     
     %: force
             @$(MAKE) -f Makefile $@
     force: ;

If you say ‘make foo’, make will findGNUmakefile,read it, and see that to make foo, it needs to run the recipe‘frobnicate > foo’. If you say ‘make bar’,make willfind no way to make bar inGNUmakefile, so it will use therecipe from the pattern rule: ‘make -f Makefile bar’. IfMakefile provides a rule for updatingbar, makewill apply the rule. And likewise for any other target thatGNUmakefile does not say how to make.

The way this works is that the pattern rule has a pattern of just‘%’, so it matches any target whatever. The rule specifies aprerequisiteforce, to guarantee that the recipe will be run evenif the target file already exists. We give theforce target anempty recipe to prevent make from searching for an implicit rule tobuild it—otherwise it would apply the same match-anything rule toforce itself and create a prerequisite loop!

Next:  ,Previous:  Overriding Makefiles,Up:  Makefiles

3.7 How make Reads a Makefile

GNUmake does its work in two distinct phases. During the firstphase it reads all the makefiles, included makefiles, etc. andinternalizes all the variables and their values, implicit and explicitrules, and constructs a dependency graph of all the targets and theirprerequisites. During the second phase, make uses these internalstructures to determine what targets will need to be rebuilt and toinvoke the rules necessary to do so.

It's important to understand this two-phase approach because it has adirect impact on how variable and function expansion happens; this isoften a source of some confusion when writing makefiles. Here we willpresent a summary of the phases in which expansion happens for differentconstructs within the makefile. We say that expansion isimmediate if it happens during the first phase: in this casemake will expand any variables or functions in that section of aconstruct as the makefile is parsed. We say that expansion isdeferred if expansion is not performed immediately. Expansion ofa deferred construct is not performed until either the construct appearslater in an immediate context, or until the second phase.

You may not be familiar with some of these constructs yet. You canreference this section as you become familiar with them, in laterchapters.

Variable Assignment

Variable definitions are parsed as follows:

     immediate = deferred
     immediate ?= deferred
     immediate := immediate
     immediate += deferred or immediate
     
     define immediate
       deferred
     endef
     
     define immediate =
       deferred
     endef
     
     define immediate ?=
       deferred
     endef
     
     define immediate :=
       immediate
     endef
     
     define immediate +=
       deferred or immediate
     endef

For the append operator, ‘+=’, the right-hand side is consideredimmediate if the variable was previously set as a simple variable(‘:=’), and deferred otherwise.

Conditional Directives

Conditional directives are parsed immediately. This means, forexample, that automatic variables cannot be used in conditionaldirectives, as automatic variables are not set until the recipe forthat rule is invoked. If you need to use automatic variables in aconditional directive youmust move the condition into therecipe and use shell conditional syntax instead.

Rule Definition

A rule is always expanded the same way, regardless of the form:

     immediate : immediate ; deferred
     	deferred

That is, the target and prerequisite sections are expanded immediately,and the recipe used to construct the target is always deferred. Thisgeneral rule is true for explicit rules, pattern rules, suffix rules,static pattern rules, and simple prerequisite definitions.

Previous:  Reading Makefiles,Up:  Makefiles

3.8 Secondary Expansion

In the previous section we learned that GNUmake works in twodistinct phases: a read-in phase and a target-update phase(seeHow make Reads a Makefile). GNUmake also has the ability to enable asecond expansion of theprerequisites (only) for some or all targets defined in the makefile. In order for this second expansion to occur, the special target.SECONDEXPANSION must be defined before the first prerequisitelist that makes use of this feature.

If that special target is defined then in between the two phasesmentioned above, right at the end of the read-in phase, all theprerequisites of the targets defined after the special target areexpanded asecond time. In most circumstances this secondaryexpansion will have no effect, since all variable and functionreferences will have been expanded during the initial parsing of themakefiles. In order to take advantage of the secondary expansionphase of the parser, then, it's necessary to escape thevariable or function reference in the makefile. In this case thefirst 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:

     .SECONDEXPANSION:
     ONEVAR = onefile
     TWOVAR = twofile
     myfile: $(ONEVAR) $$(TWOVAR)

After the first expansion phase the prerequisites list of themyfile target will beonefile and $(TWOVAR); thefirst (unescaped) variable reference toONEVAR is expanded,while the second (escaped) variable reference is simply unescaped,without being recognized as a variable reference. Now during thesecondary expansion the first word is expanded again but since itcontains no variable or function references it remains the staticvalue onefile, while the second word is now a normal referenceto the variableTWOVAR, which is expanded to the valuetwofile. The final result is that there are two prerequisites,onefile andtwofile.

Obviously, this is not a very interesting case since the same resultcould more easily have been achieved simply by having both variablesappear, unescaped, in the prerequisites list. One difference becomesapparent if the variables are reset; consider this example:

     .SECONDEXPANSION:
     AVAR = top
     onefile: $(AVAR)
     twofile: $$(AVAR)
     AVAR = bottom

Here the prerequisite of onefile will be expanded immediately,and resolve to the valuetop, while the prerequisite oftwofile will not be full expanded until the secondary expansionand yield a value ofbottom.

This is marginally more exciting, but the true power of this featureonly becomes apparent when you discover that secondary expansionsalways take place within the scope of the automatic variables for thattarget. This means that you can use variables such as $@,$*, etc. during the second expansion and they will have theirexpected values, just as in the recipe. All you have to do is deferthe expansion by escaping the$. Also, secondary expansionoccurs for both explicit and implicit (pattern) rules. Knowing this,the possible uses for this feature increase dramatically. Forexample:

     .SECONDEXPANSION:
     main_OBJS := main.o try.o test.o
     lib_OBJS := lib.o api.o
     
     main lib: $$($$@_OBJS)

Here, after the initial expansion the prerequisites of both themain andlib targets will be $($@_OBJS). Duringthe secondary expansion, the$@ variable is set to the name ofthe target and so the expansion for themain target will yield$(main_OBJS), ormain.o try.o test.o, while thesecondary expansion for the lib target will yield$(lib_OBJS), orlib.o api.o.

You can also mix in functions here, as long as they are properly escaped:

     main_SRCS := main.c try.c test.c
     lib_SRCS := lib.c api.c
     
     .SECONDEXPANSION:
     main lib: $$(patsubst %.c,%.o,$$($$@_SRCS))

This version allows users to specify source files rather than objectfiles, but gives the same resulting prerequisites list as the previousexample.

Evaluation of automatic variables during the secondary expansionphase, especially of the target name variable$$@, behavessimilarly to evaluation within recipes. However, there are somesubtle differences and “corner cases” which come into play for thedifferent types of rule definitions thatmake understands. Thesubtleties of using the different automatic variables are describedbelow.

Secondary Expansion of Explicit Rules

During the secondary expansion of explicit rules,$$@ and$$% evaluate, respectively, to the file name of the target and,when the target is an archive member, the target member name. The$$< variable evaluates to the first prerequisite in the firstrule for this target.$$^ and $$+ evaluate to the listof all prerequisites of rulesthat have already appeared forthe same target ($$+ with repetitions and$$^without). The following example will help illustrate these behaviors:

     .SECONDEXPANSION:
     
     foo: foo.1 bar.1 $$< $$^ $$+    # line #1
     
     foo: foo.2 bar.2 $$< $$^ $$+    # line #2
     
     foo: foo.3 bar.3 $$< $$^ $$+    # line #3

In the first prerequisite list, all three variables ($$<,$$^, and$$+) expand to the empty string. In thesecond, they will have valuesfoo.1, foo.1 bar.1, andfoo.1 bar.1 respectively. In the third they will have valuesfoo.1,foo.1 bar.1 foo.2 bar.2, and foo.1 bar.1foo.2 bar.2 foo.1 foo.1 bar.1 foo.1 bar.1 respectively.

Rules undergo secondary expansion in makefile order, except thatthe rule with the recipe is always evaluated last.

The variables $$? and $$* are not available and expandto the empty string.

Secondary Expansion of Static Pattern Rules

Rules for secondary expansion of static pattern rules are identical tothose for explicit rules, above, with one exception: for staticpattern rules the $$* variable is set to the pattern stem. Aswith explicit rules,$$? is not available and expands to theempty string.

Secondary Expansion of Implicit Rules

Asmake searches for an implicit rule, it substitutes the stemand then performs secondary expansion for every rule with a matchingtarget pattern. The value of the automatic variables is derived inthe same fashion as for static pattern rules. As an example:

     .SECONDEXPANSION:
     
     foo: bar
     
     foo foz: fo%: bo%
     
     %oo: $$< $$^ $$+ $$*

When the implicit rule is tried for target foo,$$<expands to bar, $$^ expands tobar boo,$$+ also expands to bar boo, and $$* expands tof.

Note that the directory prefix (D), as described in Implicit Rule Search Algorithm, is appended (afterexpansion) to all the patterns in the prerequisites list. As anexample:

     .SECONDEXPANSION:
     
     /tmp/foo.o:
     
     %.o: $$(addsuffix /%.c,foo bar) foo.h

The prerequisite list after the secondary expansion and directoryprefix reconstruction will be/tmp/foo/foo.c /tmp/var/bar/foo.cfoo.h. If you are not interested in this reconstruction, you can use$$* instead of% in the prerequisites list.

Next:  ,Previous:  Makefiles,Up:  Top

4 Writing Rules

Arule appears in the makefile and says when and how to remakecertain files, called the rule'stargets (most often only one per rule). It lists the other files that are theprerequisites of the target, andthe recipe to use to create or update the target.

The order of rules is not significant, except for determining thedefault goal: the target formake to consider, if you donot otherwise specify one. The default goal is the target of the firstrule in the first makefile. If the first rule has multiple targets,only the first target is taken as the default. There are twoexceptions: a target starting with a period is not a default unless itcontains one or more slashes, ‘/’, as well; and, a target thatdefines a pattern rule has no effect on the default goal. (SeeDefining and Redefining Pattern Rules.)

Therefore, we usually write the makefile so that the first rule is theone for compiling the entire program or all the programs described bythe makefile (often with a target called ‘all’). SeeArguments to Specify the Goals.

Next:  ,Previous:  Rules,Up:  Rules

4.1 Rule Example

Here is an example of a rule:

     foo.o : foo.c defs.h       # module for twiddling the frobs
             cc -c -g foo.c

Its target is foo.o and its prerequisites arefoo.c anddefs.h. It has one command in the recipe: ‘cc -c -g foo.c’. The recipe starts with a tab to identify it as a recipe.

This rule says two things:

  • How to decide whether foo.o is out of date: it is out of dateif it does not exist, or if eitherfoo.c or defs.h ismore recent than it.
  • How to update the file foo.o: by runningcc as stated. The recipe does not explicitly mention defs.h, but we presumethatfoo.c includes it, and that that is why defs.h wasadded to the prerequisites.

Next:  ,Previous:  Rule Example,Up:  Rules

4.2 Rule Syntax

In general, a rule looks like this:

     targets : prerequisites
             recipe
             ...

or like this:

     targets : prerequisites ; recipe
             recipe
             ...

The targets are file names, separated by spaces. Wildcardcharacters may be used (seeUsing Wildcard Characters in File Names) and a name of the forma(m)represents memberm in archive file a(see Archive Members as Targets). Usually there is only onetarget per rule, but occasionally there is a reason to have more(seeMultiple Targets in a Rule).

Therecipe lines start with a tab character (or the firstcharacter in the value of the.RECIPEPREFIX variable;see Special Variables). The first recipe line may appear on the lineafter the prerequisites, with a tab character, or may appear on thesame line, with a semicolon. Either way, the effect is the same. There are other differences in the syntax of recipes. See Writing Recipes in Rules.

Because dollar signs are used to startmake variablereferences, if you really want a dollar sign in a target orprerequisite you must write two of them, ‘$$’ (seeHow to Use Variables). If you have enabled secondaryexpansion (seeSecondary Expansion) and you want a literal dollarsign in the prerequisites list, you must actually writefourdollar signs (‘$$$$’).

You may split a long line by inserting a backslash followed by anewline, but this is not required, asmake places no limit onthe length of a line in a makefile.

A rule tells make two things: when the targets are out of date,and how to update them when necessary.

The criterion for being out of date is specified in terms of theprerequisites, which consist of file names separated by spaces. (Wildcards and archive members (seeArchives) are allowed here too.) A target is out of date if it does not exist or if it is older than anyof the prerequisites (by comparison of last-modification times). Theidea is that the contents of the target file are computed based oninformation in the prerequisites, so if any of the prerequisites changes,the contents of the existing target file are no longer necessarilyvalid.

How to update is specified by a recipe. This is one or morelines to be executed by the shell (normally ‘sh’), but with someextra features (seeWriting Recipes in Rules).

Next:  ,Previous:  Rule Syntax,Up:  Rules

4.3 Types of Prerequisites

There are actually two different types of prerequisites understood byGNU make: normal prerequisites such as described in theprevious section, andorder-only prerequisites. A normalprerequisite makes two statements: first, it imposes an order in whichrecipes will be invoked: the recipes for all prerequisites of a targetwill be completed before the recipe for the target is run. Second, itimposes a dependency relationship: if any prerequisite is newer thanthe target, then the target is considered out-of-date and must berebuilt.

Normally, this is exactly what you want: if a target's prerequisite isupdated, then the target should also be updated.

Occasionally, however, you have a situation where you want to impose aspecific ordering on the rules to be invokedwithout forcingthe target to be updated if one of those rules is executed. In thatcase, you want to defineorder-only prerequisites. Order-onlyprerequisites can be specified by placing a pipe symbol (|)in the prerequisites list: any prerequisites to the left of the pipesymbol are normal; any prerequisites to the right are order-only:

     targets : normal-prerequisites | order-only-prerequisites

The normal prerequisites section may of course be empty. Also, youmay still declare multiple lines of prerequisites for the same target:they are appended appropriately (normal prerequisites are appended tothe list of normal prerequisites; order-only prerequisites areappended to the list of order-only prerequisites). Note that if youdeclare the same file to be both a normal and an order-onlyprerequisite, the normal prerequisite takes precedence (since theyhave a strict superset of the behavior of an order-only prerequisite).

Consider an example where your targets are to be placed in a separatedirectory, and that directory might not exist beforemake isrun. In this situation, you want the directory to be created beforeany targets are placed into it but, because the timestamps ondirectories change whenever a file is added, removed, or renamed, wecertainly don't want to rebuild all the targets whenever thedirectory's timestamp changes. One way to manage this is withorder-only prerequisites: make the directory an order-onlyprerequisite on all the targets:

     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)

Now the rule to create the objdir directory will be run, ifneeded, before any ‘.o’ is built, but no ‘.o’ will be builtbecause theobjdir directory timestamp changed.

Next:  ,Previous:  Prerequisite Types,Up:  Rules

4.4 Using Wildcard Characters in File Names

A single file name can specify many files using wildcard characters. The wildcard characters inmake are ‘*’, ‘?’ and‘[...]’, the same as in the Bourne shell. For example,*.cspecifies a list of all the files (in the working directory) whose namesend in ‘.c’.

The character ‘~’ at the beginning of a file name also has specialsignificance. If alone, or followed by a slash, it represents your homedirectory. For example~/bin expands to /home/you/bin. If the ‘~’ is followed by a word, the string represents the homedirectory of the user named by that word. For example ~john/binexpands to /home/john/bin. On systems which don't have a homedirectory for each user (such as MS-DOS or MS-Windows), thisfunctionality can be simulated by setting the environment variableHOME.

Wildcard expansion is performed by make automatically intargets and in prerequisites. In recipes, the shell is responsiblefor wildcard expansion. In other contexts, wildcard expansion happensonly if you request it explicitly with thewildcard function.

The special significance of a wildcard character can be turned off bypreceding it with a backslash. Thus,foo\*bar would refer to aspecific file whose name consists of ‘foo’, an asterisk, and‘bar’.

Next:  ,Previous:  Wildcards,Up:  Wildcards

4.4.1 Wildcard Examples

Wildcards can be used in the recipe of a rule, where they are expandedby the shell. For example, here is a rule to delete all the object files:

     clean:
             rm -f *.o

Wildcards are also useful in the prerequisites of a rule. With thefollowing rule in the makefile, ‘make print’ will print all the‘.c’ files that have changed since the last time you printed them:

     print: *.c
             lpr -p $?
             touch print

This rule usesprint as an empty target file; see Empty Target Files to Record Events. (The automatic variable‘$?’ is used to print only those files that have changed; seeAutomatic Variables.)

Wildcard expansion does not happen when you define a variable. Thus, ifyou write this:

     objects = *.o

then the value of the variable objects is the actual string‘*.o’. However, if you use the value ofobjects in atarget or prerequisite, wildcard expansion will take place there. Ifyou use the value ofobjects in a recipe, the shell may performwildcard expansion when the recipe runs. To setobjects to theexpansion, instead use:

     objects := $(wildcard *.o)

See Wildcard Function.

Next:  ,Previous:  Wildcard Examples,Up:  Wildcards

4.4.2 Pitfalls of Using Wildcards

Now here is an example of a naive way of using wildcard expansion, thatdoes not do what you would intend. Suppose you would like to say that theexecutable filefoo is made from all the object files in thedirectory, and you write this:

     objects = *.o
     
     foo : $(objects)
             cc -o foo $(CFLAGS) $(objects)

The value of objects is the actual string ‘*.o’. Wildcardexpansion happens in the rule forfoo, so that each existing‘.o’ file becomes a prerequisite offoo and will be recompiled ifnecessary.

But what if you delete all the ‘.o’ files? When a wildcard matchesno files, it is left as it is, so thenfoo will depend on theoddly-named file *.o. Since no such file is likely to exist,make will give you an error saying it cannot figure out how tomake*.o. This is not what you want!

Actually it is possible to obtain the desired result with wildcardexpansion, but you need more sophisticated techniques, including thewildcard function and string substitution. SeeThe Function wildcard.

Microsoft operating systems (MS-DOS and MS-Windows) use backslashes toseparate directories in pathnames, like so:

       c:\foo\bar\baz.c

This is equivalent to the Unix-style c:/foo/bar/baz.c (thec: part is the so-called drive letter). Whenmake runs onthese systems, it supports backslashes as well as the Unix-style forwardslashes in pathnames. However, this support doesnot include thewildcard expansion, where backslash is a quote character. Therefore,youmust use Unix-style slashes in these cases.

Previous:  Wildcard Pitfall,Up:  Wildcards

4.4.3 The Function wildcard

Wildcard expansion happens automatically in rules. But wildcard expansiondoes not normally take place when a variable is set, or inside thearguments of a function. If you want to do wildcard expansion in suchplaces, you need to use the wildcard function, like this:

     $(wildcard pattern...)

This string, used anywhere in a makefile, is replaced by aspace-separated list of names of existing files that match one of thegiven file name patterns. If no existing file name matches a pattern,then that pattern is omitted from the output of the wildcardfunction. Note that this is different from how unmatched wildcardsbehave in rules, where they are used verbatim rather than ignored(seeWildcard Pitfall).

One use of the wildcard function is to get a list of all the C sourcefiles in a directory, like this:

     $(wildcard *.c)

We can change the list of C source files into a list of object files byreplacing the ‘.c’ suffix with ‘.o’ in the result, like this:

     $(patsubst %.c,%.o,$(wildcard *.c))

(Here we have used another function, patsubst. SeeFunctions for String Substitution and Analysis.)

Thus, a makefile to compile all C source files in the directory and thenlink them together could be written as follows:

     objects := $(patsubst %.c,%.o,$(wildcard *.c))
     
     foo : $(objects)
             cc -o foo $(objects)

(This takes advantage of the implicit rule for compiling C programs, sothere is no need to write explicit rules for compiling the files. SeeThe Two Flavors of Variables, for an explanation of‘:=’, which is a variant of ‘=’.)

Next:  ,Previous:  Wildcards,Up:  Rules

4.5 Searching Directories for Prerequisites

For large systems, it is often desirable to put sources in a separatedirectory from the binaries. Thedirectory search features ofmake facilitate this by searching several directoriesautomatically to find a prerequisite. When you redistribute the filesamong directories, you do not need to change the individual rules,just the search paths.

Next:  ,Previous:  Directory Search,Up:  Directory Search

4.5.1 VPATH: Search Path for All Prerequisites

The value of the make variable VPATH specifies a list ofdirectories that make should search. Most often, thedirectories are expected to contain prerequisite files that are not in thecurrent directory; however,make uses VPATH as a searchlist for both prerequisites and targets of rules.

Thus, if a file that is listed as a target or prerequisite does not existin the current directory,make searches the directories listed inVPATH for a file with that name. If a file is found in one ofthem, that file may become the prerequisite (see below). Rules may thenspecify the names of files in the prerequisite list as if they allexisted in the current directory. See Writing Recipes with Directory Search.

In the VPATH variable, directory names are separated by colons orblanks. The order in which directories are listed is the order followedbymake in its search. (On MS-DOS and MS-Windows, semi-colonsare used as separators of directory names inVPATH, since thecolon can be used in the pathname itself, after the drive letter.)

For example,

     VPATH = src:../headers

specifies a path containing two directories, src and../headers, whichmake searches in that order.

With this value of VPATH, the following rule,

     foo.o : foo.c

is interpreted as if it were written like this:

     foo.o : src/foo.c

assuming the file foo.c does not exist in the current directory butis found in the directorysrc.

Next:  ,Previous:  General Search,Up:  Directory Search

4.5.2 The vpath Directive

Similar to the VPATH variable, but more selective, is thevpath directive (note lower case), which allows you to specify asearch path for a particular class of file names: those that match aparticular pattern. Thus you can supply certain search directories forone class of file names and other directories (or none) for other filenames.

There are three forms of the vpath directive:

vpath pattern directories
Specify the search path directories for file names that match pattern.

The search path, directories, is a list of directories to besearched, separated by colons (semi-colons on MS-DOS and MS-Windows) orblanks, just like the search path used in theVPATH variable.

vpath pattern
Clear out the search path associated with pattern.
vpath
Clear all search paths previously specified with vpath directives.

A vpath pattern is a string containing a ‘%’ character. Thestring must match the file name of a prerequisite that is being searchedfor, the ‘%’ character matching any sequence of zero or morecharacters (as in pattern rules; see Defining and Redefining Pattern Rules). For example, %.h matches files thatend in.h. (If there is no ‘%’, the pattern must match theprerequisite exactly, which is not useful very often.)

‘%’ characters in a vpath directive's pattern can be quotedwith preceding backslashes (‘\’). Backslashes that would otherwisequote ‘%’ characters can be quoted with more backslashes. Backslashes that quote ‘%’ characters or other backslashes areremoved from the pattern before it is compared to file names. Backslashesthat are not in danger of quoting ‘%’ characters go unmolested.

When a prerequisite fails to exist in the current directory, if thepattern in avpath directive matches the name of theprerequisite file, then the directories in that directive are searchedjust like (and before) the directories in theVPATH variable.

For example,

     vpath %.h ../headers

tells make to look for any prerequisite whose name ends in.hin the directory ../headers if the file is not found in the currentdirectory.

If several vpath patterns match the prerequisite file's name, thenmake processes each matchingvpath directive one by one,searching all the directories mentioned in each directive.makehandles multiple vpath directives in the order in which theyappear in the makefile; multiple directives with the same pattern areindependent of each other.

Thus,

     vpath %.c foo
     vpath %   blish
     vpath %.c bar

will look for a file ending in ‘.c’ infoo, thenblish, thenbar, while

     vpath %.c foo:bar
     vpath %   blish

will look for a file ending in ‘.c’ infoo, thenbar, thenblish.

Next:  ,Previous:  Selective Search,Up:  Directory Search

4.5.3 How Directory Searches are Performed

When a prerequisite is found through directory search, regardless of type(general or selective), the pathname located may not be the one thatmake actually provides you in the prerequisite list. Sometimesthe path discovered through directory search is thrown away.

The algorithm make uses to decide whether to keep or abandon apath found via directory search is as follows:

  1. If a target file does not exist at the path specified in the makefile,directory search is performed.
  2. If the directory search is successful, that path is kept and this fileis tentatively stored as the target.
  3. All prerequisites of this target are examined using this same method.
  4. After processing the prerequisites, the target may or may not need to berebuilt:
    1. If the target does not need to be rebuilt, the path to the filefound during directory search is used for any prerequisite lists whichcontain this target. In short, ifmake doesn't need to rebuildthe target then you use the path found via directory search.
    2. If the target does need to be rebuilt (is out-of-date), thepathname found during directory search isthrown away, and thetarget is rebuilt using the file name specified in the makefile. Inshort, ifmake must rebuild, then the target is rebuilt locally,not in the directory found via directory search.

This algorithm may seem complex, but in practice it is quite oftenexactly what you want.

Other versions ofmake use a simpler algorithm: if the file doesnot exist, and it is found via directory search, then that pathname isalways used whether or not the target needs to be built. Thus, if thetarget is rebuilt it is created at the pathname discovered duringdirectory search.

If, in fact, this is the behavior you want for some or all of yourdirectories, you can use theGPATH variable to indicate this tomake.

GPATH has the same syntax and format as VPATH (that is, aspace- or colon-delimited list of pathnames). If an out-of-date targetis found by directory search in a directory that also appears inGPATH, then that pathname is not thrown away. The target isrebuilt using the expanded path.

Next:  ,Previous:  Search Algorithm,Up:  Directory Search

4.5.4 Writing Recipes with Directory Search

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 forthe prerequisite in the directory wheremake finds it.

This is done with the automatic variables such as ‘$^’(seeAutomatic Variables). For instance, the value of ‘$^’ is alist of all the prerequisites of the rule, including the names ofthe directories in which they were found, and the value of‘$@’ is the target. Thus:

     foo.o : foo.c
             cc -c $(CFLAGS) $^ -o $@

(The variable CFLAGS exists so you can specify flags for Ccompilation by implicit rules; we use it here for consistency so it willaffect all C compilations uniformly;seeVariables Used by Implicit Rules.)

Often the prerequisites include header files as well, which you do notwant to mention in the recipe. The automatic variable ‘$<’ isjust the first prerequisite:

     VPATH = src:../headers
     foo.o : foo.c defs.h hack.h
             cc -c $(CFLAGS) $< -o $@

Next:  ,Previous:  Recipes/Search,Up:  Directory Search

4.5.5 Directory Search and Implicit Rules

The search through the directories specified in VPATH or withvpath also happens during consideration of implicit rules(seeUsing Implicit Rules).

For example, when a file foo.o has no explicit rule,makeconsiders implicit rules, such as the built-in rule to compilefoo.c if that file exists. If such a file is lacking in thecurrent directory, the appropriate directories are searched for it. Iffoo.c exists (or is mentioned in the makefile) in any of thedirectories, the implicit rule for C compilation is applied.

The recipes of implicit rules normally use automatic variables as amatter of necessity; consequently they will use the file names found bydirectory search with no extra effort.

Previous:  Implicit/Search,Up:  Directory Search

4.5.6 Directory Search for Link Libraries

Directory search applies in a special way to libraries used with thelinker. This special feature comes into play when you write a prerequisitewhose name is of the form ‘-lname’. (You can tell somethingstrange is going on here because the prerequisite is normally the name of afile, and the file name of a library generally looks likelibname.a, not like ‘-lname’.)

When a prerequisite's name has the form ‘-lname’,makehandles it specially by searching for the file libname.so,and, if it is not found, for the filelibname.a in the currentdirectory, in directories specified by matchingvpathsearch paths and the VPATH search path, and then in thedirectories/lib, /usr/lib, andprefix/lib(normally /usr/local/lib, but MS-DOS/MS-Windows versions ofmake behave as ifprefix is defined to be the root of theDJGPP installation tree).

For example, if there is a /usr/lib/libcurses.a library on yoursystem (and no/usr/lib/libcurses.so file), then

     foo : foo.c -lcurses
             cc $^ -o $@

would cause the command ‘cc foo.c /usr/lib/libcurses.a -o foo’ tobe executed whenfoo is older than foo.c or than/usr/lib/libcurses.a.

Although the default set of files to be searched for islibname.so andlibname.a, this is customizablevia the.LIBPATTERNS variable. Each word in the value of thisvariable is a pattern string. When a prerequisite like‘-lname’ is seen,make will replace the percent ineach pattern in the list with name and perform the above directorysearches using each library filename.

The default value for .LIBPATTERNS is ‘lib%.so lib%.a’,which provides the default behavior described above.

You can turn off link library expansion completely by setting thisvariable to an empty value.

Next:  ,Previous:  Directory Search,Up:  Rules

4.6 Phony Targets

A phony target is one that is not really the name of a file; rather itis just a name for a recipe to be executed when you make an explicitrequest. There are two reasons to use a phony target: to avoid aconflict with a file of the same name, and to improve performance.

If you write a rule whose recipe will not create the target file, therecipe will be executed every time the target comes up for remaking. Here is an example:

     clean:
             rm *.o temp

Because the rm command does not create a file namedclean,probably no such file will ever exist. Therefore, therm commandwill be executed every time you say ‘make clean’.The phony target will cease to work if anything ever does create a filenamedclean in this directory. Since it has no prerequisites, thefileclean would inevitably be considered up to date, and itsrecipe would not be executed. To avoid this problem, you can explicitlydeclare the target to be phony, using the special target.PHONY(see Special Built-in Target Names) as follows:

     .PHONY : clean

Once this is done, ‘make clean’ will run the recipe regardless ofwhether there is a file namedclean.

Since it knows that phony targets do not name actual files that could beremade from other files,make skips the implicit rule search forphony targets (see Implicit Rules). This is why declaring a targetphony is good for performance, even if you are not worried about theactual file existing.

Thus, you first write the line that states that clean is aphony target, then you write the rule, like this:

     .PHONY: clean
     clean:
             rm *.o temp

Another example of the usefulness of phony targets is in conjunctionwith recursive invocations ofmake (for more information, seeRecursive Use ofmake). In this case themakefile will often contain a variable which lists a number ofsubdirectories to be built. One way to handle this is with one rulewhose recipe is a shell loop over the subdirectories, like this:

     SUBDIRS = foo bar baz
     
     subdirs:
             for dir in $(SUBDIRS); do \
               $(MAKE) -C $$dir; \
             done

There are problems with this method, however. First, any errordetected in a submake is ignored by this rule, so it will continueto build the rest of the directories even when one fails. This can beovercome by adding shell commands to note the error and exit, but thenit will do so even if make is invoked with the -koption, which is unfortunate. Second, and perhaps more importantly,you cannot take advantage ofmake's ability to build targets inparallel (see Parallel Execution), since there is onlyone rule.

By declaring the subdirectories as phony targets (you must do this asthe subdirectory obviously always exists; otherwise it won't be built)you can remove these problems:

     SUBDIRS = foo bar baz
     
     .PHONY: subdirs $(SUBDIRS)
     
     subdirs: $(SUBDIRS)
     
     $(SUBDIRS):
             $(MAKE) -C $@
     
     foo: baz

Here we've also declared that the foo subdirectory cannot bebuilt until after thebaz subdirectory is complete; this kind ofrelationship declaration is particularly important when attemptingparallel builds.

A phony target should not be a prerequisite of a real target file; if itis, its recipe will be run every timemake goes to update thatfile. As long as a phony target is never a prerequisite of a realtarget, the phony target recipe will be executed only when the phonytarget is a specified goal (seeArguments to Specify the Goals).

Phony targets can have prerequisites. When one directory contains multipleprograms, it is most convenient to describe all of the programs in onemakefile./Makefile. Since the target remade by default will be thefirst one in the makefile, it is common to make this a phony target named‘all’ and give it, as prerequisites, all the individual programs. Forexample:

     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

Now you can say just ‘make’ to remake all three programs, orspecify as arguments the ones to remake (as in ‘make prog1prog3’). Phoniness is not inherited: the prerequisites of a phonytarget are not themselves phony, unless explicitly declared to be so.

When one phony target is a prerequisite of another, it serves as a subroutineof the other. For example, here ‘make cleanall’ will delete theobject files, the difference files, and the fileprogram:

     .PHONY: cleanall cleanobj cleandiff
     
     cleanall : cleanobj cleandiff
             rm program
     
     cleanobj :
             rm *.o
     
     cleandiff :
             rm *.diff

Next:  ,Previous:  Phony Targets,Up:  Rules

4.7 Rules without Recipes or Prerequisites

If a rule has no prerequisites or recipe, and the target of the ruleis a nonexistent file, then make imagines this target to havebeen updated whenever its rule is run. This implies that all targetsdepending on this one will always have their recipe run.

An example will illustrate this:

     clean: FORCE
             rm $(objects)
     FORCE:

Here the target ‘FORCE’ satisfies the special conditions, so thetargetclean that depends on it is forced to run its recipe. There is nothing special about the name ‘FORCE’, but that is onename commonly used this way.

As you can see, using ‘FORCE’ this way has the same results as using‘.PHONY: clean’.

Using ‘.PHONY’ is more explicit and more efficient. However,other versions ofmake do not support ‘.PHONY’; thus‘FORCE’ appears in many makefiles. SeePhony Targets.

Next:  ,Previous:  Force Targets,Up:  Rules

4.8 Empty Target Files to Record Events

Theempty target is a variant of the phony target; it is used to holdrecipes for an action that you request explicitly from time to time. Unlike a phony target, this target file can really exist; but the file'scontents do not matter, and usually are empty.

The purpose of the empty target file is to record, with itslast-modification time, when the rule's recipe was last executed. Itdoes so because one of the commands in the recipe is atouchcommand to update the target file.

The empty target file should have some prerequisites (otherwise itdoesn't make sense). When you ask to remake the empty target, therecipe is executed if any prerequisite is more recent than the target;in other words, if a prerequisite has changed since the last time youremade the target. Here is an example:

     print: foo.c bar.c
             lpr -p $?
             touch print

With this rule, ‘make print’ will execute the lpr command ifeither source file has changed since the last ‘make print’. Theautomatic variable ‘$?’ is used to print only those files that havechanged (see Automatic Variables).

Next:  ,Previous:  Empty Targets,Up:  Rules

4.9 Special Built-in Target Names

Certain names have special meanings if they appear as targets.

.PHONY
The prerequisites of the special target .PHONY are considered tobe phony targets. When it is time to consider such a target, make will run its recipe unconditionally, regardless ofwhether a file with that name exists or what its last-modificationtime is. See Phony Targets.


.SUFFIXES
The prerequisites of the special target .SUFFIXES are the listof suffixes to be used in checking for suffix rules. See Old-Fashioned Suffix Rules.


.DEFAULT
The recipe specified for .DEFAULT is used for any target forwhich no rules are found (either explicit rules or implicit rules). See Last Resort. If a .DEFAULT recipe is specified, everyfile mentioned as a prerequisite, but not as a target in a rule, will havethat recipe executed on its behalf. See Implicit Rule Search Algorithm.


.PRECIOUS
The targets which .PRECIOUS depends on are given the followingspecial treatment: if make is killed or interrupted during theexecution of their recipes, the target is not deleted. See Interrupting or Killing make. Also, if thetarget is an intermediate file, it will not be deleted after it is nolonger needed, as is normally done. See Chains of Implicit Rules. In this latter respect it overlaps with the .SECONDARY special target.

You can also list the target pattern of an implicit rule (such as‘%.o’) as a prerequisite file of the special target.PRECIOUSto preserve intermediate files created by rules whose target patternsmatch that file's name.


.INTERMEDIATE
The targets which .INTERMEDIATE depends on are treated asintermediate files. See Chains of Implicit Rules. .INTERMEDIATE with no prerequisites has no effect.


.SECONDARY
The targets which .SECONDARY depends on are treated asintermediate files, except that they are never automatically deleted. See Chains of Implicit Rules.

.SECONDARY with no prerequisites causes all targets to be treatedas secondary (i.e., no target is removed because it is consideredintermediate).


.SECONDEXPANSION
If .SECONDEXPANSION is mentioned as a target anywhere in themakefile, then all prerequisite lists defined after it appearswill be expanded a second time after all makefiles have been read in. See Secondary Expansion.


.DELETE_ON_ERROR
If .DELETE_ON_ERROR is mentioned as a target anywhere in themakefile, then make will delete the target of a rule if it haschanged and its recipe exits with a nonzero exit status, just as itdoes when it receives a signal. See Errors in Recipes.


.IGNORE
If you specify prerequisites for .IGNORE, then make willignore errors in execution of the recipe for those particular files. The recipe for .IGNORE (if any) is ignored.

If mentioned as a target with no prerequisites, .IGNORE says toignore errors in execution of recipes for all files. This usage of‘.IGNORE’ is supported only for historical compatibility. Sincethis affects every recipe in the makefile, it is not very useful; werecommend you use the more selective ways to ignore errors in specificrecipes. SeeErrors in Recipes.


.LOW_RESOLUTION_TIME
If you specify prerequisites for .LOW_RESOLUTION_TIME, make assumes that these files are created by commands thatgenerate low resolution time stamps. The recipe for the .LOW_RESOLUTION_TIME target are ignored.

The high resolution file time stamps of many modern file systemslessen the chance ofmake incorrectly concluding that a fileis up to date. Unfortunately, some hosts do not provide a way to set ahigh resolution file time stamp, so commands like ‘cp -p’ thatexplicitly set a file's time stamp must discard its subsecond part. If a file is created by such a command, you should list it as aprerequisite of.LOW_RESOLUTION_TIME so that makedoes not mistakenly conclude that the file is out of date. Forexample:

          .LOW_RESOLUTION_TIME: dst
          dst: src
                  cp -p src dst

Since ‘cp -p’ discards the subsecond part ofsrc's timestamp, dst is typically slightly older thansrc even whenit is up to date. The .LOW_RESOLUTION_TIME line causesmake to considerdst to be up to date if its time stampis at the start of the same second thatsrc's time stamp is in.

Due to a limitation of the archive format, archive member time stampsare always low resolution. You need not list archive members asprerequisites of.LOW_RESOLUTION_TIME, as make does thisautomatically.


.SILENT
If you specify prerequisites for .SILENT, then make willnot print the recipe used to remake those particular files beforeexecuting them. The recipe for .SILENT is ignored.

If mentioned as a target with no prerequisites, .SILENT says notto print any recipes before executing them. This usage of‘.SILENT’ is supported only for historical compatibility. Werecommend you use the more selective ways to silence specific recipes. See Recipe Echoing. If you want to silence all recipesfor a particular run ofmake, use the ‘-s’ or‘--silent’ option (seeOptions Summary).


.EXPORT_ALL_VARIABLES
Simply by being mentioned as a target, this tells make toexport all variables to child processes by default. See Communicating Variables to a Sub-make.


.NOTPARALLEL
If .NOTPARALLEL is mentioned as a target, then this invocationof make will be run serially, even if the ‘ -j’ option isgiven. Any recursively invoked make command will still runrecipes in parallel (unless its makefile also contains this target). Any prerequisites on this target are ignored.


.ONESHELL
If .ONESHELL is mentioned as a target, then when a target isbuilt all lines of the recipe will be given to a single invocation ofthe shell rather than each line being invoked separately(see Recipe Execution).


.POSIX
If .POSIX is mentioned as a target, then the makefile will beparsed and run in POSIX-conforming mode. This does not meanthat only POSIX-conforming makefiles will be accepted: all advancedGNU make features are still available. Rather, this targetcauses make to behave as required by POSIX in those areaswhere make's default behavior differs.

In particular, if this target is mentioned then recipes will beinvoked as if the shell had been passed the-e flag: the firstfailing command in a recipe will cause the recipe to fail immediately.

Any defined implicit rule suffix also counts as a special target if itappears as a target, and so does the concatenation of two suffixes, suchas ‘.c.o’. These targets are suffix rules, an obsolete way ofdefining implicit rules (but a way still widely used). In principle, anytarget name could be special in this way if you break it in two and addboth pieces to the suffix list. In practice, suffixes normally begin with‘.’, so these special target names also begin with ‘.’. See Old-Fashioned Suffix Rules.

Next:  ,Previous:  Special Targets,Up:  Rules

4.10 Multiple Targets in a Rule

A rule with multiple targets is equivalent to writing many rules, each withone target, and all identical aside from that. The same recipe applies toall the targets, but its effect may vary because you can substitute theactual target name into the recipe using ‘$@’. The rule contributesthe same prerequisites to all the targets also.

This is useful in two cases.

  • You want just prerequisites, no recipe. For example: 
              kbd.o command.o files.o: command.h

    gives an additional prerequisite to each of the three object filesmentioned.

  • Similar recipes work for all the targets. The recipes do not needto be absolutely identical, since the automatic variable ‘$@’can be used to substitute the particular target to be remade into thecommands (seeAutomatic Variables). For example: 
              bigoutput littleoutput : text.g
                  generate text.g -$(subst output,,$@) > $@

    is equivalent to 

              bigoutput : text.g
                  generate text.g -big > bigoutput
          littleoutput : text.g
                  generate text.g -little > littleoutput

    Here we assume the hypothetical program generate makes twotypes of output, one if given ‘-big’ and one if given‘-little’. SeeFunctions for String Substitution and Analysis,for an explanation of thesubst function.

Suppose you would like to vary the prerequisites according to thetarget, much as the variable ‘$@’ allows you to vary the recipe. You cannot do this with multiple targets in an ordinary rule, but youcan do it with astatic pattern rule. See Static Pattern Rules.

Next:  ,Previous:  Multiple Targets,Up:  Rules

4.11 Multiple Rules for One Target

One file can be the target of several rules. All the prerequisitesmentioned in all the rules are merged into one list of prerequisites forthe 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 thanone rule gives a recipe for the same file,make uses the lastone given and prints an error message. (As a special case, if thefile's name begins with a dot, no error message is printed. This oddbehavior is only for compatibility with other implementations ofmake... you should avoid using it). Occasionally it isuseful to have the same target invoke multiple recipes which aredefined in different parts of your makefile; you can usedouble-colon rules (seeDouble-Colon) for this.

An extra rule with just prerequisites can be used to give a few extraprerequisites to many files at once. For example, makefiles oftenhave a variable, such asobjects, containing a list of all thecompiler output files in the system being made. An easy way to saythat all of them must be recompiled ifconfig.h changes is towrite the following:

     objects = foo.o bar.o
     foo.o : defs.h
     bar.o : defs.h test.h
     $(objects) : config.h

This could be inserted or taken out without changing the rules that reallyspecify how to make the object files, making it a convenient form to use ifyou wish to add the additional prerequisite intermittently.

Another wrinkle is that the additional prerequisites could bespecified with a variable that you set with a command line argument tomake (seeOverriding Variables). For example,

     extradeps=
     $(objects) : $(extradeps)

means that the command ‘make extradeps=foo.h’ will considerfoo.h as a prerequisite of each object file, but plain ‘make’will not.

If none of the explicit rules for a target has a recipe, then makesearches for an applicable implicit rule to find oneseeUsing Implicit Rules).

Next:  ,Previous:  Multiple Rules,Up:  Rules

4.12 Static Pattern Rules

Static pattern rules are rules which specify multiple targets andconstruct the prerequisite names for each target based on the target name. They are more general than ordinary rules with multiple targets because thetargets do not have to have identical prerequisites. Their prerequisites mustbe analogous, but not necessarily identical.

Next:  ,Previous:  Static Pattern,Up:  Static Pattern

4.12.1 Syntax of Static Pattern Rules

Here is the syntax of a static pattern rule:

     targets ...: target-pattern: prereq-patterns ...
             recipe
             ...

The targets list specifies the targets that the rule applies to. The targets can contain wildcard characters, just like the targets ofordinary rules (seeUsing Wildcard Characters in File Names).

Thetarget-pattern and prereq-patterns say how to compute theprerequisites of each target. Each target is matched against thetarget-pattern to extract a part of the target name, called thestem. This stem is substituted into each of the prereq-patternsto make the prerequisite names (one from eachprereq-pattern).

Each pattern normally contains the character ‘%’ just once. When thetarget-pattern matches a target, the ‘%’ can match any part ofthe target name; this part is called the stem. The rest of thepattern must match exactly. For example, the targetfoo.o matchesthe pattern ‘%.o’, with ‘foo’ as the stem. The targetsfoo.c andfoo.out do not match that pattern.

The prerequisite names for each target are made by substituting the stemfor the ‘%’ in each prerequisite pattern. For example, if oneprerequisite pattern is %.c, then substitution of the stem‘foo’ gives the prerequisite namefoo.c. It is legitimateto write a prerequisite pattern that does not contain ‘%’; then thisprerequisite is the same for all targets.

‘%’ characters in pattern rules can be quoted with precedingbackslashes (‘\’). Backslashes that would otherwise quote ‘%’characters can be quoted with more backslashes. Backslashes that quote‘%’ characters or other backslashes are removed from the patternbefore it is compared to file names or has a stem substituted into it. Backslashes that are not in danger of quoting ‘%’ characters gounmolested. For example, the pattern the\%weird\\%pattern\\ has‘the%weird\’ preceding the operative ‘%’ character, and‘pattern\\’ following it. The final two backslashes are left alonebecause they cannot affect any ‘%’ character.

Here is an example, which compiles each of foo.o andbar.ofrom the corresponding .c file:

     objects = foo.o bar.o
     
     all: $(objects)
     
     $(objects): %.o: %.c
             $(CC) -c $(CFLAGS) $< -o $@

Here ‘$<’ is the automatic variable that holds the name of theprerequisite and ‘$@’ is the automatic variable that holds the nameof the target; seeAutomatic Variables.

Each target specified must match the target pattern; a warning is issuedfor each target that does not. If you have a list of files, only some ofwhich will match the pattern, you can use thefilter function toremove nonmatching file names (see Functions for String Substitution and Analysis):

     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 $<

In this example the result of ‘$(filter %.o,$(files))’ isbar.o lose.o, and the first static pattern rule causes each ofthese object files to be updated by compiling the corresponding C sourcefile. The result of ‘$(filter %.elc,$(files))’ isfoo.elc, so that file is made fromfoo.el.

Another example shows how to use $* in static pattern rules:

     bigoutput littleoutput : %output : text.g
             generate text.g -$* > $@

When the generate command is run, $* will expand to thestem, either ‘big’ or ‘little’.

Previous:  Static Usage,Up:  Static Pattern

4.12.2 Static Pattern Rules versus Implicit Rules

A static pattern rule has much in common with an implicit rule defined as apattern rule (seeDefining and Redefining Pattern Rules). Both have a pattern for the target and patterns for constructing thenames of prerequisites. The difference is in howmake decideswhen the rule applies.

An implicit rule can apply to any target that matches its pattern,but itdoes apply only when the target has no recipe otherwisespecified, and only when the prerequisites can be found. If more than oneimplicit rule appears applicable, only one applies; the choice depends onthe order of rules.

By contrast, a static pattern rule applies to the precise list of targetsthat you specify in the rule. It cannot apply to any other target and itinvariably does apply to each of the targets specified. If two conflictingrules apply, and both have recipes, that's an error.

The static pattern rule can be better than an implicit rule for thesereasons:

  • You may wish to override the usual implicit rule for a fewfiles whose names cannot be categorized syntactically butcan be given in an explicit list.
  • If you cannot be sure of the precise contents of the directoriesyou are using, you may not be sure which other irrelevant filesmight leadmake to use the wrong implicit rule. The choicemight depend on the order in which the implicit rule search is done. With static pattern rules, there is no uncertainty: each rule appliesto precisely the targets specified.

Next:  ,Previous:  Static Pattern,Up:  Rules

4.13 Double-Colon Rules

Double-colon rules are explicit rules written with ‘::’instead of ‘:’ after the target names. They are handleddifferently from ordinary rules when the same target appears in morethan one rule. Pattern rules with double-colons have an entirelydifferent meaning (see Match-Anything Rules).

When a target appears in multiple rules, all the rules must be the sametype: all ordinary, or all double-colon. If they are double-colon, eachof them is independent of the others. Each double-colon rule's recipeis executed if the target is older than any prerequisites of that rule. If there are no prerequisites for that rule, its recipe is alwaysexecuted (even if the target already exists). This can result inexecuting none, any, or all of the double-colon rules.

Double-colon rules with the same target are in fact completely separatefrom one another. Each double-colon rule is processed individually, justas rules with different targets are processed.

The double-colon rules for a target are executed in the order they appearin the makefile. However, the cases where double-colon rules really makesense are those where the order of executing the recipes would not matter.

Double-colon rules are somewhat obscure and not often very useful; theyprovide a mechanism for cases in which the method used to update a targetdiffers depending on which prerequisite files caused the update, and suchcases are rare.

Each double-colon rule should specify a recipe; if it does not, animplicit rule will be used if one applies. SeeUsing Implicit Rules.

Previous:  Double-Colon,Up:  Rules

4.14 Generating Prerequisites Automatically

In the makefile for a program, many of the rules you need to write oftensay only that some object file depends on some headerfile. For example, if main.c uses defs.h via an#include, you would write:

     main.o: defs.h

You need this rule so that make knows that it must remakemain.o wheneverdefs.h changes. You can see that for alarge program you would have to write dozens of such rules in yourmakefile. And, you must always be very careful to update the makefileevery time you add or remove an#include. To avoid this hassle, most modern C compilers can write these rules foryou, by looking at the#include lines in the source files. Usually this is done with the ‘-M’ option to the compiler. For example, the command:

     cc -M main.c

generates the output:

     main.o : main.c defs.h

Thus you no longer have to write all those rules yourself. The compiler will do it for you.

Note that such a prerequisite constitutes mentioning main.o in amakefile, so it can never be considered an intermediate file by implicitrule search. This means thatmake won't ever remove the fileafter using it; see Chains of Implicit Rules.

With old make programs, it was traditional practice to use thiscompiler feature to generate prerequisites on demand with a command like‘make depend’. That command would create a file dependcontaining all the automatically-generated prerequisites; then themakefile could useinclude to read them in (see Include).

In GNU make, the feature of remaking makefiles makes thispractice obsolete—you need never tellmake explicitly toregenerate the prerequisites, because it always regenerates any makefilethat is out of date. SeeRemaking Makefiles.

The practice we recommend for automatic prerequisite generation is to haveone makefile corresponding to each source file. For each source filename.c there is a makefilename.d which listswhat files the object filename.o depends on. That wayonly the source files that have changed need to be rescanned to producethe new prerequisites.

Here is the pattern rule to generate a file of prerequisites (i.e., a makefile)calledname.d from a C source file calledname.c:

     %.d: %.c
             @set -e; rm -f $@; \
              $(CC) -M $(CPPFLAGS) $< > $@.$$$$; \
              sed 's,\($*\)\.o[ :]*,\1.o $@ : ,g' < $@.$$$$ > $@; \
              rm -f $@.$$$$

See Pattern Rules, for information on defining pattern rules. The‘-e’ flag to the shell causes it to exit immediately if the$(CC) command (or any other command) fails (exits with anonzero status). With the GNU C compiler, you may wish to use the ‘-MM’ flag insteadof ‘-M’. This omits prerequisites on system header files. See Options Controlling the Preprocessor, for details.

The purpose of thesed command is to translate (for example):

     main.o : main.c defs.h

into:

     main.o main.d : main.c defs.h

This makes each ‘.d’ file depend on all the source and header filesthat the corresponding ‘.o’ file depends on. make thenknows it must regenerate the prerequisites whenever any of the source orheader files changes.

Once you've defined the rule to remake the ‘.d’ files,you then use theinclude directive to read them all in. See Include. For example:

     sources = foo.c bar.c
     
     include $(sources:.c=.d)

(This example uses a substitution variable reference to translate thelist of source files ‘foo.c bar.c’ into a list of prerequisitemakefiles, ‘foo.d bar.d’. SeeSubstitution Refs, for fullinformation on substitution references.) Since the ‘.d’ files aremakefiles like any others,make will remake them as necessarywith no further work from you. SeeRemaking Makefiles.

Note that the ‘.d’ files contain target definitions; you shouldbe sure to place theinclude directive after the first,default goal in your makefiles or run the risk of having a randomobject file become the default goal. SeeHow Make Works.

Next:  ,Previous:  Rules,Up:  Top

5 Writing Recipes in Rules

The recipe of a rule consists of one or more shell command lines tobe executed, one at a time, in the order they appear. Typically, theresult of executing these commands is that the target of the rule isbrought up to date.

Users use many different shell programs, but recipes in makefiles arealways interpreted by/bin/sh unless the makefile specifiesotherwise. SeeRecipe Execution.

Next:  ,Previous:  Recipes,Up:  Recipes

5.1 Recipe Syntax

Makefiles have the unusual property that there are really two distinctsyntaxes in one file. Most of the makefile usesmake syntax(see Writing Makefiles). However, recipes are meantto be interpreted by the shell and so they are written using shellsyntax. Themake program does not try to understand shellsyntax: it performs only a very few specific translations on thecontent of the recipe before handing it to the shell.

Each line in the recipe must start with a tab (or the first characterin the value of the.RECIPEPREFIX variable; see Special Variables), except that the first recipe line may be attached to thetarget-and-prerequisites line with a semicolon in between.Anyline in the makefile that begins with a tab and appears in a “rulecontext” (that is, after a rule has been started until another ruleor variable definition) will be considered part of a recipe for thatrule. Blank lines and lines of just comments may appear among therecipe lines; they are ignored.

Some consequences of these rules include:

  • A blank line that begins with a tab is not blank: it's an emptyrecipe (see Empty Recipes).

  • A comment in a recipe is not a make comment; it will bepassed to the shell as-is. Whether the shell treats it as a commentor not depends on your shell.
  • A variable definition in a “rule context” which is indented by a tabas the first character on the line, will be considered part of arecipe, not amake variable definition, and passed to theshell.
  • A conditional expression (ifdef, ifeq,etc. see Syntax of Conditionals) in a “rulecontext” which is indented by a tab as the first character on theline, will be considered part of a recipe and be passed to the shell.

Next:  ,Previous:  Recipe Syntax,Up:  Recipe Syntax

5.1.1 Splitting Recipe Lines

One of the few ways in which make does interpret recipes ischecking for a backslash just before the newline. As in normalmakefile syntax, a single logical recipe line can be split intomultiple physical lines in the makefile by placing a backslash beforeeach newline. A sequence of lines like this is considered a singlerecipe 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 amakefile, backslash-newline pairs arenot removed from therecipe. Both the backslash and the newline characters are preservedand passed to the shell. How the backslash-newline is interpreteddepends on your shell. If the first character of the next line afterthe backslash-newline is the recipe prefix character (a tab bydefault; see Special Variables), then that character (and onlythat character) is removed. Whitespace is never added to the recipe.

For example, the recipe for the all target in this makefile:

     all :
             @echo no\
     space
             @echo no\
             space
             @echo one \
             space
             @echo one\
              space

consists of four separate shell commands where the output is:

     nospace
     nospace
     one space
     one space

As a more complex example, this makefile:

     all : ; @echo 'hello \
             world' ; echo "hello \
         world"

will invoke one shell with a command of:

     echo 'hello \
     world' ; echo "hello \
         world"

which, according to shell quoting rules, will yield the following output:

     hello \
     world
     hello     world

Notice how the backslash/newline pair was removed inside the stringquoted with double quotes ("..."), but not from the stringquoted with single quotes ('...'). This is the way thedefault shell (/bin/sh) handles backslash/newline pairs. Ifyou specify a different shell in your makefiles it may treat themdifferently.

Sometimes you want to split a long line inside of single quotes, butyou 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,where extraneous backslashes inside the script can change its meaningor even be a syntax error. One simple way of handling this is toplace the quoted string, or even the entire command, into amake variable then use the variable in the recipe. In thissituation the newline quoting rules for makefiles will be used, andthe backslash-newline will be removed. If we rewrite our exampleabove using this method:

     HELLO = 'hello \
     world'
     
     all : ; @echo $(HELLO)

we will get output like this:

     hello world

If you like, you can also use target-specific variables(see Target-specific Variable Values) to obtaina tighter correspondence between the variable and the recipe thatuses it.

Previous:  Splitting Lines,Up:  Recipe Syntax

5.1.2 Using Variables in Recipes

The other way in whichmake processes recipes is by expandingany variable references in them (seeBasics of Variable References). This occurs after make has finished reading all themakefiles and the target is determined to be out of date; so, therecipes for targets which are not rebuilt are never expanded.

Variable and function references in recipes have identical syntax andsemantics to references elsewhere in the makefile. They also have thesame quoting rules: if you want a dollar sign to appear in yourrecipe, you must double it (‘$$’). For shells like the defaultshell, that use dollar signs to introduce variables, it's important tokeep clear in your mind whether the variable you want to reference isamake variable (use a single dollar sign) or a shell variable(use two dollar signs). For example:

     LIST = one two three
     all:
             for i in $(LIST); do \
                 echo $$i; \
             done

results in the following command being passed to the shell:

     for i in one two three; do \
         echo $i; \
     done

which generates the expected result:

     one
     two
     three

Next:  ,Previous:  Recipe Syntax,Up:  Recipes

5.2 Recipe Echoing

Normallymake prints each line of the recipe before it isexecuted. We call thisechoing because it gives the appearancethat you are typing the lines yourself.

When a line starts with ‘@’, the echoing of that line is suppressed. The ‘@’ is discarded before the line is passed to the shell. Typically you would use this for a command whose only effect is to printsomething, such as an echo command to indicate progress throughthe makefile:

     @echo About to make distribution files

Whenmake is given the flag ‘-n’ or ‘--just-print’ itonly echoes most recipes, without executing them. SeeSummary of Options. In this case even the recipe linesstarting with ‘@’ are printed. This flag is useful for findingout which recipesmake thinks are necessary without actuallydoing them.

The ‘-s’ or ‘--silent’flag to make prevents all echoing, as if all recipesstarted with ‘@’. A rule in the makefile for the special target.SILENT without prerequisites has the same effect(see Special Built-in Target Names)..SILENT is essentially obsolete since ‘@’ is more flexible.

Next:  ,Previous:  Echoing,Up:  Recipes

5.3 Recipe Execution

When it is time to execute recipes to update a target, they areexecuted by invoking a new subshell for each line of the recipe,unless the .ONESHELL special target is in effect(seeUsing One Shell) (In practice, make maytake shortcuts that do not affect the results.)

Please note: this implies that setting shell variables andinvoking shell commands such as cd that set a context local toeach process will not affect the following lines in the recipe.2 If you want to usecd to affect the next statement,put both statements in a single recipe line. Thenmake willinvoke one shell to run the entire line, and the shell will executethe statements in sequence. For example:

     foo : bar/lose
             cd $(@D) && gobble $(@F) > ../$@

Here we use the shell AND operator (&&) so that if thecd command fails, the script will fail without trying to invokethegobble command in the wrong directory, which could causeproblems (in this case it would certainly cause../foo to betruncated, at least).

Next:  ,Previous:  Execution,Up:  Execution

5.3.1 Using One Shell

Sometimes you would prefer that all the lines in the recipe be passedto a single invocation of the shell. There are generally twosituations where this is useful: first, it can improve performance inmakefiles where recipes consist of many command lines, by avoidingextra processes. Second, you might want newlines to be included inyour recipe command (for example perhaps you are using a verydifferent interpreter as your SHELL). If the.ONESHELLspecial target appears anywhere in the makefile then allrecipe lines for each target will be provided to a single invocationof the shell. Newlines between recipe lines will be preserved. Forexample:

     .ONESHELL:
     foo : bar/lose
             cd $(@D)
             gobble $(@F) > ../$@

would now work as expected even though the commands are on differentrecipe lines.

If .ONESHELL is provided, then only the first line of therecipe will be checked for the special prefix characters (‘@’,‘-’, and ‘+’). Subsequent lines will include the specialcharacters in the recipe line when the SHELL is invoked. Ifyou want your recipe to start with one of these special charactersyou'll need to arrange for them to not be the first characters on thefirst line, perhaps by adding a comment or similar. For example, thiswould be a syntax error in Perl because the first ‘@’ is removedby make:

     .ONESHELL:
     SHELL = /usr/bin/perl
     .SHELLFLAGS = -e
     show :
             @f = qw(a b c);
             print "@f\n";

However, either of these alternatives would work properly:

     .ONESHELL:
     SHELL = /usr/bin/perl
     .SHELLFLAGS = -e
     show :
             # Make sure "@" is not the first character on the first line
             @f = qw(a b c);
             print "@f\n";

or

     .ONESHELL:
     SHELL = /usr/bin/perl
     .SHELLFLAGS = -e
     show :
             my @f = qw(a b c);
             print "@f\n";

As a special feature, if SHELL is determined to be aPOSIX-style shell, the special prefix characters in “internal”recipe lines willremoved before the recipe is processed. Thisfeature is intended to allow existing makefiles to add the.ONESHELL special target and still run properly withoutextensive modifications. Since the special prefix characters are notlegal at the beginning of a line in a POSIX shell script this is not aloss in functionality. For example, this works as expected:

     .ONESHELL:
     foo : bar/lose
             @cd $(@D)
             @gobble $(@F) > ../$@

Even with this special feature, however, makefiles with.ONESHELL will behave differently in ways that could benoticeable. For example, normally if any line in the recipe fails,that causes the rule to fail and no more recipe lines are processed. Under .ONESHELL a failure of any but the final recipe line willnot be noticed bymake. You can modify .SHELLFLAGS toadd the -e option to the shell which will cause any failureanywhere in the command line to cause the shell to fail, but thiscould itself cause your recipe to behave differently. Ultimately youmay need to harden your recipe lines to allow them to work with.ONESHELL.

Previous:  One Shell,Up:  Execution

5.3.2 Choosing the Shell

The program used as the shell is taken from the variable SHELL. If this variable is not set in your makefile, the program/bin/sh is used as the shell. The argument(s) passed to theshell are taken from the variable.SHELLFLAGS. The defaultvalue of .SHELLFLAGS is -c normally, or-ec inPOSIX-conforming mode.

Unlike most variables, the variableSHELL is never set from theenvironment. This is because the SHELL environment variable isused to specify your personal choice of shell program for interactiveuse. It would be very bad for personal choices like this to affect thefunctioning of makefiles. See Variables from the Environment.

Furthermore, when you do set SHELL in your makefile that valueis not exported in the environment to recipe lines thatmake invokes. Instead, the value inherited from the user'senvironment, if any, is exported. You can override this behavior byexplicitly exportingSHELL (see Communicating Variables to a Sub-make), forcing it to bepassed in the environment to recipe lines.

However, on MS-DOS and MS-Windows the value ofSHELL in theenvironment is used, since on those systems most users do notset this variable, and therefore it is most likely set specifically tobe used bymake. On MS-DOS, if the setting of SHELL isnot suitable formake, you can set the variableMAKESHELL to the shell thatmake should use; if set itwill be used as the shell instead of the value ofSHELL.

Choosing a Shell in DOS and Windows

Choosing a shell in MS-DOS and MS-Windows is much more complex than onother systems.

On MS-DOS, if SHELL is not set, the value of the variableCOMSPEC (which is always set) is used instead.

The processing of lines that set the variableSHELL in Makefilesis different on MS-DOS. The stock shell, command.com, isridiculously limited in its functionality and many users ofmaketend to install a replacement shell. Therefore, on MS-DOS, makeexamines the value of SHELL, and changes its behavior based onwhether it points to a Unix-style or DOS-style shell. This allowsreasonable functionality even ifSHELL points tocommand.com.

If SHELL points to a Unix-style shell, make on MS-DOSadditionally checks whether that shell can indeed be found; if not, itignores the line that setsSHELL. In MS-DOS, GNU makesearches for the shell in the following places:

  1. In the precise place pointed to by the value of SHELL. Forexample, if the makefile specifies ‘SHELL = /bin/sh’,makewill look in the directory /bin on the current drive.
  2. In the current directory.
  3. In each of the directories in the PATH variable, in order.

In every directory it examines, make will first look for thespecific file (sh in the example above). If this is not found,it will also look in that directory for that file with one of the knownextensions which identify executable files. For example .exe,.com,.bat, .btm,.sh, and some others.

If any of these attempts is successful, the value of SHELL willbe set to the full pathname of the shell as found. However, if none ofthese is found, the value ofSHELL will not be changed, and thusthe line that sets it will be effectively ignored. This is somake will only support features specific to a Unix-style shell ifsuch a shell is actually installed on the system wheremake runs.

Note that this extended search for the shell is limited to the caseswhere SHELL is set from the Makefile; if it is set in theenvironment or command line, you are expected to set it to the fullpathname of the shell, exactly as things are on Unix.

The effect of the above DOS-specific processing is that a Makefile thatcontains ‘SHELL = /bin/sh’ (as many Unix makefiles do), will workon MS-DOS unaltered if you have e.g.sh.exe installed in somedirectory along yourPATH.

Next:  ,Previous:  Execution,Up:  Recipes

5.4 Parallel Execution

GNUmake knows how to execute several recipes at once. Normally, make will execute only one recipe at a time, waitingfor it to finish before executing the next. However, the ‘-j’ or‘--jobs’ option tells make to execute many recipessimultaneously. You can inhibit parallelism in a particular makefilewith the.NOTPARALLEL pseudo-target (see Special Built-in Target Names).

On MS-DOS, the ‘-j’ option has no effect, since that system doesn'tsupport multi-processing.

If the ‘-j’ option is followed by an integer, this is the number ofrecipes to execute at once; this is called the number ofjob slots. If there is nothing looking like an integer after the ‘-j’ option,there is no limit on the number of job slots. The default number of jobslots is one, which means serial execution (one thing at a time).

One unpleasant consequence of running several recipes simultaneously isthat output generated by the recipes appears whenever each recipesends it, so messages from different recipes may be interspersed.

Another problem is that two processes cannot both take input from thesame device; so to make sure that only one recipe tries to take inputfrom the terminal at once,make will invalidate the standardinput streams of all but one running recipe. This means thatattempting to read from standard input will usually be a fatal error (a‘Broken pipe’ signal) for most child processes if there areseveral. It is unpredictable which recipe will have a valid standard input stream(which will come from the terminal, or wherever you redirect the standardinput ofmake). The first recipe run will always get it first, andthe first recipe started after that one finishes will get it next, and soon.

We will change how this aspect of make works if we find a betteralternative. In the mean time, you should not rely on any recipe usingstandard input at all if you are using the parallel execution feature; butif you are not using this feature, then standard input works normally inall recipes.

Finally, handling recursive make invocations raises issues. Formore information on this, seeCommunicating Options to a Sub-make.

If a recipe fails (is killed by a signal or exits with a nonzerostatus), and errors are not ignored for that recipe(seeErrors in Recipes),the remaining recipe lines to remake the same target will not be run. If a recipe fails and the ‘-k’ or ‘--keep-going’option was not given(seeSummary of Options),make aborts execution. If maketerminates for any reason (including a signal) with child processesrunning, it waits for them to finish before actually exiting.

When the system is heavily loaded, you will probably want to run fewer jobsthan when it is lightly loaded. You can use the ‘-l’ option to tellmake to limit the number of jobs to run at once, based on the loadaverage. The ‘-l’ or ‘--max-load’option is followed by a floating-point number. Forexample,

     -l 2.5

will not let make start more than one job if the load average isabove 2.5. The ‘-l’ option with no following number removes theload limit, if one was given with a previous ‘-l’ option.

More precisely, when make goes to start up a job, and it already hasat least one job running, it checks the current load average; if it is notlower than the limit given with ‘-l’,make waits until the loadaverage goes below that limit, or until all the other jobs finish.

By default, there is no load limit.

Next:  ,Previous:  Parallel,Up:  Recipes

5.5 Errors in Recipes

After each shell invocation returns,make looks at its exitstatus. If the shell completed successfully (the exit status iszero), the next line in the recipe is executed in a new shell; afterthe last line is finished, the rule is finished.

If there is an error (the exit status is nonzero), make gives up onthe current rule, and perhaps on all rules.

Sometimes the failure of a certain recipe line does not indicate a problem. For example, you may use themkdir command to ensure that adirectory exists. If the directory already exists,mkdir willreport an error, but you probably want make to continue regardless.

To ignore errors in a recipe line, write a ‘-’ at the beginningof the line's text (after the initial tab). The ‘-’ is discardedbefore the line is passed to the shell for execution.

For example,

     clean:
             -rm -f *.o

This causesmake to continue even if rm is unable toremove a file.

When you runmake with the ‘-i’ or ‘--ignore-errors’flag, errors are ignored in all recipes of all rules. A rule in themakefile for the special target.IGNORE has the same effect, ifthere are no prerequisites. These ways of ignoring errors are obsoletebecause ‘-’ is more flexible.

When errors are to be ignored, because of either a ‘-’ or the‘-i’ flag,make treats an error return just like success,except that it prints out a message that tells you the status codethe shell exited with, and says that the error has been ignored.

When an error happens that make has not been told to ignore,it implies that the current target cannot be correctly remade, and neithercan any other that depends on it either directly or indirectly. No furtherrecipes will be executed for these targets, since their preconditionshave not been achieved.

Normallymake gives up immediately in this circumstance, returning anonzero status. However, if the ‘-k’ or ‘--keep-going’flag is specified,makecontinues to consider the other prerequisites of the pending targets,remaking them if necessary, before it gives up and returns nonzero status. For example, after an error in compiling one object file, ‘make -k’will continue compiling other object files even though it already knowsthat linking them will be impossible. SeeSummary of Options.

The usual behavior assumes that your purpose is to get the specifiedtargets up to date; oncemake learns that this is impossible, itmight as well report the failure immediately. The ‘-k’ option saysthat the real purpose is to test as many of the changes made in theprogram as possible, perhaps to find several independent problems sothat you can correct them all before the next attempt to compile. Thisis why Emacs'compile command passes the ‘-k’ flag bydefault.Usually when a recipe line fails, if it has changed the target file at all,the file is corrupted and cannot be used—or at least it is notcompletely updated. Yet the file's time stamp says that it is now up todate, so the next timemake runs, it will not try to update thatfile. The situation is just the same as when the shell is killed by asignal; seeInterrupts. So generally the right thing to do is todelete the target file if the recipe fails after beginning to changethe file.make will do this if .DELETE_ON_ERROR appearsas a target. This is almost always what you wantmake to do, butit is not historical practice; so for compatibility, you must explicitlyrequest it.

Next:  ,Previous:  Errors,Up:  Recipes

5.6 Interrupting or Killing make

Ifmake gets a fatal signal while a shell is executing, it maydelete the target file that the recipe was supposed to update. This isdone if the target file's last-modification time has changed sincemake first checked it.

The purpose of deleting the target is to make sure that it is remade fromscratch whenmake is next run. Why is this? Suppose you typeCtrl-c while a compiler is running, and it has begun to write anobject filefoo.o. The Ctrl-c kills the compiler, resultingin an incomplete file whose last-modification time is newer than the sourcefilefoo.c. But make also receives theCtrl-c signaland deletes this incomplete file. If make did not do this, the nextinvocation ofmake would think that foo.o did not requireupdating—resulting in a strange error message from the linker when ittries to link an object file half of which is missing.

You can prevent the deletion of a target file in this way by making thespecial target.PRECIOUS depend on it. Before remaking a target,make checks to see whether it appears on the prerequisites of.PRECIOUS, and thereby decides whether the target should be deletedif a signal happens. Some reasons why you might do this are that thetarget is updated in some atomic fashion, or exists only to record amodification-time (its contents do not matter), or must exist at alltimes to prevent other sorts of trouble.

Next:  ,Previous:  Interrupts,Up:  Recipes

5.7 Recursive Use of make

Recursive use ofmake means using make as a command in amakefile. This technique is useful when you want separate makefiles forvarious subsystems that compose a larger system. For example, suppose youhave a subdirectorysubdir which has its own makefile, and you wouldlike the containing directory's makefile to runmake on thesubdirectory. You can do it by writing this:

     subsystem:
             cd subdir && $(MAKE)

or, equivalently, this (see Summary of Options):

     subsystem:
             $(MAKE) -C subdir

You can write recursivemake commands just by copying this example,but there are many things to know about how they work and why, and abouthow the sub-make relates to the top-levelmake. You mayalso find it useful to declare targets that invoke recursivemake commands as ‘.PHONY’ (for more discussion on whenthis is useful, seePhony Targets).

For your convenience, when GNUmake starts (after it hasprocessed any -C options) it sets the variableCURDIR tothe pathname of the current working directory. This value is nevertouched bymake again: in particular note that if you includefiles from other directories the value ofCURDIR does notchange. The value has the same precedence it would have if it wereset in the makefile (by default, an environment variableCURDIRwill not override this value). Note that setting this variable has noimpact on the operation ofmake (it does not cause maketo change its working directory, for example).

Next:  ,Previous:  Recursion,Up:  Recursion

5.7.1 How the MAKE Variable Works

Recursivemake commands should always use the variable MAKE,not the explicit command name ‘make’, as shown here:

     subsystem:
             cd subdir && $(MAKE)

The value of this variable is the file name with which make wasinvoked. If this file name was/bin/make, then the recipe executedis ‘cd subdir && /bin/make’. If you use a special version ofmake to run the top-level makefile, the same special version will beexecuted for recursive invocations. As a special feature, using the variableMAKE in the recipe ofa rule alters the effects of the ‘-t’ (‘--touch’), ‘-n’(‘--just-print’), or ‘-q’ (‘--question’) option. Using theMAKE variable has the same effect as using a ‘+’character at the beginning of the recipe line. SeeInstead of Executing the Recipes. This special featureis only enabled if theMAKE variable appears directly in therecipe: it does not apply if theMAKE variable is referencedthrough expansion of another variable. In the latter case you mustuse the ‘+’ token to get these special effects.

Consider the command ‘make -t’ in the above example. (The‘-t’ option marks targets as up to date without actually runningany recipes; seeInstead of Execution.) Following the usualdefinition of ‘-t’, a ‘make -t’ command in the example wouldcreate a file namedsubsystem and do nothing else. What youreally want it to do is run ‘cd subdir && make -t’; butthat would require executing the recipe, and ‘-t’ says not toexecute recipes. The special feature makes this do what you want: whenever a recipeline of a rule contains the variableMAKE, the flags ‘-t’,‘-n’ and ‘-q’ do not apply to that line. Recipe linescontainingMAKE are executed normally despite the presence of aflag that causes most recipes not to be run. The usualMAKEFLAGS mechanism passes the flags to the sub-make(seeCommunicating Options to a Sub-make), so your request to touch the files, or print therecipes, is propagated to the subsystem.

Next:  ,Previous:  MAKE Variable,Up:  Recursion

5.7.2 Communicating Variables to a Sub-make

Variable values of the top-level make can be passed to thesub-make through the environment by explicit request. Thesevariables are defined in the sub-make as defaults, but do notoverride what is specified in the makefile used by the sub-makemakefile unless you use the ‘-e’ switch (seeSummary of Options).

To pass down, or export, a variable, make adds thevariable and its value to the environment for running each line of therecipe. The sub-make, in turn, uses the environment toinitialize its table of variable values. SeeVariables from the Environment.

Except by explicit request, make exports a variable only if itis either defined in the environment initially or set on the commandline, and if its name consists only of letters, numbers, and underscores. Some shells cannot cope with environment variable names consisting ofcharacters other than letters, numbers, and underscores.

The value of the make variableSHELL is not exported. Instead, the value of the SHELL variable from the invokingenvironment is passed to the sub-make. You can forcemake to export its value forSHELL by using theexport directive, described below. SeeChoosing the Shell.

The special variable MAKEFLAGS is always exported (unless youunexport it).MAKEFILES is exported if you set it to anything.

make automatically passes down variable values that were definedon the command line, by putting them in theMAKEFLAGS variable. See Options/Recursion.

Variables are not normally passed down if they were created bydefault bymake (see Variables Used by Implicit Rules). The sub-make will define these foritself.

If you want to export specific variables to a sub-make, use theexport directive, like this:

     export variable ...

If you want to prevent a variable from being exported, use theunexport directive, like this:

     unexport variable ...

In both of these forms, the arguments to export andunexport are expanded, and so could be variables or functionswhich expand to a (list of) variable names to be (un)exported.

As a convenience, you can define a variable and export it at the sametime by doing:

     export variable = value

has the same result as:

     variable = value
     export variable

and

     export variable := value

has the same result as:

     variable := value
     export variable

Likewise,

     export variable += value

is just like:

     variable += value
     export variable

See Appending More Text to Variables.

You may notice that the export and unexport directiveswork inmake in the same way they work in the shell, sh.

If you want all variables to be exported by default, you can useexport by itself:

     export

This tells make that variables which are not explicitly mentionedin anexport or unexport directive should be exported. Any variable given in anunexport directive will still notbe exported. If you use export by itself to export variables bydefault, variables whose names contain characters other thanalphanumerics and underscores will not be exported unless specificallymentioned in anexport directive.

The behavior elicited by anexport directive by itself was thedefault in older versions of GNU make. If your makefiles dependon this behavior and you want to be compatible with old versions ofmake, you can write a rule for the special target.EXPORT_ALL_VARIABLES instead of using theexport directive. This will be ignored by old makes, while theexportdirective will cause a syntax error. Likewise, you can use unexport by itself to tell makenot to export variables by default. Since this is the defaultbehavior, you would only need to do this ifexport had been usedby itself earlier (in an included makefile, perhaps). Youcannot useexport and unexport by themselves tohave variables exported for some recipes and not for others. The lastexport orunexport directive that appears by itselfdetermines the behavior for the entire run ofmake.

As a special feature, the variableMAKELEVEL is changed when itis passed down from level to level. This variable's value is a stringwhich is the depth of the level as a decimal number. The value is‘0’ for the top-levelmake; ‘1’ for a sub-make,‘2’ for a sub-sub-make, and so on. The incrementationhappens whenmake sets up the environment for a recipe.

The main use of MAKELEVEL is to test it in a conditionaldirective (seeConditional Parts of Makefiles); thisway you can write a makefile that behaves one way if run recursively andanother way if run directly by you.

You can use the variable MAKEFILES to cause all sub-makecommands to use additional makefiles. The value ofMAKEFILES isa whitespace-separated list of file names. This variable, if defined inthe outer-level makefile, is passed down through the environment; thenit serves as a list of extra makefiles for the sub-make to readbefore the usual or specified ones. See The Variable MAKEFILES.

Next:  ,Previous:  Variables/Recursion,Up:  Recursion

5.7.3 Communicating Options to a Sub-make

Flags such as ‘-s’ and ‘-k’ are passed automatically to thesub-make through the variable MAKEFLAGS. This variable isset up automatically bymake to contain the flag letters thatmake received. Thus, if you do ‘make -ks’ thenMAKEFLAGS gets the value ‘ks’.

As a consequence, every sub-make gets a value for MAKEFLAGSin its environment. In response, it takes the flags from that value andprocesses them as if they had been given as arguments. SeeSummary of Options.

Likewise variables defined on the command line are passed to thesub-make through MAKEFLAGS. Words in the value ofMAKEFLAGS that contain ‘=’,make treats as variabledefinitions just as if they appeared on the command line. SeeOverriding Variables.

The options ‘-C’, ‘-f’, ‘-o’, and ‘-W’ are not putintoMAKEFLAGS; these options are not passed down.

The ‘-j’ option is a special case (see Parallel Execution). If you set it to some numeric value ‘N’ and your operating systemsupports it (most any UNIX system will; others typically won't), theparentmake and all the sub-makes will communicate toensure that there are only ‘N’ jobs running at the same timebetween them all. Note that any job that is marked recursive(seeInstead of Executing Recipes)doesn't count against the total jobs (otherwise we could get ‘N’sub-makes running and have no slots left over for any real work!)

If your operating system doesn't support the above communication, then‘-j 1’ is always put intoMAKEFLAGS instead of the value youspecified. This is because if the ‘-j’ option were passed downto sub-makes, you would get many more jobs running in parallelthan you asked for. If you give ‘-j’ with no numeric argument,meaning to run as many jobs as possible in parallel, this is passeddown, since multiple infinities are no more than one.

If you do not want to pass the other flags down, you must change thevalue of MAKEFLAGS, like this:

     subsystem:
             cd subdir && $(MAKE) MAKEFLAGS=

The command line variable definitions really appear in the variableMAKEOVERRIDES, andMAKEFLAGS contains a reference to thisvariable. If you do want to pass flags down normally, but don't want topass down the command line variable definitions, you can resetMAKEOVERRIDES to empty, like this:

     MAKEOVERRIDES =

This is not usually useful to do. However, some systems have a smallfixed limit on the size of the environment, and putting so muchinformation into the value ofMAKEFLAGS can exceed it. If yousee the error message ‘Arg list too long’, this may be the problem.(For strict compliance with POSIX.2, changingMAKEOVERRIDES doesnot affect MAKEFLAGS if the special target ‘.POSIX’ appearsin the makefile. You probably do not care about this.)

A similar variable MFLAGS exists also, for historicalcompatibility. It has the same value asMAKEFLAGS except that itdoes not contain the command line variable definitions, and it alwaysbegins with a hyphen unless it is empty (MAKEFLAGS begins with ahyphen only when it begins with an option that has no single-letterversion, such as ‘--warn-undefined-variables’). MFLAGS wastraditionally used explicitly in the recursive make command, likethis:

     subsystem:
             cd subdir && $(MAKE) $(MFLAGS)

but now MAKEFLAGS makes this usage redundant. If you want yourmakefiles to be compatible with oldmake programs, use thistechnique; it will work fine with more modernmake versions too.

TheMAKEFLAGS variable can also be useful if you want to havecertain options, such as ‘-k’ (seeSummary of Options), set each time you run make. You simply put a value forMAKEFLAGS in your environment. You can also setMAKEFLAGS ina makefile, to specify additional flags that should also be in effect forthat makefile. (Note that you cannot useMFLAGS this way. Thatvariable is set only for compatibility; make does not interpret avalue you set for it in any way.)

When make interprets the value of MAKEFLAGS (either from theenvironment or from a makefile), it first prepends a hyphen if the valuedoes not already begin with one. Then it chops the value into wordsseparated by blanks, and parses these words as if they were options givenon the command line (except that ‘-C’, ‘-f’, ‘-h’,‘-o’, ‘-W’, and their long-named versions are ignored; and thereis no error for an invalid option).

If you do put MAKEFLAGS in your environment, you should be sure notto include any options that will drastically affect the actions ofmake and undermine the purpose of makefiles and ofmakeitself. For instance, the ‘-t’, ‘-n’, and ‘-q’ options, ifput in one of these variables, could have disastrous consequences and wouldcertainly have at least surprising and probably annoying effects.

Previous:  Options/Recursion,Up:  Recursion

5.7.4 The ‘--print-directory’ Option

If you use several levels of recursivemake invocations, the‘-w’ or ‘--print-directory’ option can make the output alot easier to understand by showing each directory asmakestarts processing it and as make finishes processing it. Forexample, if ‘make -w’ is run in the directory/u/gnu/make,make will print a line of the form:

     make: Entering directory `/u/gnu/make'.

before doing anything else, and a line of the form:

     make: Leaving directory `/u/gnu/make'.

when processing is completed.

Normally, you do not need to specify this option because ‘make’does it for you: ‘-w’ is turned on automatically when you use the‘-C’ option, and in sub-makes.make will notautomatically turn on ‘-w’ if you also use ‘-s’, which says tobe silent, or if you use ‘--no-print-directory’ to explicitlydisable it.

Next:  ,Previous:  Recursion,Up:  Recipes

5.8 Defining Canned Recipes

When the same sequence of commands is useful in making varioustargets, you can define it as a canned sequence with the definedirective, and refer to the canned sequence from the recipes for thosetargets. The canned sequence is actually a variable, so the name mustnot conflict with other variable names.

Here is an example of defining a canned recipe:

     define run-yacc =
     yacc $(firstword $^)
     mv y.tab.c $@
     endef

Here run-yacc is the name of the variable being defined;endef marks the end of the definition; the lines in between are thecommands. Thedefine directive does not expand variable referencesand function calls in the canned sequence; the ‘$’ characters,parentheses, variable names, and so on, all become part of the value of thevariable you are defining. See Defining Multi-Line Variables,for a complete explanation ofdefine.

The first command in this example runs Yacc on the first prerequisite ofwhichever rule uses the canned sequence. The output file from Yacc isalways namedy.tab.c. The second command moves the output to therule's target file name.

To use the canned sequence, substitute the variable into the recipe of arule. You can substitute it like any other variable(seeBasics of Variable References). Because variables defined bydefine are recursively expandedvariables, all the variable references you wrote inside thedefineare expanded now. For example:

     foo.c : foo.y
             $(run-yacc)

‘foo.y’ will be substituted for the variable ‘$^’ when it occurs inrun-yacc's value, and ‘foo.c’ for ‘$@’.

This is a realistic example, but this particular one is not needed inpractice becausemake has an implicit rule to figure out thesecommands based on the file names involved(seeUsing Implicit Rules).

In recipe execution, each line of a canned sequence is treated just asif the line appeared on its own in the rule, preceded by a tab. Inparticular,make invokes a separate subshell for each line. Youcan use the special prefix characters that affect command lines(‘@’, ‘-’, and ‘+’) on each line of a canned sequence. See Writing Recipes in Rules. For example, using this canned sequence:

     define frobnicate =
     @echo "frobnicating target $@"
     frob-step-1 $< -o $@-step-1
     frob-step-2 $@-step-1 -o $@
     endef

make will not echo the first line, the echo command. But itwill echo the following two recipe lines.

On the other hand, prefix characters on the recipe line that refers toa canned sequence apply to every line in the sequence. So the rule:

     frob.out: frob.in
             @$(frobnicate)

does not echo any recipe lines. (See Recipe Echoing, for a full explanation of ‘@’.)

Previous:  Canned Recipes,Up:  Recipes

5.9 Using Empty Recipes

It is sometimes useful to define recipes which do nothing. This is donesimply by giving a recipe that consists of nothing but whitespace. Forexample:

     target: ;

defines an empty recipe for target. You could also use a linebeginning with a recipe prefix character to define an empty recipe,but this would be confusing because such a line looks empty.

You may be wondering why you would want to define a recipe thatdoes nothing. The only reason this is useful is to prevent a targetfrom getting implicit recipes (from implicit rules or the.DEFAULT special target; see Implicit Rules andsee Defining Last-Resort Default Rules).

You may be inclined to define empty recipes for targets that arenot actual files, but only exist so that their prerequisites can beremade. However, this is not the best way to do that, because theprerequisites may not be remade properly if the target file actually does exist. See Phony Targets, for a better way to do this.

Next:  ,Previous:  Recipes,Up:  Top

6 How to Use Variables

Avariable is a name defined in a makefile to represent a stringof text, called the variable'svalue. These values aresubstituted by explicit request into targets, prerequisites, recipes,and other parts of the makefile. (In some other versions ofmake,variables are called macros.) Variables and functions in all parts of a makefile are expanded whenread, except for in recipes, the right-hand sides of variabledefinitions using ‘=’, and the bodies of variable definitionsusing thedefine directive.

Variables can represent lists of file names, options to pass to compilers,programs to run, directories to look in for source files, directories towrite output in, or anything else you can imagine.

A variable name may be any sequence of characters not containing ‘:’,‘#’, ‘=’, or leading or trailing whitespace. However,variable names containing characters other than letters, numbers, andunderscores should be avoided, as they may be given special meanings in thefuture, and with some shells they cannot be passed through the environment to asub-make(seeCommunicating Variables to a Sub-make).

Variable names are case-sensitive. The names ‘foo’, ‘FOO’,and ‘Foo’ all refer to different variables.

It is traditional to use upper case letters in variable names, but werecommend using lower case letters for variable names that serve internalpurposes in the makefile, and reserving upper case for parameters thatcontrol implicit rules or for parameters that the user should override withcommand options (see Overriding Variables).

A few variables have names that are a single punctuation character orjust a few characters. These are theautomatic variables, andthey have particular specialized uses. See Automatic 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.

Next:  ,Previous:  Using Variables,Up:  Using Variables

6.1 Basics of Variable References

To substitute a variable's value, write a dollar sign followed by the nameof the variable in parentheses or braces: either ‘$(foo)’ or‘${foo}’ is a valid reference to the variablefoo. Thisspecial significance of ‘$’ is why you must write ‘$$’ to havethe effect of a single dollar sign in a file name or recipe.

Variable references can be used in any context: targets, prerequisites,recipes, most directives, and new variable values. Here is anexample of a common case, where a variable holds the names of all theobject files in a program:

     objects = program.o foo.o utils.o
     program : $(objects)
             cc -o program $(objects)
     
     $(objects) : defs.h

Variable references work by strict textual substitution. Thus, the rule

     foo = c
     prog.o : prog.$(foo)
             $(foo)$(foo) -$(foo) prog.$(foo)

could be used to compile a C program prog.c. Since spaces beforethe variable value are ignored in variable assignments, the value offoo is precisely ‘c’. (Don't actually write your makefilesthis way!)

A dollar sign followed by a character other than a dollar sign,open-parenthesis or open-brace treats that single character as thevariable name. Thus, you could reference the variablex with‘$x’. However, this practice is strongly discouraged, except inthe case of the automatic variables (seeAutomatic Variables).

Next:  ,Previous:  Reference,Up:  Using Variables

6.2 The Two Flavors of Variables

There are two ways that a variable in GNU make can have a value;we call them the twoflavors of variables. The two flavors aredistinguished in how they are defined and in what they do when expanded.

The first flavor of variable is a recursively expanded variable. Variables of this sort are defined by lines using ‘=’(seeSetting Variables) or by the define directive(seeDefining Multi-Line Variables). The value you specifyis installed verbatim; if it contains references to other variables,these references are expanded whenever this variable is substituted (inthe course of expanding some other string). When this happens, it iscalled recursive expansion.

For example,

     foo = $(bar)
     bar = $(ugh)
     ugh = Huh?
     
     all:;echo $(foo)

will echo ‘Huh?’: ‘$(foo)’ expands to ‘$(bar)’ whichexpands to ‘$(ugh)’ which finally expands to ‘Huh?’.

This flavor of variable is the only sort supported by other versions ofmake. It has its advantages and its disadvantages. An advantage(most would say) is that:

     CFLAGS = $(include_dirs) -O
     include_dirs = -Ifoo -Ibar

will do what was intended: when ‘CFLAGS’ is expanded in a recipe,it will expand to ‘-Ifoo -Ibar -O’. A major disadvantage is that youcannot append something on the end of a variable, as in

     CFLAGS = $(CFLAGS) -O

because it will cause an infinite loop in the variable expansion. (Actuallymake detects the infinite loop and reports an error.) Another disadvantage is that any functions(seeFunctions for Transforming Text)referenced in the definition will be executed every time the variable isexpanded. This makesmake run slower; worse, it causes thewildcard and shell functions to give unpredictable resultsbecause you cannot easily control when they are called, or even how manytimes.

To avoid all the problems and inconveniences of recursively expandedvariables, there is another flavor: simply expanded variables.

Simply expanded variables are defined by lines using ‘:=’(seeSetting Variables). The value of a simply expanded variable is scannedonce and for all, expanding any references to other variables andfunctions, when the variable is defined. The actual value of the simplyexpanded variable is the result of expanding the text that you write. It does not contain any references to other variables; it contains theirvaluesas of the time this variable was defined. Therefore,

     x := foo
     y := $(x) bar
     x := later

is equivalent to

     y := foo bar
     x := later

When a simply expanded variable is referenced, its value is substitutedverbatim.

Here is a somewhat more complicated example, illustrating the use of‘:=’ in conjunction with theshell function. (See The shell Function.) This examplealso shows use of the variableMAKELEVEL, which is changedwhen it is passed down from level to level. (SeeCommunicating Variables to a Sub-make, for information aboutMAKELEVEL.) 

     ifeq (0,${MAKELEVEL})
     whoami    := $(shell whoami)
     host-type := $(shell arch)
     MAKE := ${MAKE} host-type=${host-type} whoami=${whoami}
     endif

An advantage of this use of ‘:=’ is that a typical`descend into a directory' recipe then looks like this:

     ${subdirs}:
             ${MAKE} -C $@ all

Simply expanded variables generally make complicated makefile programmingmore predictable because they work like variables in most programminglanguages. They allow you to redefine a variable using its own value (orits value processed in some way by one of the expansion functions) and touse the expansion functions much more efficiently(seeFunctions for Transforming Text).

You can also use them to introduce controlled leading whitespace intovariable values. Leading whitespace characters are discarded from yourinput before substitution of variable references and function calls;this means you can include leading spaces in a variable value byprotecting them with variable references, like this:

     nullstring :=
     space := $(nullstring) # end of the line

Here the value of the variable space is precisely one space. Thecomment ‘# end of the line’ is included here just for clarity. Since trailing space characters arenot stripped from variablevalues, just a space at the end of the line would have the same effect(but be rather hard to read). If you put whitespace at the end of avariable value, it is a good idea to put a comment like that at the endof the line to make your intent clear. Conversely, if you do notwant any whitespace characters at the end of your variable value, youmust remember not to put a random comment on the end of the line aftersome whitespace, such as this:

     dir := /foo/bar    # directory to put the frobs in

Here the value of the variable dir is ‘/foo/bar    ’(with four trailing spaces), which was probably not the intention. (Imagine something like ‘$(dir)/file’ with this definition!)

There is another assignment operator for variables, ‘?=’. Thisis called a conditional variable assignment operator, because it onlyhas an effect if the variable is not yet defined. This statement:

     FOO ?= bar

is exactly equivalent to this(see The origin Function):

     ifeq ($(origin FOO), undefined)
       FOO = bar
     endif

Note that a variable set to an empty value is still defined, so‘?=’ will not set that variable.

Next:  ,Previous:  Flavors,Up:  Using Variables

6.3 Advanced Features for Reference to Variables

This section describes some advanced features you can use to referencevariables in more flexible ways.

Next:  ,Previous:  Advanced,Up:  Advanced

6.3.1 Substitution References

Asubstitution reference substitutes the value of a variable withalterations that you specify. It has the form‘$(var:a=b)’ (or‘${var:a=b}’) and its meaning is to take the valueof the variablevar, replace every a at the end of a word withb in that value, and substitute the resulting string.

When we say “at the end of a word”, we mean that a must appeareither followed by whitespace or at the end of the value in order to bereplaced; other occurrences ofa in the value are unaltered. Forexample:

     foo := a.o b.o c.o
     bar := $(foo:.o=.c)

sets ‘bar’ to ‘a.c b.c c.c’. SeeSetting Variables.

A substitution reference is actually an abbreviation for use of thepatsubst expansion function (seeFunctions for String Substitution and Analysis). We providesubstitution references as well aspatsubst for compatibility withother implementations of make.

Another type of substitution reference lets you use the full power ofthepatsubst function. It has the same form‘$(var:a=b)’ described above, except that nowa must contain a single ‘%’ character. This case isequivalent to ‘$(patsubsta,b,$(var))’. SeeFunctions for String Substitution and Analysis,for a description of thepatsubst function.

For example:

     
     foo := a.o b.o c.o
     bar := $(foo:%.o=%.c)

sets ‘bar’ to ‘a.c b.c c.c’.

Previous:  Substitution Refs,Up:  Advanced

6.3.2 Computed Variable Names

Computed variable names are a complicated concept needed only forsophisticated makefile programming. For most purposes you need notconsider them, except to know that making a variable with a dollar signin its name might have strange results. However, if you are the typethat wants to understand everything, or you are actually interested inwhat they do, read on.

Variables may be referenced inside the name of a variable. This iscalled a computed variable name or a nested variablereference. For example,

     x = y
     y = z
     a := $($(x))

defines a as ‘z’: the ‘$(x)’ inside ‘$($(x))’ expandsto ‘y’, so ‘$($(x))’ expands to ‘$(y)’ which in turn expandsto ‘z’. Here the name of the variable to reference is not statedexplicitly; it is computed by expansion of ‘$(x)’. The reference‘$(x)’ here is nested within the outer variable reference.

The previous example shows two levels of nesting, but any number of levelsis possible. For example, here are three levels:

     x = y
     y = z
     z = u
     a := $($($(x)))

Here the innermost ‘$(x)’ expands to ‘y’, so ‘$($(x))’expands to ‘$(y)’ which in turn expands to ‘z’; now we have‘$(z)’, which becomes ‘u’.

References to recursively-expanded variables within a variable name arereexpanded in the usual fashion. For example:

     x = $(y)
     y = z
     z = Hello
     a := $($(x))

defines a as ‘Hello’: ‘$($(x))’ becomes ‘$($(y))’which becomes ‘$(z)’ which becomes ‘Hello’.

Nested variable references can also contain modified references andfunction invocations (seeFunctions for Transforming Text),just like any other reference. For example, using thesubst function(see Functions for String Substitution and Analysis):

     x = variable1
     variable2 := Hello
     y = $(subst 1,2,$(x))
     z = y
     a := $($($(z)))

eventually defines a as ‘Hello’. It is doubtful that anyonewould ever want to write a nested reference as convoluted as this one, butit works: ‘$($($(z)))’ expands to ‘$($(y))’ which becomes‘$($(subst 1,2,$(x)))’. This gets the value ‘variable1’ fromx and changes it by substitution to ‘variable2’, so that theentire string becomes ‘$(variable2)’, a simple variable referencewhose value is ‘Hello’.

A computed variable name need not consist entirely of a single variablereference. It can contain several variable references, as well as someinvariant text. For example,

     a_dirs := dira dirb
     1_dirs := dir1 dir2
     
     a_files := filea fileb
     1_files := file1 file2
     
     ifeq "$(use_a)" "yes"
     a1 := a
     else
     a1 := 1
     endif
     
     ifeq "$(use_dirs)" "yes"
     df := dirs
     else
     df := files
     endif
     
     dirs := $($(a1)_$(df))

will give dirs the same value as a_dirs,1_dirs,a_files or 1_files depending on the settings ofuse_aand use_dirs.

Computed variable names can also be used in substitution references:

     a_objects := a.o b.o c.o
     1_objects := 1.o 2.o 3.o
     
     sources := $($(a1)_objects:.o=.c)

defines sources as either ‘a.c b.c c.c’ or ‘1.c 2.c 3.c’,depending on the value ofa1.

The only restriction on this sort of use of nested variable referencesis that they cannot specify part of the name of a function to be called. This is because the test for a recognized function name is done beforethe expansion of nested references. For example,

     ifdef do_sort
     func := sort
     else
     func := strip
     endif
     
     bar := a d b g q c
     
     foo := $($(func) $(bar))

attempts to give ‘foo’ the value of the variable ‘sort a d b gq c’ or ‘strip a d b g q c’, rather than giving ‘a d b g q c’as the argument to either the sort or the strip function. This restriction could be removed in the future if that change is shownto be a good idea.

You can also use computed variable names in the left-hand side of avariable assignment, or in adefine directive, as in:

     dir = foo
     $(dir)_sources := $(wildcard $(dir)/*.c)
     define $(dir)_print =
     lpr $($(dir)_sources)
     endef

This example defines the variables ‘dir’, ‘foo_sources’, and‘foo_print’.

Note that nested variable references are quite different fromrecursively expanded variables(seeThe Two Flavors of Variables), though both areused together in complex ways when doing makefile programming.

Next:  ,Previous:  Advanced,Up:  Using Variables

6.4 How Variables Get Their Values

Variables can get values in several different ways:

Next:  ,Previous:  Values,Up:  Using Variables

6.5 Setting Variables

To set a variable from the makefile, write a line starting with thevariable name followed by ‘=’ or ‘:=’. Whatever follows the‘=’ or ‘:=’ on the line becomes the value. For example,

     objects = main.o foo.o bar.o utils.o

defines a variable named objects. Whitespace around the variablename and immediately after the ‘=’ is ignored.

Variables defined with ‘=’ are recursively expanded variables. Variables defined with ‘:=’ aresimply expanded variables; thesedefinitions can contain variable references which will be expanded beforethe definition is made. SeeThe Two Flavors of Variables.

The variable name may contain function and variable references, whichare expanded when the line is read to find the actual variable name to use.

There is no limit on the length of the value of a variable except theamount of swapping space on the computer. When a variable definition islong, it is a good idea to break it into several lines by insertingbackslash-newline at convenient places in the definition. This will notaffect the functioning of make, but it will make the makefile easierto read.

Most variable names are considered to have the empty string as a value ifyou have never set them. Several variables have built-in initial valuesthat are not empty, but you can set them in the usual ways(seeVariables Used by Implicit Rules). Several special variables are setautomatically to a new value for each rule; these are called theautomatic variables (seeAutomatic Variables).

If you'd like a variable to be set to a value only if it's not alreadyset, then you can use the shorthand operator ‘?=’ instead of‘=’. These two settings of the variable ‘FOO’ are identical(see The origin Function):

     FOO ?= bar

and

     ifeq ($(origin FOO), undefined)
     FOO = bar
     endif

Next:  ,Previous:  Setting,Up:  Using Variables

6.6 Appending More Text to Variables

Often it is useful to add more text to the value of a variable already defined. You do this with a line containing ‘+=’, like this:

     objects += another.o

This takes the value of the variable objects, and adds the text‘another.o’ to it (preceded by a single space). Thus:

     objects = main.o foo.o bar.o utils.o
     objects += another.o

sets objects to ‘main.o foo.o bar.o utils.o another.o’.

Using ‘+=’ is similar to:

     objects = main.o foo.o bar.o utils.o
     objects := $(objects) another.o

but differs in ways that become important when you use more complex values.

When the variable in question has not been defined before, ‘+=’acts just like normal ‘=’: it defines a recursively-expandedvariable. However, when thereis a previous definition, exactlywhat ‘+=’ does depends on what flavor of variable you definedoriginally. SeeThe Two Flavors of Variables, for anexplanation of the two flavors of variables.

When you add to a variable's value with ‘+=’,make actsessentially as if you had included the extra text in the initialdefinition of the variable. If you defined it first with ‘:=’,making it a simply-expanded variable, ‘+=’ adds to thatsimply-expanded definition, and expands the new text before appending itto the old value just as ‘:=’ does(seeSetting Variables, for a full explanation of ‘:=’). In fact,

     variable := value
     variable += more

is exactly equivalent to:

     variable := value
     variable := $(variable) more

On the other hand, when you use ‘+=’ with a variable that you definedfirst to be recursively-expanded using plain ‘=’,make doessomething a bit different. Recall that when you define arecursively-expanded variable,make does not expand the value you setfor variable and function references immediately. Instead it stores the textverbatim, and saves these variable and function references to be expandedlater, when you refer to the new variable (seeThe Two Flavors of Variables). When you use ‘+=’ on a recursively-expanded variable,it is this unexpanded text to whichmake appends the new text youspecify.

     variable = value
     variable += more

is roughly equivalent to:

     temp = value
     variable = $(temp) more

except that of course it never defines a variable called temp. The importance of this comes when the variable's old value containsvariable references. Take this common example:

     CFLAGS = $(includes) -O
     ...
     CFLAGS += -pg # enable profiling

The first line defines the CFLAGS variable with a reference to anothervariable,includes. (CFLAGS is used by the rules for Ccompilation; seeCatalogue of Implicit Rules.) Using ‘=’ for the definition makesCFLAGS a recursively-expandedvariable, meaning ‘$(includes) -O’ isnot expanded whenmake processes the definition of CFLAGS. Thus,includesneed not be defined yet for its value to take effect. It only has to bedefined before any reference toCFLAGS. If we tried to append to thevalue of CFLAGS without using ‘+=’, we might do it like this:

     CFLAGS := $(CFLAGS) -pg # enable profiling

This is pretty close, but not quite what we want. Using ‘:=’redefinesCFLAGS as a simply-expanded variable; this meansmake expands the text ‘$(CFLAGS) -pg’ before setting thevariable. Ifincludes is not yet defined, we get ‘ -O -pg’, and a later definition ofincludes will have no effect. Conversely, by using ‘+=’ we setCFLAGS to theunexpanded value ‘$(includes) -O -pg’. Thus we preservethe reference toincludes, so if that variable gets defined atany later point, a reference like ‘$(CFLAGS)’ still uses itsvalue.

Next:  ,Previous:  Appending,Up:  Using Variables

6.7 The override Directive

If a variable has been set with a command argument(seeOverriding Variables),then ordinary assignments in the makefile are ignored. If you want to setthe variable in the makefile even though it was set with a commandargument, you can use anoverride directive, which is a line thatlooks like this:

     override variable = value

or

     override variable := value

To append more text to a variable defined on the command line, use:

     override variable += more text

See Appending More Text to Variables.

Variable assignments marked with the override flag have ahigher priority than all other assignments, except anotheroverride. Subsequent assignments or appends to this variablewhich are not markedoverride will be ignored.

The override directive was not invented for escalation in the warbetween makefiles and command arguments. It was invented so you can alterand add to values that the user specifies with command arguments.

For example, suppose you always want the ‘-g’ switch when you run theC compiler, but you would like to allow the user to specify the otherswitches with a command argument just as usual. You could use thisoverride directive:

     override CFLAGS += -g

You can also use override directives with define directives. This is done as you might expect:

     override define foo =
     bar
     endef

See Defining Multi-Line Variables.

Next:  ,Previous:  Override Directive,Up:  Using Variables

6.8 Defining Multi-Line Variables

Another way to set the value of a variable is to use the definedirective. This directive has an unusual syntax which allows newlinecharacters to be included in the value, which is convenient fordefining both canned sequences of commands (seeDefining Canned Recipes), and also sections of makefile syntax touse witheval (see Eval Function).

The define directive is followed on the same line by the nameof the variable being defined and an (optional) assignment operator,and nothing more. The value to give the variable appears on thefollowing lines. The end of the value is marked by a line containingjust the word endef. Aside from this difference in syntax,define works just like any other variable definition. Thevariable name may contain function and variable references, which areexpanded when the directive is read to find the actual variable nameto use.

You may omit the variable assignment operator if you prefer. Ifomitted, make assumes it to be ‘=’ and creates arecursively-expanded variable (seeThe Two Flavors of Variables). When using a ‘+=’ operator, the value is appended to the previousvalue as with any other append operation: with a single spaceseparating the old and new values.

You may nest define directives: make will keep track ofnested directives and report an error if they are not all properlyclosed withendef. Note that lines beginning with the recipeprefix character are considered part of a recipe, so anydefineor endef strings appearing on such a line will not beconsideredmake directives.

     define two-lines =
     echo foo
     echo $(bar)
     endef

The value in an ordinary assignment cannot contain a newline; but thenewlines that separate the lines of the value in adefine becomepart of the variable's value (except for the final newline which precedestheendef and is not considered part of the value).

When used in a recipe, the previous example is functionally equivalentto this:

     two-lines = echo foo; echo $(bar)

since two commands separated by semicolon behave much like two separateshell commands. However, note that using two separate lines meansmake will invoke the shell twice, running an independent subshellfor each line. SeeRecipe Execution.

If you want variable definitions made with define to takeprecedence over command-line variable definitions, you can use theoverride directive together withdefine:

     override define two-lines =
     foo
     $(bar)
     endef

See The override Directive.

Next:  ,Previous:  Multi-Line,Up:  Using Variables

6.9 Undefining Variables

If you want to clear a variable, setting its value to empty is usuallysufficient. Expanding such a variable will yield the same result (emptystring) regardless of whether it was set or not. However, if you areusing the flavor (see Flavor Function) andorigin (see Origin Function) functions, there is a differencebetween a variable that was never set and a variable with an empty value. In such situations you may want to use theundefine directive tomake a variable appear as if it was never set. For example:

     foo := foo
     bar = bar
     
     undefine foo
     undefine bar
     
     $(info $(origin foo))
     $(info $(flavor bar))

This example will print “undefined” for both variables.

If you want to undefine a command-line variable definition, you can usethe override directive together with undefine, similar tohow this is done for variable definitions:

     override undefine CFLAGS

Next:  ,Previous:  Undefine Directive,Up:  Using Variables

6.10 Variables from the Environment

Variables inmake can come from the environment in whichmake is run. Every environment variable thatmake seeswhen it starts up is transformed into a make variable with thesame name and value. However, an explicit assignment in the makefile,or with a command argument, overrides the environment. (If the‘-e’ flag is specified, then values from the environment overrideassignments in the makefile. SeeSummary of Options. But this is not recommended practice.)

Thus, by setting the variable CFLAGS in your environment, you cancause all C compilations in most makefiles to use the compiler switches youprefer. This is safe for variables with standard or conventional meaningsbecause you know that no makefile will use them for other things. (Notethis is not totally reliable; some makefiles setCFLAGS explicitlyand therefore are not affected by the value in the environment.)

When make runs a recipe, variables defined in themakefile are placed into the environment of each shell. This allowsyou to pass values to sub-make invocations (seeRecursive Use of make). By default, only variables that camefrom the environment or the command line are passed to recursiveinvocations. You can use theexport directive to pass othervariables. See Communicating Variables to a Sub-make, for full details.

Other use of variables from the environment is not recommended. It is notwise for makefiles to depend for their functioning on environment variablesset up outside their control, since this would cause different users to getdifferent results from the same makefile. This is against the wholepurpose of most makefiles.

Such problems would be especially likely with the variableSHELL, which is normally present in the environment to specifythe user's choice of interactive shell. It would be very undesirablefor this choice to affect make; so, make handles theSHELL environment variable in a special way; seeChoosing the Shell.

Next:  ,Previous:  Environment,Up:  Using Variables

6.11 Target-specific Variable Values

Variable values inmake are usually global; that is, they are thesame regardless of where they are evaluated (unless they're reset, ofcourse). One exception to that is automatic variables(seeAutomatic Variables).

The other exception is target-specific variable values. Thisfeature allows you to define different values for the same variable,based on the target thatmake is currently building. As withautomatic variables, these values are only available within the contextof a target's recipe (and in other target-specific assignments).

Set a target-specific variable value like this:

     target ... : variable-assignment

Target-specific variable assignments can be prefixed with any or all of thespecial keywordsexport, override, or private;these apply their normal behavior to this instance of the variable only.

Multiple target values create a target-specific variable value foreach member of the target list individually.

The variable-assignment can be any valid form of assignment;recursive (‘=’), static (‘:=’), appending (‘+=’), orconditional (‘?=’). All variables that appear within thevariable-assignment are evaluated within the context of thetarget: thus, any previously-defined target-specific variable valueswill be in effect. Note that this variable is actually distinct fromany “global” value: the two variables do not have to have the sameflavor (recursive vs. static).

Target-specific variables have the same priority as any other makefilevariable. Variables provided on the command line (and in theenvironment if the ‘-e’ option is in force) will take precedence. Specifying theoverride directive will allow the target-specificvariable value to be preferred.

There is one more special feature of target-specific variables: whenyou define a target-specific variable that variable value is also ineffect for all prerequisites of this target, and all theirprerequisites, etc. (unless those prerequisites override that variablewith their own target-specific variable value). So, for example, astatement like this:

     prog : CFLAGS = -g
     prog : prog.o foo.o bar.o

will set CFLAGS to ‘-g’ in the recipe forprog, butit will also set CFLAGS to ‘-g’ in the recipes that createprog.o,foo.o, and bar.o, and any recipes whichcreate their prerequisites.

Be aware that a given prerequisite will only be built once perinvocation of make, at most. If the same file is a prerequisite ofmultiple targets, and each of those targets has a different value forthe same target-specific variable, then the first target to be builtwill cause that prerequisite to be built and the prerequisite willinherit the target-specific value from the first target. It willignore the target-specific values from any other targets.

Next:  ,Previous:  Target-specific,Up:  Using Variables

6.12 Pattern-specific Variable Values

In addition to target-specific variable values(seeTarget-specific Variable Values), GNUmake supports pattern-specific variable values. In this form,the variable is defined for any target that matches the patternspecified.

Set a pattern-specific variable value like this:

     pattern ... : variable-assignment

where pattern is a %-pattern. As with target-specific variablevalues, multiplepattern values create a pattern-specific variablevalue for each pattern individually. Thevariable-assignment canbe any valid form of assignment. Any command line variable setting willtake precedence, unlessoverride is specified.

For example:

     %.o : CFLAGS = -O

will assign CFLAGS the value of ‘-O’ for all targetsmatching the pattern%.o.

If a target matches more than one pattern, the matching pattern-specificvariables with longer stems are interpreted first. This results in morespecific variables taking precedence over the more generic ones, forexample:

     %.o: %.c
             $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@
     
     lib/%.o: CFLAGS := -fPIC -g
     %.o: CFLAGS := -g
     
     all: foo.o lib/bar.o

In this example the first definition of the CFLAGS variablewill be used to updatelib/bar.o even though the second onealso applies to this target. Pattern-specific variables which resultin the same stem length are considered in the order in which theywere defined in the makefile.

Pattern-specific variables are searched after any target-specificvariables defined explicitly for that target, and before target-specificvariables defined for the parent target.

Next:  ,Previous:  Pattern-specific,Up:  Using Variables

6.13 Suppressing Inheritance

As described in previous sections,make variables are inheritedby prerequisites. This capability allows you to modify the behaviorof a prerequisite based on which targets caused it to be rebuilt. Forexample, you might set a target-specific variable on adebugtarget, then running ‘make debug’ will cause that variable to beinherited by all prerequisites ofdebug, while just running‘make all’ (for example) would not have that assignment.

Sometimes, however, you may not want a variable to be inherited. Forthese situations,make provides the private modifier. Although this modifier can be used with any variable assignment, itmakes the most sense with target- and pattern-specific variables. Anyvariable markedprivate will be visible to its local target butwill not be inherited by prerequisites of that target. A globalvariable markedprivate will be visible in the global scope butwill not be inherited by any target, and hence will not be visiblein any recipe.

As an example, consider this makefile:

     EXTRA_CFLAGS =
     
     prog: private EXTRA_CFLAGS = -L/usr/local/lib
     prog: a.o b.o

Due to the private modifier, a.o and b.o will notinherit theEXTRA_CFLAGS variable assignment from theprogs target.

Previous:  Suppressing Inheritance,Up:  Using Variables

6.14 Other Special Variables

GNUmake supports some variables that have special properties.

MAKEFILE_LIST
Contains the name of each makefile that is parsed by make, inthe order in which it was parsed. The name is appended justbefore make begins to parse the makefile. Thus, if the firstthing a makefile does is examine the last word in this variable, itwill be the name of the current makefile. Once the current makefilehas used include, however, the last word will be thejust-included makefile.

If a makefile named Makefile has this content: 

          name1 := $(lastword $(MAKEFILE_LIST))
          
          include inc.mk
          
          name2 := $(lastword $(MAKEFILE_LIST))
          
          all:
                  @echo name1 = $(name1)
                  @echo name2 = $(name2)

then you would expect to see this output: 

          name1 = Makefile
          name2 = inc.mk


.DEFAULT_GOAL
Sets the default goal to be used if no targets were specified on thecommand line (see Arguments to Specify the Goals). The .DEFAULT_GOAL variable allows you to discover the currentdefault goal, restart the default goal selection algorithm by clearingits value, or to explicitly set the default goal. The followingexample illustrates these cases: 
          # Query the default goal.
          ifeq ($(.DEFAULT_GOAL),)
            $(warning no default goal is set)
          endif
          
          .PHONY: foo
          foo: ; @echo $@
          
          $(warning default goal is $(.DEFAULT_GOAL))
          
          # Reset the default goal.
          .DEFAULT_GOAL :=
          
          .PHONY: bar
          bar: ; @echo $@
          
          $(warning default goal is $(.DEFAULT_GOAL))
          
          # Set our own.
          .DEFAULT_GOAL := foo

This makefile prints: 

          no default goal is set
          default goal is foo
          default goal is bar
          foo

Note that assigning more than one target name to .DEFAULT_GOAL isillegal and will result in an error.


MAKE_RESTARTS
This variable is set only if this instance of make hasrestarted (see How Makefiles Are Remade): itwill contain the number of times this instance has restarted. Notethis is not the same as recursion (counted by the MAKELEVELvariable). You should not set, modify, or export this variable.


.RECIPEPREFIX
The first character of the value of this variable is used as thecharacter make assumes is introducing a recipe line. If the variableis empty (as it is by default) that character is the standard tabcharacter. For example, this is a valid makefile: 
          .RECIPEPREFIX = >
          all:
          > @echo Hello, world

The value of .RECIPEPREFIX can be changed multiple times; once setit stays in effect for all rules parsed until it is modified.


.VARIABLES
Expands to a list of the names of all global variables definedso far. This includes variables which have empty values, as well asbuilt-in variables (see Variables Used by Implicit Rules), but does not include any variables which are onlydefined in a target-specific context. Note that any value you assignto this variable will be ignored; it will always return its specialvalue.


.FEATURES
Expands to a list of special features supported by this version of make. Possible values include:
‘ archives’
Supports ar (archive) files using special filename syntax. See Using make to Update Archive Files.
‘ check-symlink’
Supports the -L ( --check-symlink-times) flag. See Summary of Options.
‘ else-if’
Supports “else if” non-nested conditionals. See Syntax of Conditionals.
‘ jobserver’
Supports “job server” enhanced parallel builds. See Parallel Execution.
‘ second-expansion’
Supports secondary expansion of prerequisite lists.
‘ order-only’
Supports order-only prerequisites. See Types of Prerequisites.
‘ target-specific’
Supports target-specific and pattern-specific variable assignments. See Target-specific Variable Values.


.INCLUDE_DIRS
Expands to a list of directories that make searches forincluded makefiles (see Including Other Makefiles).

Next:  ,Previous:  Using Variables,Up:  Top

7 Conditional Parts of Makefiles

A conditional directive causes part of a makefile to be obeyedor ignored depending on the values of variables. Conditionals cancompare the value of one variable to another, or the value of avariable to a constant string. Conditionals control what makeactually “sees” in the makefile, so theycannot be used tocontrol recipes at the time of execution.

Next:  ,Previous:  Conditionals,Up:  Conditionals

7.1 Example of a Conditional

The following example of a conditional tells make to use oneset of libraries if theCC variable is ‘gcc’, and adifferent set of libraries otherwise. It works by controlling whichof two recipe lines will be used for the rule. The result is that‘CC=gcc’ as an argument to make changes not only whichcompiler is used but also which libraries are linked.

     libs_for_gcc = -lgnu
     normal_libs =
     
     foo: $(objects)
     ifeq ($(CC),gcc)
             $(CC) -o foo $(objects) $(libs_for_gcc)
     else
             $(CC) -o foo $(objects) $(normal_libs)
     endif

This conditional uses three directives: one ifeq, one elseand oneendif.

The ifeq directive begins the conditional, and specifies thecondition. It contains two arguments, separated by a comma and surroundedby parentheses. Variable substitution is performed on both arguments andthen they are compared. The lines of the makefile following theifeq are obeyed if the two arguments match; otherwise they areignored.

The else directive causes the following lines to be obeyed if theprevious conditional failed. In the example above, this means that thesecond alternative linking command is used whenever the first alternativeis not used. It is optional to have an else in a conditional.

The endif directive ends the conditional. Every conditional mustend with anendif. Unconditional makefile text follows.

As this example illustrates, conditionals work at the textual level:the lines of the conditional are treated as part of the makefile, orignored, according to the condition. This is why the larger syntacticunits of the makefile, such as rules, may cross the beginning or theend of the conditional.

When the variable CC has the value ‘gcc’, the above example hasthis effect:

     foo: $(objects)
             $(CC) -o foo $(objects) $(libs_for_gcc)

When the variable CC has any other value, the effect is this:

     foo: $(objects)
             $(CC) -o foo $(objects) $(normal_libs)

Equivalent results can be obtained in another way by conditionalizing avariable assignment and then using the variable unconditionally:

     libs_for_gcc = -lgnu
     normal_libs =
     
     ifeq ($(CC),gcc)
       libs=$(libs_for_gcc)
     else
       libs=$(normal_libs)
     endif
     
     foo: $(objects)
             $(CC) -o foo $(objects) $(libs)

Next:  ,Previous:  Conditional Example,Up:  Conditionals

7.2 Syntax of Conditionals

The syntax of a simple conditional with noelse is as follows:

     conditional-directive
     text-if-true
     endif

The text-if-true may be any lines of text, to be considered as partof the makefile if the condition is true. If the condition is false, notext is used instead.

The syntax of a complex conditional is as follows:

     conditional-directive
     text-if-true
     else
     text-if-false
     endif

or:

     conditional-directive
     text-if-one-is-true
     else conditional-directive
     text-if-true
     else
     text-if-false
     endif

There can be as many “else conditional-directive”clauses as necessary. Once a given condition is true,text-if-true is used and no other clause is used; if nocondition is true thentext-if-false is used. Thetext-if-true and text-if-false can be any number of linesof text.

The syntax of the conditional-directive is the same whether theconditional is simple or complex; after anelse or not. Thereare four different directives that test different conditions. Here isa table of them:

ifeq ( arg1 , arg2 ) ifeq ' arg1 ' ' arg2 ' ifeq " arg1 " " arg2 " ifeq " arg1 " ' arg2 ' ifeq ' arg1 ' " arg2 "
Expand all variable references in arg1 and arg2 andcompare them. If they are identical, the text-if-true iseffective; otherwise, the text-if-false, if any, is effective.

Often you want to test if a variable has a non-empty value. When thevalue results from complex expansions of variables and functions,expansions you would consider empty may actually contain whitespacecharacters and thus are not seen as empty. However, you can use thestrip function (see Text Functions) to avoid interpretingwhitespace as a non-empty value. For example:

          ifeq ($(strip $(foo)),)
          text-if-empty
          endif

will evaluate text-if-empty even if the expansion of$(foo) contains whitespace characters.

ifneq ( arg1 , arg2 ) ifneq ' arg1 ' ' arg2 ' ifneq " arg1 " " arg2 " ifneq " arg1 " ' arg2 ' ifneq ' arg1 ' " arg2 "
Expand all variable references in arg1 and arg2 andcompare them. If they are different, the text-if-true iseffective; otherwise, the text-if-false, if any, is effective.
ifdef variable-name
The ifdef form takes the name of a variable as itsargument, not a reference to a variable. The value of that variablehas a non-empty value, the text-if-true is effective; otherwise,the text-if-false, if any, is effective. Variables that havenever been defined have an empty value. The text variable-nameis expanded, so it could be a variable or function that expandsto the name of a variable. For example: 
          bar = true
          foo = bar
          ifdef $(foo)
          frobozz = yes
          endif

The variable reference $(foo) is expanded, yielding bar,which is considered to be the name of a variable. The variablebar is not expanded, but its value is examined to determine ifit is non-empty.

Note that ifdef only tests whether a variable has a value. Itdoes not expand the variable to see if that value is nonempty. Consequently, tests usingifdef return true for all definitionsexcept those like foo =. To test for an empty value, useifeq ($(foo),). For example,

          bar =
          foo = $(bar)
          ifdef foo
          frobozz = yes
          else
          frobozz = no
          endif

sets ‘frobozz’ to ‘yes’, while:

          foo =
          ifdef foo
          frobozz = yes
          else
          frobozz = no
          endif

sets ‘frobozz’ to ‘no’.

ifndef variable-name
If the variable variable-name has an empty value, the text-if-true is effective; otherwise, the text-if-false,if any, is effective. The rules for expansion and testing of variable-name are identical to the ifdef directive.

Extra spaces are allowed and ignored at the beginning of theconditional directive line, but a tab is not allowed. (If the linebegins with a tab, it will be considered part of a recipe for a rule.) Aside from this, extra spaces or tabs may be inserted with no effectanywhere except within the directive name or within an argument. Acomment starting with ‘#’ may appear at the end of the line.

The other two directives that play a part in a conditional are elseandendif. Each of these directives is written as one word, with noarguments. Extra spaces are allowed and ignored at the beginning of theline, and spaces or tabs at the end. A comment starting with ‘#’ mayappear at the end of the line.

Conditionals affect which lines of the makefile make uses. Ifthe condition is true,make reads the lines of thetext-if-true as part of the makefile; if the condition is false,make ignores those lines completely. It follows that syntacticunits of the makefile, such as rules, may safely be split across thebeginning or the end of the conditional.

make evaluates conditionals when it reads a makefile. Consequently, you cannot use automatic variables in the tests ofconditionals because they are not defined until recipes are run(seeAutomatic Variables).

To prevent intolerable confusion, it is not permitted to start aconditional in one makefile and end it in another. However, you maywrite aninclude directive within a conditional, provided you donot attempt to terminate the conditional inside the included file.

Previous:  Conditional Syntax,Up:  Conditionals

7.3 Conditionals that Test Flags

You can write a conditional that tests make command flags such as‘-t’ by using the variableMAKEFLAGS together with thefindstring function(see Functions for String Substitution and Analysis). This is useful when touch is not enough to make a file appear upto date.

The findstring function determines whether one string appears as asubstring of another. If you want to test for the ‘-t’ flag,use ‘t’ as the first string and the value of MAKEFLAGS asthe other.

For example, here is how to arrange to use ‘ranlib -t’ to finishmarking an archive file up to date:

     archive.a: ...
     ifneq (,$(findstring t,$(MAKEFLAGS)))
             +touch archive.a
             +ranlib -t archive.a
     else
             ranlib archive.a
     endif

The ‘+’ prefix marks those recipe lines as “recursive” so thatthey will be executed despite use of the ‘-t’ flag. SeeRecursive Use of make.

Next:  ,Previous:  Conditionals,Up:  Top

8 Functions for Transforming Text

Functions allow you to do text processing in the makefile tocompute the files to operate on or the commands to use in recipes. You use a function in afunction call, where you give the nameof the function and some text (thearguments) for the functionto operate on. The result of the function's processing is substitutedinto the makefile at the point of the call, just as a variable mightbe substituted.

Next:  ,Previous:  Functions,Up:  Functions

8.1 Function Call Syntax

A function call resembles a variable reference. It looks like this:

     $(function arguments)

or like this:

     ${function arguments}

Here function is a function name; one of a short list of namesthat are part ofmake. You can also essentially create your ownfunctions by using thecall builtin function.

The arguments are the arguments of the function. They areseparated from the function name by one or more spaces or tabs, and ifthere is more than one argument, then they are separated by commas. Such whitespace and commas are not part of an argument's value. Thedelimiters which you use to surround the function call, whetherparentheses or braces, can appear in an argument only in matching pairs;the other kind of delimiters may appear singly. If the argumentsthemselves contain other function calls or variable references, it iswisest to use the same kind of delimiters for all the references; write‘$(subst a,b,$(x))’, not ‘$(subst a,b,${x})’. Thisis because it is clearer, and because only one type of delimiter ismatched to find the end of the reference.

The text written for each argument is processed by substitution ofvariables and function calls to produce the argument value, whichis the text on which the function acts. The substitution is done in theorder in which the arguments appear.

Commas and unmatched parentheses or braces cannot appear in the text of anargument as written; leading spaces cannot appear in the text of the firstargument as written. These characters can be put into the argument valueby variable substitution. First define variables comma andspace whose values are isolated comma and space characters, thensubstitute these variables where such characters are wanted, like this:

     comma:= ,
     empty:=
     space:= $(empty) $(empty)
     foo:= a b c
     bar:= $(subst $(space),$(comma),$(foo))
     # bar is now `a,b,c'.

Here the subst function replaces each space with a comma, throughthe value offoo, and substitutes the result.

Next:  ,Previous:  Syntax of Functions,Up:  Functions

8.2 Functions for String Substitution and Analysis

Here are some functions that operate on strings:

$(subst from , to , text )
Performs a textual replacement on the text text: each occurrenceof from is replaced by to. The result is substituted forthe function call. For example, 
          $(subst ee,EE,feet on the street)

substitutes the string ‘fEEt on the strEEt’.

$(patsubst pattern , replacement , text )
Finds whitespace-separated words in text that match pattern and replaces them with replacement. Here pattern may contain a ‘ %’ which acts as a wildcard,matching any number of any characters within a word. If replacement also contains a ‘ %’, the ‘ %’ is replacedby the text that matched the ‘ %’ in pattern. Only the first‘ %’ in the pattern and replacement is treated thisway; any subsequent ‘ %’ is unchanged.

‘%’ characters in patsubst function invocations can bequoted with preceding backslashes (‘\’). Backslashes that wouldotherwise quote ‘%’ characters can be quoted with more backslashes. Backslashes that quote ‘%’ characters or other backslashes areremoved from the pattern before it is compared file names or has a stemsubstituted into it. Backslashes that are not in danger of quoting‘%’ characters go unmolested. For example, the patternthe\%weird\\%pattern\\ has ‘the%weird\’ preceding theoperative ‘%’ character, and ‘pattern\\’ following it. Thefinal two backslashes are left alone because they cannot affect any‘%’ character.

Whitespace between words is folded into single space characters;leading and trailing whitespace is discarded.

For example, 

          $(patsubst %.c,%.o,x.c.c bar.c)

produces the value ‘x.c.o bar.o’.

Substitution references (see Substitution References) are a simpler way to get the effect of thepatsubstfunction: 

          $(var:pattern=replacement)

is equivalent to 

          $(patsubst pattern,replacement,$(var))

The second shorthand simplifies one of the most common uses ofpatsubst: replacing the suffix at the end of file names.

          $(var:suffix=replacement)

is equivalent to 

          $(patsubst %suffix,%replacement,$(var))

For example, you might have a list of object files: 

          objects = foo.o bar.o baz.o

To get the list of corresponding source files, you could simply write:

          $(objects:.o=.c)

instead of using the general form: 

          $(patsubst %.o,%.c,$(objects))

$(strip string )
Removes leading and trailing whitespace from string and replaceseach internal sequence of one or more whitespace characters with asingle space. Thus, ‘ $(strip a b c )’ results in ‘ a b c’.

The function strip can be very useful when used in conjunctionwith conditionals. When comparing something with the empty string‘’ usingifeq or ifneq, you usually want a string ofjust whitespace to match the empty string (seeConditionals).

Thus, the following may fail to have the desired results: 

          .PHONY: all
          ifneq   "$(needs_made)" ""
          all: $(needs_made)
          else
          all:;@echo 'Nothing to make!'
          endif

Replacing the variable reference ‘$(needs_made)’ with thefunction call ‘$(strip $(needs_made))’ in theifneqdirective would make it more robust.

$(findstring find , in )
Searches in for an occurrence of find. If it occurs, thevalue is find; otherwise, the value is empty. You can use thisfunction in a conditional to test for the presence of a specificsubstring in a given string. Thus, the two examples, 
          $(findstring a,a b c)
          $(findstring a,b c)

produce the values ‘a’ and ‘’ (the empty string),respectively. SeeTesting Flags, for a practical application offindstring.


$(filter pattern ..., text )
Returns all whitespace-separated words in text that do matchany of the pattern words, removing any words that do notmatch. The patterns are written using ‘ %’, just like the patternsused in the patsubst function above.

The filter function can be used to separate out different typesof strings (such as file names) in a variable. For example:

          sources := foo.c bar.c baz.s ugh.h
          foo: $(sources)
                  cc $(filter %.c %.s,$(sources)) -o foo

says that foo depends offoo.c, bar.c,baz.s andugh.h but only foo.c,bar.c andbaz.s should be specified in the command to thecompiler.

$(filter-out pattern ..., text )
Returns all whitespace-separated words in text that do notmatch any of the pattern words, removing the words that domatch one or more. This is the exact opposite of the filterfunction.

For example, given: 

          objects=main1.o foo.o main2.o bar.o
          mains=main1.o main2.o

the following generates a list which contains all the object files notin ‘mains’:

          $(filter-out $(mains),$(objects))


$(sort list )
Sorts the words of list in lexical order, removing duplicatewords. The output is a list of words separated by single spaces. Thus, 
          $(sort foo bar lose)

returns the value ‘bar foo lose’.

Incidentally, sincesort removes duplicate words, you can useit for this purpose even if you don't care about the sort order.

$(word n , text )
Returns the nth word of text. The legitimate values of n start from 1. If n is bigger than the number of wordsin text, the value is empty. For example, 
          $(word 2, foo bar baz)

returns ‘bar’.

$(wordlist s , e , text )
Returns the list of words in text starting with word s andending with word e (inclusive). The legitimate values of sstart from 1; e may start from 0. If s is bigger than thenumber of words in text, the value is empty. If e isbigger than the number of words in text, words up to the end of text are returned. If s is greater than e, nothingis returned. For example, 
          $(wordlist 2, 3, foo bar baz)

returns ‘bar baz’.

$(words text )
Returns the number of words in text. Thus, the last word of text is $(word $(words  text ), text ).
$(firstword names ...)
The argument names is regarded as a series of names, separatedby whitespace. The value is the first name in the series. The restof the names are ignored.

For example, 

          $(firstword foo bar)

produces the result ‘foo’. Although$(firstwordtext) is the same as $(word 1,text), thefirstword function is retained for its simplicity.

$(lastword names ...)
The argument names is regarded as a series of names, separatedby whitespace. The value is the last name in the series.

For example, 

          $(lastword foo bar)

produces the result ‘bar’. Although$(lastwordtext) is the same as $(word $(wordstext),text),the lastword function was added for its simplicity and betterperformance.

Here is a realistic example of the use of subst andpatsubst. Suppose that a makefile uses theVPATH variableto specify a list of directories that make should search forprerequisite files(seeVPATH Search Path for All Prerequisites). This example shows how totell the C compiler to search for header files in the same list ofdirectories.

The value of VPATH is a list of directories separated by colons,such as ‘src:../headers’. First, thesubst function is used tochange the colons to spaces:

     $(subst :, ,$(VPATH))

This produces ‘src ../headers’. Thenpatsubst is used to turneach directory name into a ‘-I’ flag. These can be added to thevalue of the variableCFLAGS, which is passed automatically to the Ccompiler, like this:

     override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH)))

The effect is to append the text ‘-Isrc -I../headers’ to thepreviously given value ofCFLAGS. The override directive isused so that the new value is assigned even if the previous value ofCFLAGS was specified with a command argument (seeThe override Directive).

Next:  ,Previous:  Text Functions,Up:  Functions

8.3 Functions for File Names

Several of the built-in expansion functions relate specifically totaking apart file names or lists of file names.

Each of the following functions performs a specific transformation on afile name. The argument of the function is regarded as a series of filenames, separated by whitespace. (Leading and trailing whitespace isignored.) Each file name in the series is transformed in the same way andthe results are concatenated with single spaces between them.

$(dir names ...)
Extracts the directory-part of each file name in names. Thedirectory-part of the file name is everything up through (andincluding) the last slash in it. If the file name contains no slash,the directory part is the string ‘ ./’. For example, 
          $(dir src/foo.c hacks)

produces the result ‘src/ ./’.

$(notdir names ...)
Extracts all but the directory-part of each file name in names. If the file name contains no slash, it is left unchanged. Otherwise,everything through the last slash is removed from it.

A file name that ends with a slash becomes an empty string. This isunfortunate, because it means that the result does not always have thesame number of whitespace-separated file names as the argument had;but we do not see any other valid alternative.

For example, 

          $(notdir src/foo.c hacks)

produces the result ‘foo.c hacks’.

$(suffix names ...)
Extracts the suffix of each file name in names. If the file namecontains a period, the suffix is everything starting with the lastperiod. Otherwise, the suffix is the empty string. This frequentlymeans that the result will be empty when names is not, and if names contains multiple file names, the result may contain fewerfile names.

For example, 

          $(suffix src/foo.c src-1.0/bar.c hacks)

produces the result ‘.c .c’.

$(basename names ...)
Extracts all but the suffix of each file name in names. If thefile name contains a period, the basename is everything starting up to(and not including) the last period. Periods in the directory part areignored. If there is no period, the basename is the entire file name. For example, 
          $(basename src/foo.c src-1.0/bar hacks)

produces the result ‘src/foo src-1.0/bar hacks’.

$(addsuffix suffix , names ...)
The argument names is regarded as a series of names, separatedby whitespace; suffix is used as a unit. The value of suffix is appended to the end of each individual name and theresulting larger names are concatenated with single spaces betweenthem. For example, 
          $(addsuffix .c,foo bar)

produces the result ‘foo.c bar.c’.

$(addprefix prefix , names ...)
The argument names is regarded as a series of names, separatedby whitespace; prefix is used as a unit. The value of prefix is prepended to the front of each individual name and theresulting larger names are concatenated with single spaces betweenthem. For example, 
          $(addprefix src/,foo bar)

produces the result ‘src/foo src/bar’.

$(join list1 , list2 )
Concatenates the two arguments word by word: the two first words (onefrom each argument) concatenated form the first word of the result, thetwo second words form the second word of the result, and so on. So the nth word of the result comes from the nth word of eachargument. If one argument has more words that the other, the extrawords are copied unchanged into the result.

For example, ‘$(join a b,.c .o)’ produces ‘a.c b.o’.

Whitespace between the words in the lists is not preserved; it isreplaced with a single space.

This function can merge the results of the dir andnotdir functions, to produce the original list of files whichwas given to those two functions.

$(wildcard pattern )
The argument pattern is a file name pattern, typically containingwildcard characters (as in shell file name patterns). The result of wildcard is a space-separated list of the names of existing filesthat match the pattern. See Using Wildcard Characters in File Names.
$(realpath names ...)
For each file name in names return the canonical absolute name. A canonical name does not contain any . or .. components,nor any repeated path separators ( /) or symlinks. In case of afailure the empty string is returned. Consult the realpath(3)documentation for a list of possible failure causes.
$(abspath names ...)
For each file name in names return an absolute name that doesnot contain any . or .. components, nor any repeated pathseparators ( /). Note that, in contrast to realpathfunction, abspath does not resolve symlinks and does not requirethe file names to refer to an existing file or directory. Use the wildcard function to test for existence.

Next:  ,Previous:  File Name Functions,Up:  Functions

8.4 Functions for Conditionals

There are three functions that provide conditional expansion. A keyaspect of these functions is that not all of the arguments areexpanded initially. Only those arguments which need to be expanded,will be expanded.

$(if condition , then-part [, else-part ])
The if function provides support for conditional expansion in afunctional context (as opposed to the GNU make makefileconditionals such as ifeq (see Syntax of Conditionals).

The first argument, condition, first has all preceding andtrailing whitespace stripped, then is expanded. If it expands to anynon-empty string, then the condition is considered to be true. If itexpands to an empty string, the condition is considered to be false.

If the condition is true then the second argument, then-part, isevaluated and this is used as the result of the evaluation of the entireif function.

If the condition is false then the third argument, else-part, isevaluated and this is the result of theif function. If there isno third argument, the if function evaluates to nothing (theempty string).

Note that only one of the then-part or the else-part will beevaluated, never both. Thus, either can contain side-effects (such asshell function calls, etc.)

$(or condition1 [, condition2 [, condition3 ...]])
The or function provides a “short-circuiting” OR operation. Each argument is expanded, in order. If an argument expands to anon-empty string the processing stops and the result of the expansionis that string. If, after all arguments are expanded, all of them arefalse (empty), then the result of the expansion is the empty string.
$(and condition1 [, condition2 [, condition3 ...]])
The and function provides a “short-circuiting” AND operation. Each argument is expanded, in order. If an argument expands to anempty string the processing stops and the result of the expansion isthe empty string. If all arguments expand to a non-empty string thenthe result of the expansion is the expansion of the last argument.

Next:  ,Previous:  Conditional Functions,Up:  Functions

8.5 The foreach Function

Theforeach function is very different from other functions. Itcauses one piece of text to be used repeatedly, each time with a differentsubstitution performed on it. It resembles thefor command in theshell sh and the foreach command in the C-shellcsh.

The syntax of the foreach function is:

     $(foreach var,list,text)

The first two arguments, var and list, are expanded beforeanything else is done; note that the last argument,text, isnot expanded at the same time. Then for each word of the expandedvalue oflist, the variable named by the expanded value of varis set to that word, andtext is expanded. Presumably textcontains references to that variable, so its expansion will be differenteach time.

The result is that text is expanded as many times as there arewhitespace-separated words inlist. The multiple expansions oftext are concatenated, with spaces between them, to make the resultofforeach.

This simple example sets the variable ‘files’ to the list of all filesin the directories in the list ‘dirs’:

     dirs := a b c d
     files := $(foreach dir,$(dirs),$(wildcard $(dir)/*))

Here text is ‘$(wildcard $(dir)/*)’. The first repetitionfinds the value ‘a’ fordir, so it produces the same resultas ‘$(wildcard a/*)’; the second repetition produces the resultof ‘$(wildcard b/*)’; and the third, that of ‘$(wildcard c/*)’.

This example has the same result (except for setting ‘dirs’) asthe following example:

     files := $(wildcard a/* b/* c/* d/*)

When text is complicated, you can improve readability by giving ita name, with an additional variable:

     find_files = $(wildcard $(dir)/*)
     dirs := a b c d
     files := $(foreach dir,$(dirs),$(find_files))

Here we use the variable find_files this way. We use plain ‘=’to define a recursively-expanding variable, so that its value contains anactual function call to be reexpanded under the control of foreach;a simply-expanded variable would not do, since wildcard would becalled only once at the time of definingfind_files.

The foreach function has no permanent effect on the variablevar; its value and flavor after theforeach function call arethe same as they were beforehand. The other values which are taken fromlist are in effect only temporarily, during the execution offoreach. The variablevar is a simply-expanded variableduring the execution of foreach. Ifvar was undefinedbefore the foreach function call, it is undefined after the call. SeeThe Two Flavors of Variables.

You must take care when using complex variable expressions that result invariable names because many strange things are valid variable names, butare probably not what you intended. For example,

     files := $(foreach Esta escrito en espanol!,b c ch,$(find_files))

might be useful if the value of find_files references the variablewhose name is ‘Esta escrito en espanol!’ (es un nombre bastante largo,no?), but it is more likely to be a mistake.

Next:  ,Previous:  Foreach Function,Up:  Functions

8.6 The call Function

Thecall function is unique in that it can be used to create newparameterized functions. You can write a complex expression as thevalue of a variable, then usecall to expand it with differentvalues.

The syntax of the call function is:

     $(call variable,param,param,...)

When make expands this function, it assigns each param totemporary variables$(1), $(2), etc. The variable$(0) will containvariable. There is no maximum number ofparameter arguments. There is no minimum, either, but it doesn't makesense to usecall with no parameters.

Then variable is expanded as a make variable in the contextof these temporary assignments. Thus, any reference to$(1) inthe value of variable will resolve to the first param in theinvocation of call.

Note that variable is the name of a variable, not areference to that variable. Therefore you would not normally usea ‘$’ or parentheses when writing it. (You can, however, use avariable reference in the name if you want the name not to be aconstant.)

If variable is the name of a builtin function, the builtin functionis always invoked (even if amake variable by that name alsoexists).

The call function expands the param arguments beforeassigning them to temporary variables. This means thatvariablevalues containing references to builtin functions that have specialexpansion rules, likeforeach or if, may not work as youexpect.

Some examples may make this clearer.

This macro simply reverses its arguments:

     reverse = $(2) $(1)
     
     foo = $(call reverse,a,b)

Here foo will contain ‘b a’.

This one is slightly more interesting: it defines a macro to search forthe first instance of a program inPATH:

     pathsearch = $(firstword $(wildcard $(addsuffix /$(1),$(subst :, ,$(PATH)))))
     
     LS := $(call pathsearch,ls)

Now the variable LS contains /bin/ls or similar.

The call function can be nested. Each recursive invocation getsits own local values for$(1), etc. that mask the values ofhigher-level call. For example, here is an implementation of amap function:

     map = $(foreach a,$(2),$(call $(1),$(a)))

Now you can map a function that normally takes only one argument,such asorigin, to multiple values in one step:

     o = $(call map,origin,o map MAKE)

and end up with o containing something like ‘file file default’.

A final caution: be careful when adding whitespace to the arguments tocall. As with other functions, any whitespace contained in thesecond and subsequent arguments is kept; this can cause strangeeffects. It's generally safest to remove all extraneous whitespace whenproviding parameters to call.

Next:  ,Previous:  Call Function,Up:  Functions

8.7 The value Function

Thevalue function provides a way for you to use the value of avariable without having it expanded. Please note that thisdoes not undo expansions which have already occurred; for example ifyou create a simply expanded variable its value is expanded during thedefinition; in that case thevalue function will return thesame result as using the variable directly.

The syntax of the value function is:

     $(value variable)

Note that variable is the name of a variable; not areference to that variable. Therefore you would not normallyuse a ‘$’ or parentheses when writing it. (You can, however, usea variable reference in the name if you want the name not to be aconstant.)

The result of this function is a string containing the value ofvariable, without any expansion occurring. For example, in thismakefile:

     FOO = $PATH
     
     all:
             @echo $(FOO)
             @echo $(value FOO)

The first output line would be ATH, since the “$P” would beexpanded as amake variable, while the second output line wouldbe the current value of your$PATH environment variable, sincethe value function avoided the expansion.

The value function is most often used in conjunction with theeval function (seeEval Function).

Next:  ,Previous:  Value Function,Up:  Functions

8.8 The eval Function

Theeval function is very special: it allows you to define newmakefile constructs that are not constant; which are the result ofevaluating other variables and functions. The argument to theeval function is expanded, then the results of that expansionare parsed as makefile syntax. The expanded results can define newmake variables, targets, implicit or explicit rules, etc.

The result of the eval function is always the empty string;thus, it can be placed virtually anywhere in a makefile withoutcausing syntax errors.

It's important to realize that the eval argument is expandedtwice; first by theeval function, then the results ofthat expansion are expanded again when they are parsed as makefilesyntax. This means you may need to provide extra levels of escapingfor “$” characters when usingeval. The valuefunction (see Value Function) can sometimes be useful in thesesituations, to circumvent unwanted expansions.

Here is an example of how eval can be used; this examplecombines a number of concepts and other functions. Although it mightseem overly complex to useeval in this example, rather thanjust writing out the rules, consider two things: first, the templatedefinition (inPROGRAM_template) could need to be much morecomplex than it is here; and second, you might put the complex,“generic” part of this example into another makefile, then includeit in all the individual makefiles. Now your individual makefiles arequite straightforward.

     PROGRAMS    = server client
     
     server_OBJS = server.o server_priv.o server_access.o
     server_LIBS = priv protocol
     
     client_OBJS = client.o client_api.o client_mem.o
     client_LIBS = protocol
     
     # Everything after this is generic
     
     .PHONY: all
     all: $(PROGRAMS)
     
     define PROGRAM_template =
      $(1): $$($(1)_OBJS) $$($(1)_LIBS:%=-l%)
      ALL_OBJS   += $$($(1)_OBJS)
     endef
     
     $(foreach prog,$(PROGRAMS),$(eval $(call PROGRAM_template,$(prog))))
     
     $(PROGRAMS):
             $(LINK.o) $^ $(LDLIBS) -o $@
     
     clean:
             rm -f $(ALL_OBJS) $(PROGRAMS)

Next:  ,Previous:  Eval Function,Up:  Functions

8.9 The origin Function

Theorigin function is unlike most other functions in that it doesnot operate on the values of variables; it tells you somethingabouta variable. Specifically, it tells you where it came from.

The syntax of the origin function is:

     $(origin variable)

Note that variable is the name of a variable to inquire about;not areference to that variable. Therefore you would not normallyuse a ‘$’ or parentheses when writing it. (You can, however, use avariable reference in the name if you want the name not to be a constant.)

The result of this function is a string telling you how the variablevariable was defined:

‘ undefined’
if variable was never defined.
‘ default’
if variable has a default definition, as is usual with CCand so on. See Variables Used by Implicit Rules. Note that if you have redefined a default variable, the originfunction will return the origin of the later definition.
‘ environment’
if variable was inherited from the environment provided to make.
‘ environment override’
if variable was inherited from the environment provided to make, and is overriding a setting for variable in themakefile as a result of the ‘ -e’ option (see Summary of Options).
‘ file’
if variable was defined in a makefile.
‘ command line’
if variable was defined on the command line.
‘ override’
if variable was defined with an override directive in amakefile (see The override Directive).
‘ automatic’
if variable is an automatic variable defined for the executionof the recipe for each rule (see Automatic Variables).

This information is primarily useful (other than for your curiosity) todetermine if you want to believe the value of a variable. For example,suppose you have a makefilefoo that includes another makefilebar. You want a variablebletch to be defined in barif you run the command ‘make -f bar’, even if the environment containsa definition ofbletch. However, if foo definedbletch before includingbar, you do not want to override thatdefinition. This could be done by using anoverride directive infoo, giving that definition precedence over the later definition inbar; unfortunately, theoverride directive would alsooverride any command line definitions. So,bar couldinclude:

     ifdef bletch
     ifeq "$(origin bletch)" "environment"
     bletch = barf, gag, etc.
     endif
     endif

If bletch has been defined from the environment, this will redefineit.

If you want to override a previous definition of bletch if it camefrom the environment, even under ‘-e’, you could instead write:

     ifneq "$(findstring environment,$(origin bletch))" ""
     bletch = barf, gag, etc.
     endif

Here the redefinition takes place if ‘$(origin bletch)’ returns either‘environment’ or ‘environment override’. SeeFunctions for String Substitution and Analysis.

Next:  ,Previous:  Origin Function,Up:  Functions

8.10 The flavor Function

Theflavor function is unlike most other functions (and likeorigin function) in that it does not operate on the values ofvariables; it tells you somethingabout a variable. Specifically, it tells you the flavor of a variable (seeThe Two Flavors of Variables).

The syntax of the flavor function is:

     $(flavor variable)

Note that variable is the name of a variable to inquire about;not areference to that variable. Therefore you would not normallyuse a ‘$’ or parentheses when writing it. (You can, however, use avariable reference in the name if you want the name not to be a constant.)

The result of this function is a string that identifies the flavor of thevariablevariable:

‘ undefined’
if variable was never defined.
‘ recursive’
if variable is a recursively expanded variable.
‘ simple’
if variable is a simply expanded variable.

Next:  ,Previous:  Flavor Function,Up:  Functions

8.11 The shell Function

Theshell function is unlike any other function other than thewildcard function(seeThe Function wildcard) in that itcommunicates with the world outside ofmake.

The shell function performs the same function that backquotes(‘`’) perform in most shells: it doescommand expansion. This means that it takes as an argument a shell command and evaluatesto the output of the command. The only processingmake does onthe result is to convert each newline (or carriage-return / newlinepair) to a single space. If there is a trailing (carriage-returnand) newline it will simply be removed.

The commands run by calls to the shell function are run when thefunction calls are expanded (seeHow make Reads a Makefile). Because this function involvesspawning a new shell, you should carefully consider the performanceimplications of using theshell function within recursivelyexpanded variables vs. simply expanded variables (seeThe Two Flavors of Variables).

Here are some examples of the use of the shell function:

     contents := $(shell cat foo)

sets contents to the contents of the file foo, with a space(rather than a newline) separating each line.

     files := $(shell echo *.c)

sets files to the expansion of ‘*.c’. Unlessmake isusing a very strange shell, this has the same result as‘$(wildcard *.c)’ (as long as at least one ‘.c’ fileexists).

Previous:  Shell Function,Up:  Functions

8.12 Functions That Control Make

These functions control the way make runs. Generally, they are used toprovide information to the user of the makefile or to cause make to stopif some sort of environmental error is detected.

$(error text ...)
Generates a fatal error where the message is text. Note thatthe error is generated whenever this function is evaluated. So, ifyou put it inside a recipe or on the right side of a recursivevariable assignment, it won't be evaluated until later. The text will be expanded before the error is generated.

For example, 

          ifdef ERROR1
          $(error error is $(ERROR1))
          endif

will generate a fatal error during the read of the makefile if themake variableERROR1 is defined. Or, 

          ERR = $(error found an error!)
          
          .PHONY: err
          err: ; $(ERR)

will generate a fatal error while make is running, if theerr target is invoked.

$(warning text ...)
This function works similarly to the error function, above,except that make doesn't exit. Instead, text is expandedand the resulting message is displayed, but processing of the makefilecontinues.

The result of the expansion of this function is the empty string.

$(info text ...)
This function does nothing more than print its (expanded) argument(s)to standard output. No makefile name or line number is added. Theresult of the expansion of this function is the empty string.

Next:  ,Previous:  Functions,Up:  Top

9 How to Run make

A makefile that says how to recompile a program can be used in morethan one way. The simplest use is to recompile every file that is outof date. Usually, makefiles are written so that if you runmake with no arguments, it does just that.

But you might want to update only some of the files; you might want to usea different compiler or different compiler options; you might want just tofind out which files are out of date without changing them.

By giving arguments when you run make, you can do any of thesethings and many others.

The exit status of make is always one of three values:

0
The exit status is zero if make is successful.
2
The exit status is two if make encounters any errors. It will print messages describing the particular errors.
1
The exit status is one if you use the ‘ -q’ flag and makedetermines that some target is not already up to date. See Instead of Executing Recipes.
  • 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

Next:  ,Previous:  Running,Up:  Running

9.1 Arguments to Specify the Makefile

The way to specify the name of the makefile is with the ‘-f’ or‘--file’ option (‘--makefile’ also works). For example,‘-f altmake’ says to use the filealtmake as the makefile.

If you use the ‘-f’ flag several times and follow each ‘-f’with an argument, all the specified files are used jointly asmakefiles.

If you do not use the ‘-f’ or ‘--file’ flag, the default isto tryGNUmakefile, makefile, andMakefile, inthat order, and use the first of these three which exists or can be made(seeWriting Makefiles).

Next:  ,Previous:  Makefile Arguments,Up:  Running

9.2 Arguments to Specify the Goals

The goals are the targets thatmake should strive ultimatelyto update. Other targets are updated as well if they appear asprerequisites of goals, or prerequisites of prerequisites of goals, etc.

By default, the goal is the first target in the makefile (not countingtargets that start with a period). Therefore, makefiles are usuallywritten so that the first target is for compiling the entire program orprograms they describe. If the first rule in the makefile has severaltargets, only the first target in the rule becomes the default goal, notthe whole list. You can manage the selection of the default goal fromwithin your makefile using the.DEFAULT_GOAL variable(see Other Special Variables).

You can also specify a different goal or goals with command linearguments to make. Use the name of the goal as an argument. If you specify several goals,make processes each of them inturn, in the order you name them.

Any target in the makefile may be specified as a goal (unless itstarts with ‘-’ or contains an ‘=’, in which case it will beparsed as a switch or variable definition, respectively). Eventargets not in the makefile may be specified, if make can findimplicit rules that say how to make them.

Make will set the special variableMAKECMDGOALS to thelist of goals you specified on the command line. If no goals were givenon the command line, this variable is empty. Note that this variableshould be used only in special circumstances.

An example of appropriate use is to avoid including .d filesduringclean rules (see Automatic Prerequisites), somake won't create them only to immediately remove themagain:

     sources = foo.c bar.c
     
     ifneq ($(MAKECMDGOALS),clean)
     include $(sources:.c=.d)
     endif

One use of specifying a goal is if you want to compile only a part ofthe program, or only one of several programs. Specify as a goal eachfile that you wish to remake. For example, consider a directory containingseveral programs, with a makefile that starts like this:

     .PHONY: all
     all: size nm ld ar as

If you are working on the program size, you might want to say‘make size’ so that only the files of that program are recompiled.

Another use of specifying a goal is to make files that are not normallymade. For example, there may be a file of debugging output, or aversion of the program that is compiled specially for testing, which hasa rule in the makefile but is not a prerequisite of the default goal.

Another use of specifying a goal is to run the recipe associated witha phony target (seePhony Targets) or empty target (see Empty Target Files to Record Events). Many makefiles containa phony target namedclean which deletes everything except sourcefiles. Naturally, this is done only if you request it explicitly with‘make clean’. Following is a list of typical phony and emptytarget names. See Standard Targets, for a detailed list of all thestandard target names which GNU software packages use.

all
Make all the top-level targets the makefile knows about.
clean
Delete all files that are normally created by running make.
mostlyclean
Like ‘ clean’, but may refrain from deleting a few files that peoplenormally don't want to recompile. For example, the ‘ mostlyclean’target for GCC does not delete libgcc.a, because recompiling itis rarely necessary and takes a lot of time.
distclean
realclean
clobber
Any of these targets might be defined to delete more files than‘ clean’ does. For example, this would delete configuration filesor links that you would normally create as preparation for compilation,even if the makefile itself cannot create these files.
install
Copy the executable file into a directory that users typically searchfor commands; copy any auxiliary files that the executable uses intothe directories where it will look for them.
print
Print listings of the source files that have changed.
tar
Create a tar file of the source files.
shar
Create a shell archive (shar file) of the source files.
dist
Create a distribution file of the source files. This mightbe a tar file, or a shar file, or a compressed version of one of theabove, or even more than one of the above.
TAGS
Update a tags table for this program.
check
test
Perform self tests on the program this makefile builds.

Next:  ,Previous:  Goals,Up:  Running

9.3 Instead of Executing Recipes

The makefile tellsmake how to tell whether a target is up to date,and how to update each target. But updating the targets is not alwayswhat you want. Certain options specify other activities formake.

‘ -n’ ‘ --just-print’ ‘ --dry-run’ ‘ --recon’
“No-op”. The activity is to print what recipe would be used to makethe targets up to date, but not actually execute it. Some recipes arestill executed, even with this flag (see How the MAKE Variable Works).
‘ -t’ ‘ --touch’
“Touch”. The activity is to mark the targets as up to date withoutactually changing them. In other words, make pretends to compilethe targets but does not really change their contents.
‘ -q’ ‘ --question’
“Question”. The activity is to find out silently whether the targetsare up to date already; but execute no recipe in either case. In otherwords, neither compilation nor output will occur.
‘ -W file’ ‘ --what-if=file’ ‘ --assume-new=file’ ‘ --new-file=file’
“What if”. Each ‘ -W’ flag is followed by a file name. The givenfiles' modification times are recorded by make as being the presenttime, although the actual modification times remain the same. You can use the ‘ -W’ flag in conjunction with the ‘ -n’ flagto see what would happen if you were to modify specific files.

With the ‘-n’ flag, make prints the recipe that it wouldnormally execute but usually does not execute it.

With the ‘-t’ flag, make ignores the recipes in the rulesand uses (in effect) the commandtouch for each target that needs tobe remade. The touch command is also printed, unless ‘-s’ or.SILENT is used. For speed,make does not actually invokethe program touch. It does the work directly.

With the ‘-q’ flag, make prints nothing and executes norecipes, but the exit status code it returns is zero if and only if thetargets to be considered are already up to date. If the exit status isone, then some updating needs to be done. If make encounters anerror, the exit status is two, so you can distinguish an error from atarget that is not up to date.

It is an error to use more than one of these three flags in the sameinvocation ofmake.

The ‘-n’, ‘-t’, and ‘-q’ options do not affect recipelines that begin with ‘+’ characters or contain the strings‘$(MAKE)’ or ‘${MAKE}’. Note that only the line containingthe ‘+’ character or the strings ‘$(MAKE)’ or ‘${MAKE}’is run regardless of these options. Other lines in the same rule arenot run unless they too begin with ‘+’ or contain ‘$(MAKE)’ or‘${MAKE}’ (See How the MAKE Variable Works.)

The ‘-t’ flag prevents phony targets (seePhony Targets) frombeing updated, unless there are recipe lines beginning with ‘+’or containing ‘$(MAKE)’ or ‘${MAKE}’.

The ‘-W’ flag provides two features:

  • If you also use the ‘-n’ or ‘-q’ flag, you can see whatmake would do if you were to modify some files.
  • Without the ‘-n’ or ‘-q’ flag, whenmake is actuallyexecuting recipes, the ‘-W’ flag can directmake to act asif some files had been modified, without actually running the recipesfor those files.

Note that the options ‘-p’ and ‘-v’ allow you to obtain otherinformation aboutmake or about the makefiles in use(see Summary of Options).

Next:  ,Previous:  Instead of Execution,Up:  Running

9.4 Avoiding Recompilation of Some Files

Sometimes you may have changed a source file but you do not want torecompile all the files that depend on it. For example, suppose you adda macro or a declaration to a header file that many other files dependon. Being conservative,make assumes that any change in theheader file requires recompilation of all dependent files, but you knowthat they do not need to be recompiled and you would rather not wastethe time waiting for them to compile.

If you anticipate the problem before changing the header file, you canuse the ‘-t’ flag. This flag tellsmake not to run therecipes in the rules, but rather to mark the target up to date bychanging its last-modification date. You would follow this procedure:

  1. Use the command ‘make’ to recompile the source files that reallyneed recompilation, ensuring that the object files are up-to-datebefore you begin.
  2. Make the changes in the header files.
  3. Use the command ‘make -t’ to mark all the object files asup to date. The next time you runmake, the changes in theheader files will not cause any recompilation.

If you have already changed the header file at a time when some filesdo need recompilation, it is too late to do this. Instead, you canuse the ‘-o file’ flag, which marks a specified file as“old” (seeSummary of Options). This meansthat the file itself will not be remade, and nothing else will beremade on its account. Follow this procedure:

  1. Recompile the source files that need compilation for reasons independentof the particular header file, with ‘make -oheaderfile’. If several header files are involved, use a separate ‘-o’ optionfor each header file.
  2. Touch all the object files with ‘make -t’.

Next:  ,Previous:  Avoiding Compilation,Up:  Running

9.5 Overriding Variables

An argument that contains ‘=’ specifies the value of a variable:‘v=x’ sets the value of the variablev to x. If you specify a value in this way, all ordinary assignments of the samevariable in the makefile are ignored; we say they have beenoverridden by the command line argument.

The most common way to use this facility is to pass extra flags tocompilers. For example, in a properly written makefile, the variableCFLAGS is included in each recipe that runs the C compiler, so afilefoo.c would be compiled something like this:

     cc -c $(CFLAGS) foo.c

Thus, whatever value you set for CFLAGS affects each compilationthat occurs. The makefile probably specifies the usual value forCFLAGS, like this:

     CFLAGS=-g

Each time you run make, you can override this value if youwish. For example, if you say ‘make CFLAGS='-g -O'’, each Ccompilation will be done with ‘cc -c -g -O’. (This alsoillustrates how you can use quoting in the shell to enclose spaces andother special characters in the value of a variable when you overrideit.)

The variable CFLAGS is only one of many standard variables thatexist just so that you can change them this way. SeeVariables Used by Implicit Rules, for a complete list.

You can also program the makefile to look at additional variables of yourown, giving the user the ability to control other aspects of how themakefile works by changing the variables.

When you override a variable with a command line argument, you candefine either a recursively-expanded variable or a simply-expandedvariable. The examples shown above make a recursively-expandedvariable; to make a simply-expanded variable, write ‘:=’ insteadof ‘=’. But, unless you want to include a variable reference orfunction call in thevalue that you specify, it makes nodifference which kind of variable you create.

There is one way that the makefile can change a variable that you haveoverridden. This is to use theoverride directive, which is a linethat looks like this: ‘overridevariable = value’(seeThe override Directive).

Next:  ,Previous:  Overriding,Up:  Running

9.6 Testing the Compilation of a Program

Normally, when an error happens in executing a shell command,makegives up immediately, returning a nonzero status. No further recipes areexecuted for any target. The error implies that the goal cannot becorrectly remade, andmake reports this as soon as it knows.

When you are compiling a program that you have just changed, this is notwhat you want. Instead, you would rather thatmake try compilingevery file that can be tried, to show you as many compilation errorsas possible.

On these occasions, you should use the ‘-k’ or‘--keep-going’ flag. This tells make to continue toconsider the other prerequisites of the pending targets, remaking themif necessary, before it gives up and returns nonzero status. Forexample, after an error in compiling one object file, ‘make -k’will continue compiling other object files even though it alreadyknows that linking them will be impossible. In addition to continuingafter failed shell commands, ‘make -k’ will continue as much aspossible after discovering that it does not know how to make a targetor prerequisite file. This will always cause an error message, butwithout ‘-k’, it is a fatal error (seeSummary of Options).

The usual behavior of make assumes that your purpose is to get thegoals up to date; oncemake learns that this is impossible, it mightas well report the failure immediately. The ‘-k’ flag says that thereal purpose is to test as much as possible of the changes made in theprogram, perhaps to find several independent problems so that you cancorrect them all before the next attempt to compile. This is why Emacs'M-x compile command passes the ‘-k’ flag by default.

Previous:  Testing,Up:  Running

9.7 Summary of Options

Here is a table of all the optionsmake understands:

‘ -b’
‘ -m’
These options are ignored for compatibility with other versions of make.
‘ -B’
‘ --always-make’
Consider all targets out-of-date. GNU make proceeds toconsider targets and their prerequisites using the normal algorithms;however, all targets so considered are always remade regardless of thestatus of their prerequisites. To avoid infinite recursion, if MAKE_RESTARTS (see Other Special Variables) is set to a number greater than 0 this option is disabledwhen considering whether to remake makefiles (see How Makefiles Are Remade).
‘ -C dir’
‘ --directory=dir’
Change to directory dir before reading the makefiles. If multiple‘ -C’ options are specified, each is interpreted relative to theprevious one: ‘ -C / -C etc’ is equivalent to ‘ -C /etc’. This is typically used with recursive invocations of make(see Recursive Use of make).
‘ -d’

Print debugging information in addition to normal processing. Thedebugging information says which files are being considered forremaking, which file-times are being compared and with what results,which files actually need to be remade, which implicit rules areconsidered and which are applied—everything interesting about howmake decides what to do. The-d option is equivalent to‘--debug=a’ (see below).

‘ --debug[=options]’

Print debugging information in addition to normal processing. Variouslevels and types of output can be chosen. With no arguments, print the“basic” level of debugging. Possible arguments are below; only thefirst character is considered, and values must be comma- orspace-separated.

a ( all )
All types of debugging output are enabled. This is equivalent to using‘ -d’.
b ( basic )
Basic debugging prints each target that was found to be out-of-date, andwhether the build was successful or not.
v ( verbose )
A level above ‘ basic’; includes messages about which makefiles wereparsed, prerequisites that did not need to be rebuilt, etc. This optionalso enables ‘ basic’ messages.
i ( implicit )
Prints messages describing the implicit rule searches for each target. This option also enables ‘ basic’ messages.
j ( jobs )
Prints messages giving details on the invocation of specific subcommands.
m ( makefile )
By default, the above messages are not enabled while trying to remakethe makefiles. This option enables messages while rebuilding makefiles,too. Note that the ‘ all’ option does enable this option. Thisoption also enables ‘ basic’ messages.

‘ -e’
‘ --environment-overrides’
Give variables taken from the environment precedenceover variables from makefiles. See Variables from the Environment.
‘ --eval=string’

Evaluate string as makefile syntax. This is a command-lineversion of theeval function (see Eval Function). Theevaluation is performed after the default rules and variables havebeen defined, but before any makefiles are read.

‘ -f file’
‘ --file=file’
‘ --makefile=file’
Read the file named file as a makefile. See Writing Makefiles.
‘ -h’
‘ --help’

Remind you of the options that make understands and then exit.

‘ -i’
‘ --ignore-errors’
Ignore all errors in recipes executed to remake files. See Errors in Recipes.
‘ -I dir’
‘ --include-dir=dir’
Specifies a directory dir to search for included makefiles. See Including Other Makefiles. If several ‘ -I’options are used to specify several directories, the directories aresearched in the order specified.
‘ -j [jobs]’
‘ --jobs[=jobs]’
Specifies the number of recipes (jobs) to run simultaneously. With noargument, make runs as many recipes simultaneously as possible. If there is more than one ‘ -j’ option, the last one is effective. See Parallel Execution, for more information on howrecipes are run. Note that this option is ignored on MS-DOS.
‘ -k’
‘ --keep-going’
Continue as much as possible after an error. While the target thatfailed, and those that depend on it, cannot be remade, the otherprerequisites of these targets can be processed all the same. See Testing the Compilation of a Program.
‘ -l [load]’
‘ --load-average[=load]’
‘ --max-load[=load]’
Specifies that no new recipes should be started if there are otherrecipes running and the load average is at least load (afloating-point number). With no argument, removes a previous loadlimit. See Parallel Execution.
‘ -L’
‘ --check-symlink-times’
On systems that support symbolic links, this option causes maketo consider the timestamps on any symbolic links in addition to thetimestamp on the file referenced by those links. When this option isprovided, the most recent timestamp among the file and the symboliclinks is taken as the modification time for this target file.
‘ -n’
‘ --just-print’
‘ --dry-run’
‘ --recon’

Print the recipe that would be executed, but do not execute it (exceptin certain circumstances). SeeInstead of Executing Recipes.

‘ -o file’
‘ --old-file=file’
‘ --assume-old=file’
Do not remake the file file even if it is older than itsprerequisites, and do not remake anything on account of changes in file. Essentially the file is treated as very old and its rulesare ignored. See Avoiding Recompilation of Some Files.
‘ -p’
‘ --print-data-base’
Print the data base (rules and variable values) that results fromreading the makefiles; then execute as usual or as otherwisespecified. This also prints the version information given by the‘ -v’ switch (see below). To print the data base without tryingto remake any files, use ‘ make -qp’. To print the data baseof predefined rules and variables, use ‘ make -p -f /dev/null’. The data base output contains filename and linenumber information forrecipe and variable definitions, so it can be a useful debugging toolin complex environments.
‘ -q’
‘ --question’
“Question mode”. Do not run any recipes, or print anything; justreturn an exit status that is zero if the specified targets are alreadyup to date, one if any remaking is required, or two if an error isencountered. See Instead of Executing Recipes.
‘ -r’
‘ --no-builtin-rules’
Eliminate use of the built-in implicit rules (see Using Implicit Rules). You can still define your own by writingpattern rules (see Defining and Redefining Pattern Rules). The ‘ -r’ option also clears out the default list ofsuffixes for suffix rules (see Old-Fashioned Suffix Rules). But you can still define your own suffixes with a rule for .SUFFIXES, and then define your own suffix rules. Note that only rules are affected by the -r option; default variablesremain in effect (see Variables Used by Implicit Rules); see the ‘ -R’ option below.
‘ -R’
‘ --no-builtin-variables’
Eliminate use of the built-in rule-specific variables (see Variables Used by Implicit Rules). You can still defineyour own, of course. The ‘ -R’ option also automatically enablesthe ‘ -r’ option (see above), since it doesn't make sense to haveimplicit rules without any definitions for the variables that they use.
‘ -s’
‘ --silent’
‘ --quiet’

Silent operation; do not print the recipes as they are executed. See Recipe Echoing.

‘ -S’
‘ --no-keep-going’
‘ --stop’

Cancel the effect of the ‘-k’ option. This is never necessaryexcept in a recursivemake where ‘-k’ might be inheritedfrom the top-levelmake via MAKEFLAGS(see Recursive Use ofmake)or if you set ‘-k’ inMAKEFLAGS in your environment.

‘ -t’
‘ --touch’

Touch files (mark them up to date without really changing them)instead of running their recipes. This is used to pretend that therecipes were done, in order to fool future invocations ofmake. SeeInstead of Executing Recipes.

‘ -v’
‘ --version’
Print the version of the make program plus a copyright, a listof authors, and a notice that there is no warranty; then exit.
‘ -w’
‘ --print-directory’
Print a message containing the working directory both before and afterexecuting the makefile. This may be useful for tracking down errorsfrom complicated nests of recursive make commands. See Recursive Use of make. (In practice, yourarely need to specify this option since ‘ make’ does it for you;see The ‘--print-directory’ Option.)
‘ --no-print-directory’
Disable printing of the working directory under -w. This option is useful when -w is turned on automatically,but you do not want to see the extra messages. See The ‘--print-directory’ Option.
‘ -W file’
‘ --what-if=file’
‘ --new-file=file’
‘ --assume-new=file’
Pretend that the target file has just been modified. When usedwith the ‘ -n’ flag, this shows you what would happen if you wereto modify that file. Without ‘ -n’, it is almost the same asrunning a touch command on the given file before running make, except that the modification time is changed only in theimagination of make. See Instead of Executing Recipes.
‘ --warn-undefined-variables’
Issue a warning message whenever make sees a reference to anundefined variable. This can be helpful when you are trying to debugmakefiles which use variables in complex ways.

Next:  ,Previous:  Running,Up:  Top

10 Using Implicit Rules

Certain standard ways of remaking target files are used very often. Forexample, one customary way to make an object file is from a C source fileusing the C compiler,cc.

Implicit rules tell make how to use customary techniques sothat you do not have to specify them in detail when you want to usethem. For example, there is an implicit rule for C compilation. Filenames determine which implicit rules are run. For example, Ccompilation typically takes a .c file and makes a.o file. So make applies the implicit rule for C compilation when it seesthis combination of file name endings.

A chain of implicit rules can apply in sequence; for example, makewill remake a.o file from a .y file by way of a.c file.

The built-in implicit rules use several variables in their recipes sothat, by changing the values of the variables, you can change the way theimplicit rule works. For example, the variableCFLAGS controls theflags given to the C compiler by the implicit rule for C compilation.

You can define your own implicit rules by writing pattern rules.

Suffix rules are a more limited way to define implicit rules. Pattern rules are more general and clearer, but suffix rules areretained for compatibility.

Next:  ,Previous:  Implicit Rules,Up:  Implicit Rules

10.1 Using Implicit Rules

To allowmake to find a customary method for updating a targetfile, all you have to do is refrain from specifying recipes yourself. Either write a rule with no recipe, or don't write a rule at all. Thenmake will figure out which implicit rule to use based onwhich kind of source file exists or can be made.

For example, suppose the makefile looks like this:

     foo : foo.o bar.o
             cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)

Because you mention foo.o but do not give a rule for it,makewill automatically look for an implicit rule that tells how to update it. This happens whether or not the filefoo.o currently exists.

If an implicit rule is found, it can supply both a recipe and one ormore prerequisites (the source files). You would want to write a ruleforfoo.o with no recipe if you need to specify additionalprerequisites, such as header files, that the implicit rule cannotsupply.

Each implicit rule has a target pattern and prerequisite patterns. There maybe many implicit rules with the same target pattern. For example, numerousrules make ‘.o’ files: one, from a ‘.c’ file with the C compiler;another, from a ‘.p’ file with the Pascal compiler; and so on. The rulethat actually applies is the one whose prerequisites exist or can be made. So, if you have a filefoo.c, make will run the C compiler;otherwise, if you have a filefoo.p, make will run the Pascalcompiler; and so on.

Of course, when you write the makefile, you know which implicit rule youwant make to use, and you know it will choose that one because youknow which possible prerequisite files are supposed to exist. SeeCatalogue of Implicit Rules,for a catalogue of all the predefined implicit rules.

Above, we said an implicit rule applies if the required prerequisites “existor can be made”. A file “can be made” if it is mentioned explicitly inthe makefile as a target or a prerequisite, or if an implicit rule can berecursively found for how to make it. When an implicit prerequisite is theresult of another implicit rule, we say thatchaining is occurring. See Chains of Implicit Rules.

In general, make searches for an implicit rule for each target, andfor each double-colon rule, that has no recipe. A file that is mentionedonly as a prerequisite is considered a target whose rule specifies nothing,so implicit rule search happens for it. See Implicit Rule Search Algorithm, for thedetails of how the search is done.

Note that explicit prerequisites do not influence implicit rule search. For example, consider this explicit rule:

     foo.o: foo.p

The prerequisite on foo.p does not necessarily mean thatmake will remakefoo.o according to the implicit rule tomake an object file, a.o file, from a Pascal source file, a.p file. For example, iffoo.c also exists, the implicitrule to make an object file from a C source file is used instead,because it appears before the Pascal rule in the list of predefinedimplicit rules (seeCatalogue of Implicit Rules).

If you do not want an implicit rule to be used for a target that has norecipe, you can give that target an empty recipe by writing a semicolon(seeDefining Empty Recipes).

Next:  ,Previous:  Using Implicit,Up:  Implicit Rules

10.2 Catalogue of Implicit Rules

Here is a catalogue of predefined implicit rules which are alwaysavailable unless the makefile explicitly overrides or cancels them. SeeCanceling Implicit Rules, for information oncanceling or overriding an implicit rule. The ‘-r’ or‘--no-builtin-rules’ option cancels all predefined rules.

This manual only documents the default rules available on POSIX-basedoperating systems. Other operating systems, such as VMS, Windows,OS/2, etc. may have different sets of default rules. To see the fulllist of default rules and variables available in your version of GNUmake, run ‘make -p’ in a directory with no makefile.

Not all of these rules will always be defined, even when the ‘-r’option is not given. Many of the predefined implicit rules areimplemented inmake as suffix rules, so which ones will bedefined depends on the suffix list (the list of prerequisites ofthe special target .SUFFIXES). The default suffix list is:.out,.a, .ln, .o, .c, .cc,.C,.cpp, .p, .f, .F, .m,.r,.y, .l, .ym, .lm, .s,.S,.mod, .sym, .def, .h,.info,.dvi, .tex, .texinfo, .texi,.txinfo,.w, .ch .web, .sh,.elc,.el. All of the implicit rules described belowwhose prerequisites have one of these suffixes are actually suffixrules. If you modify the suffix list, the only predefined suffixrules in effect will be those named by one or two of the suffixes thatare on the list you specify; rules whose suffixes fail to be on thelist are disabled. SeeOld-Fashioned Suffix Rules,for full details on suffix rules.

Compiling C programs
n.o is made automatically from n.c witha recipe of the form ‘ $(CC) $(CPPFLAGS) $(CFLAGS) -c’.
Compiling C++ programs
n.o is made automatically from n.cc, n.cpp, or n.C with a recipe of the form‘ $(CXX) $(CPPFLAGS) $(CXXFLAGS) -c’. We encourage you to use thesuffix ‘ .cc’ for C++ source files instead of ‘ .C’.
Compiling Pascal programs
n.o is made automatically from n.pwith the recipe ‘ $(PC) $(PFLAGS) -c’.
Compiling Fortran and Ratfor programs
n.o is made automatically from n.r, n.F or n.f by running theFortran compiler. The precise recipe used is as follows:
‘ .f’
‘ $(FC) $(FFLAGS) -c’.
‘ .F’
‘ $(FC) $(FFLAGS) $(CPPFLAGS) -c’.
‘ .r’
‘ $(FC) $(FFLAGS) $(RFLAGS) -c’.

Preprocessing Fortran and Ratfor programs
n.f is made automatically from n.r or n.F. This rule runs just the preprocessor to convert aRatfor or preprocessable Fortran program into a strict Fortranprogram. The precise recipe used is as follows:
‘ .F’
‘ $(FC) $(CPPFLAGS) $(FFLAGS) -F’.
‘ .r’
‘ $(FC) $(FFLAGS) $(RFLAGS) -F’.

Compiling Modula-2 programs
n.sym is made from n.def with a recipeof the form ‘ $(M2C) $(M2FLAGS) $(DEFFLAGS)’. n.ois made from n.mod; the form is:‘ $(M2C) $(M2FLAGS) $(MODFLAGS)’.
Assembling and preprocessing assembler programs
n.o is made automatically from n.s byrunning the assembler, as. The precise recipe is‘ $(AS) $(ASFLAGS)’.

n.s is made automatically fromn.S byrunning the C preprocessor,cpp. The precise recipe is‘$(CPP) $(CPPFLAGS)’.

Linking a single object file
n is made automatically from n.o by runningthe linker (usually called ld) via the C compiler. The preciserecipe used is ‘ $(CC) $(LDFLAGS) n.o $(LOADLIBES) $(LDLIBS)’.

This rule does the right thing for a simple program with only onesource file. It will also do the right thing if there are multipleobject files (presumably coming from various other source files), oneof which has a name matching that of the executable file. Thus, 

          x: y.o z.o

when x.c, y.c andz.c all exist will execute: 

          cc -c x.c -o x.o
          cc -c y.c -o y.o
          cc -c z.c -o z.o
          cc x.o y.o z.o -o x
          rm -f x.o
          rm -f y.o
          rm -f z.o

In more complicated cases, such as when there is no object file whosename derives from the executable file name, you must write an explicitrecipe for linking.

Each kind of file automatically made into ‘.o’ object files willbe automatically linked by using the compiler (‘$(CC)’,‘$(FC)’ or ‘$(PC)’; the C compiler ‘$(CC)’ is used toassemble ‘.s’ files) without the ‘-c’ option. This could bedone by using the ‘.o’ object files as intermediates, but it isfaster to do the compiling and linking in one step, so that's how it'sdone.

Yacc for C programs
n.c is made automatically from n.y byrunning Yacc with the recipe ‘ $(YACC) $(YFLAGS)’.
Lex for C programs
n.c is made automatically from n.l byrunning Lex. The actual recipe is ‘ $(LEX) $(LFLAGS)’.
Lex for Ratfor programs
n.r is made automatically from n.l byrunning Lex. The actual recipe is ‘ $(LEX) $(LFLAGS)’.

The convention of using the same suffix ‘.l’ for all Lex filesregardless of whether they produce C code or Ratfor code makes itimpossible formake to determine automatically which of the twolanguages you are using in any particular case. Ifmake iscalled upon to remake an object file from a ‘.l’ file, it mustguess which compiler to use. It will guess the C compiler, becausethat is more common. If you are using Ratfor, make suremakeknows this by mentioning n.r in the makefile. Or, if youare using Ratfor exclusively, with no C files, remove ‘.c’ fromthe list of implicit rule suffixes with: 

          .SUFFIXES:
          .SUFFIXES: .o .r .f .l ...

Making Lint Libraries from C, Yacc, or Lex programs
n.ln is made from n.c by running lint. The precise recipe is ‘ $(LINT) $(LINTFLAGS) $(CPPFLAGS) -i’. The same recipe is used on the C code produced from n.y or n.l.
TeX and Web
n.dvi is made from n.tex with the recipe‘ $(TEX)’. n.tex is made from n.web with‘ $(WEAVE)’, or from n.w (and from n.ch ifit exists or can be made) with ‘ $(CWEAVE)’. n.p ismade from n.web with ‘ $(TANGLE)’ and n.cis made from n.w (and from n.ch if it existsor can be made) with ‘ $(CTANGLE)’.
Texinfo and Info
n.dvi is made from n.texinfo, n.texi, or n.txinfo, with the recipe‘ $(TEXI2DVI) $(TEXI2DVI_FLAGS)’. n.info is made from n.texinfo, n.texi, or n.txinfo, withthe recipe ‘ $(MAKEINFO) $(MAKEINFO_FLAGS)’.
RCS
Any file n is extracted if necessary from an RCS filenamed either n,v or RCS/n,v. The preciserecipe used is ‘ $(CO) $(COFLAGS)’. n will not beextracted from RCS if it already exists, even if the RCS file isnewer. The rules for RCS are terminal(see Match-Anything Pattern Rules),so RCS files cannot be generated from another source; they mustactually exist.
SCCS
Any file n is extracted if necessary from an SCCS filenamed either s.n or SCCS/s.n. The preciserecipe used is ‘ $(GET) $(GFLAGS)’. The rules for SCCS areterminal (see Match-Anything Pattern Rules),so SCCS files cannot be generated from another source; they mustactually exist.

For the benefit of SCCS, a file n is copied fromn.sh and made executable (by everyone). This is forshell scripts that are checked into SCCS. Since RCS preserves theexecution permission of a file, you do not need to use this featurewith RCS.

We recommend that you avoid using of SCCS. RCS is widely held to besuperior, and is also free. By choosing free software in place ofcomparable (or inferior) proprietary software, you support the freesoftware movement.

Usually, you want to change only the variables listed in the tableabove, which are documented in the following section.

However, the recipes in built-in implicit rules actually usevariables such as COMPILE.c, LINK.p, andPREPROCESS.S, whose values contain the recipes listed above.

make follows the convention that the rule to compile a.x source file uses the variableCOMPILE.x. Similarly, the rule to produce an executable from a.xfile uses LINK.x; and the rule to preprocess a.x file usesPREPROCESS.x.

Every rule that produces an object file uses the variableOUTPUT_OPTION.make defines this variable either tocontain ‘-o $@’, or to be empty, depending on a compile-timeoption. You need the ‘-o’ option to ensure that the output goesinto the right file when the source file is in a different directory,as when using VPATH (see Directory Search). However,compilers on some systems do not accept a ‘-o’ switch for objectfiles. If you use such a system, and useVPATH, somecompilations will put their output in the wrong place. A possible workaround for this problem is to giveOUTPUT_OPTIONthe value ‘; mv $*.o $@’.

Next:  ,Previous:  Catalogue of Rules,Up:  Implicit Rules

10.3 Variables Used by Implicit Rules

The recipes in built-in implicit rules make liberal use of certainpredefined variables. You can alter the values of these variables inthe makefile, with arguments tomake, or in the environment toalter how the implicit rules work without redefining the rulesthemselves. You can cancel all variables used by implicit rules withthe ‘-R’ or ‘--no-builtin-variables’ option.

For example, the recipe used to compile a C source file actually says‘$(CC) -c $(CFLAGS) $(CPPFLAGS)’. The default values of the variablesused are ‘cc’ and nothing, resulting in the command ‘cc -c’. Byredefining ‘CC’ to ‘ncc’, you could cause ‘ncc’ to beused for all C compilations performed by the implicit rule. By redefining‘CFLAGS’ to be ‘-g’, you could pass the ‘-g’ option toeach compilation.All implicit rules that do C compilation use‘$(CC)’ to get the program name for the compiler andallinclude ‘$(CFLAGS)’ among the arguments given to the compiler.

The variables used in implicit rules fall into two classes: those that arenames of programs (likeCC) and those that contain arguments for theprograms (like CFLAGS). (The “name of a program” may also containsome command arguments, but it must start with an actual executable programname.) If a variable value contains more than one argument, separate themwith spaces.

The following tables describe of some of the more commonly-used predefinedvariables. This list is not exhaustive, and the default values shown here maynot be whatmake selects for your environment. To see thecomplete list of predefined variables for your instance of GNUmake youcan run ‘make -p’ in a directory with no makefiles.

Here is a table of some of the more common variables used as names ofprograms in built-in rules:makefiles.

AR
Archive-maintaining program; default ‘ ar’.
AS
Program for compiling assembly files; default ‘ as’.
CC
Program for compiling C programs; default ‘ cc’.
CXX
Program for compiling C++ programs; default ‘ g++’.
CPP
Program for running the C preprocessor, with results to standard output;default ‘ $(CC) -E’.
FC
Program for compiling or preprocessing Fortran and Ratfor programs;default ‘ f77’.
M2C
Program to use to compile Modula-2 source code; default ‘ m2c’.
PC
Program for compiling Pascal programs; default ‘ pc’.
CO
Program for extracting a file from RCS; default ‘ co’.
GET
Program for extracting a file from SCCS; default ‘ get’.
LEX
Program to use to turn Lex grammars into source code; default ‘ lex’.
YACC
Program to use to turn Yacc grammars into source code; default ‘ yacc’.
LINT
Program to use to run lint on source code; default ‘ lint’.
MAKEINFO
Program to convert a Texinfo source file into an Info file; default‘ makeinfo’.
TEX
Program to make TeX dvi files from TeX source;default ‘ tex’.
TEXI2DVI
Program to make TeX dvi files from Texinfo source;default ‘ texi2dvi’.
WEAVE
Program to translate Web into TeX; default ‘ weave’.
CWEAVE
Program to translate C Web into TeX; default ‘ cweave’.
TANGLE
Program to translate Web into Pascal; default ‘ tangle’.
CTANGLE
Program to translate C Web into C; default ‘ ctangle’.
RM
Command to remove a file; default ‘ rm -f’.

Here is a table of variables whose values are additional arguments for theprograms above. The default values for all of these is the emptystring, unless otherwise noted.

ARFLAGS
Flags to give the archive-maintaining program; default ‘ rv’.
ASFLAGS
Extra flags to give to the assembler (when explicitlyinvoked on a ‘ .s’ or ‘ .S’ file).
CFLAGS
Extra flags to give to the C compiler.
CXXFLAGS
Extra flags to give to the C++ compiler.
COFLAGS
Extra flags to give to the RCS co program.
CPPFLAGS
Extra flags to give to the C preprocessor and programsthat use it (the C and Fortran compilers).
FFLAGS
Extra flags to give to the Fortran compiler.
GFLAGS
Extra flags to give to the SCCS get program.
LDFLAGS
Extra flags to give to compilers when they are supposed to invoke the linker,‘ ld’.
LFLAGS
Extra flags to give to Lex.
YFLAGS
Extra flags to give to Yacc.
PFLAGS
Extra flags to give to the Pascal compiler.
RFLAGS
Extra flags to give to the Fortran compiler for Ratfor programs.
LINTFLAGS
Extra flags to give to lint.

Next:  ,Previous:  Implicit Variables,Up:  Implicit Rules

10.4 Chains of Implicit Rules

Sometimes a file can be made by a sequence of implicit rules. For example,a filen.o could be made from n.y by runningfirst Yacc and thencc. Such a sequence is called a chain.

If the file n.c exists, or is mentioned in the makefile, nospecial searching is required:make finds that the object file canbe made by C compilation from n.c; later on, when consideringhow to maken.c, the rule for running Yacc isused. Ultimately bothn.c and n.o areupdated.

However, even ifn.c does not exist and is not mentioned,make knows how to envision it as the missing link betweenn.o andn.y! In this case, n.c iscalled anintermediate file. Once make has decided to use theintermediate file, it is entered in the data base as if it had beenmentioned in the makefile, along with the implicit rule that says how tocreate it.

Intermediate files are remade using their rules just like all otherfiles. But intermediate files are treated differently in two ways.

The first difference is what happens if the intermediate file does notexist. If an ordinary fileb does not exist, and makeconsiders a target that depends onb, it invariably createsb and then updates the target from b. But if b is anintermediate file, then make can leave well enough alone. Itwon't bother updatingb, or the ultimate target, unless someprerequisite of b is newer than that target or there is some otherreason to update that target.

The second difference is that if make does create bin order to update something else, it deletesb later on after itis no longer needed. Therefore, an intermediate file which did notexist beforemake also does not exist after make. make reports the deletion to you by printing a ‘rm -f’command showing which file it is deleting.

Ordinarily, a file cannot be intermediate if it is mentioned in themakefile as a target or prerequisite. However, you can explicitly mark afile as intermediate by listing it as a prerequisite of the special target.INTERMEDIATE. This takes effect even if the file is mentionedexplicitly in some other way.

You can prevent automatic deletion of an intermediate file by marking itas asecondary file. To do this, list it as a prerequisite of thespecial target.SECONDARY. When a file is secondary, makewill not create the file merely because it does not already exist, butmake does not automatically delete the file. Marking a file assecondary also marks it as intermediate.

You can list the target pattern of an implicit rule (such as ‘%.o’)as a prerequisite of the special target.PRECIOUS to preserveintermediate files made by implicit rules whose target patterns matchthat file's name; seeInterrupts. A chain can involve more than two implicit rules. For example, it ispossible to make a filefoo from RCS/foo.y,v by running RCS,Yacc andcc. Then both foo.y and foo.c areintermediate files that are deleted at the end.

No single implicit rule can appear more than once in a chain. This meansthat make will not even consider such a ridiculous thing as makingfoo fromfoo.o.o by running the linker twice. Thisconstraint has the added benefit of preventing any infinite loop in thesearch for an implicit rule chain.

There are some special implicit rules to optimize certain cases that wouldotherwise be handled by rule chains. For example, makingfoo fromfoo.c could be handled by compiling and linking with separatechained rules, usingfoo.o as an intermediate file. But whatactually happens is that a special rule for this case does the compilationand linking with a singlecc command. The optimized rule is used inpreference to the step-by-step chain because it comes earlier in theordering of rules.

Next:  ,Previous:  Chained Rules,Up:  Implicit Rules

10.5 Defining and Redefining Pattern Rules

You define an implicit rule by writing a pattern rule. A patternrule looks like an ordinary rule, except that its target contains thecharacter ‘%’ (exactly one of them). The target is considered apattern for matching file names; the ‘%’ can match any nonemptysubstring, while other characters match only themselves. The prerequisiteslikewise use ‘%’ to show how their names relate to the target name.

Thus, a pattern rule ‘%.o : %.c’ says how to make any filestem.o from another filestem.c.

Note that expansion using ‘%’ in pattern rules occursafter any variable or function expansions, which take placewhen the makefile is read. SeeHow to Use Variables, and Functions for Transforming Text.

Next:  ,Previous:  Pattern Rules,Up:  Pattern Rules

10.5.1 Introduction to Pattern Rules

A pattern rule contains the character ‘%’ (exactly one of them)in the target; otherwise, it looks exactly like an ordinary rule. Thetarget is a pattern for matching file names; the ‘%’ matches anynonempty substring, while other characters match only themselves.For example, ‘%.c’ as a pattern matches any file name that ends in‘.c’. ‘s.%.c’ as a pattern matches any file name that startswith ‘s.’, ends in ‘.c’ and is at least five characters long. (There must be at least one character to match the ‘%’.) The substringthat the ‘%’ matches is called thestem.

‘%’ in a prerequisite of a pattern rule stands for the same stemthat was matched by the ‘%’ in the target. In order for thepattern rule to apply, its target pattern must match the file nameunder consideration and all of its prerequisites (after patternsubstitution) must name files that exist or can be made. These filesbecome prerequisites of the target.Thus, a rule of the form

     %.o : %.c ; recipe...

specifies how to make a file n.o, with another filen.c as its prerequisite, provided thatn.cexists or can be made.

There may also be prerequisites that do not use ‘%’; such a prerequisiteattaches to every file made by this pattern rule. These unvaryingprerequisites are useful occasionally.

A pattern rule need not have any prerequisites that contain ‘%’, orin fact any prerequisites at all. Such a rule is effectively a generalwildcard. It provides a way to make any file that matches the targetpattern. SeeLast Resort.

More than one pattern rule may match a target. In this casemake will choose the “best fit” rule. SeeHow Patterns Match.

Pattern rules may have more than one target. Unlike normal rules,this does not act as many different rules with the same prerequisitesand recipe. If a pattern rule has multiple targets,make knowsthat the rule's recipe is responsible for making all of the targets. The recipe is executed only once to make all the targets. Whensearching for a pattern rule to match a target, the target patterns ofa rule other than the one that matches the target in need of a ruleare incidental: make worries only about giving a recipe andprerequisites to the file presently in question. However, when thisfile's recipe is run, the other targets are marked as having beenupdated themselves.

Next:  ,Previous:  Pattern Intro,Up:  Pattern Rules

10.5.2 Pattern Rule Examples

Here are some examples of pattern rules actually predefined inmake. First, the rule that compiles ‘.c’ files into ‘.o’files:

     %.o : %.c
             $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@

defines a rule that can make any file x.o fromx.c. The recipe uses the automatic variables ‘$@’ and‘$<’ to substitute the names of the target file and the source filein each case where the rule applies (seeAutomatic Variables).

Here is a second built-in rule:

     % :: RCS/%,v
             $(CO) $(COFLAGS) $<

defines a rule that can make any file x whatsoever from acorresponding filex,v in the subdirectory RCS. Sincethe target is ‘%’, this rule will apply to any file whatever, providedthe appropriate prerequisite file exists. The double colon makes the ruleterminal, which means that its prerequisite may not be an intermediatefile (seeMatch-Anything Pattern Rules).

This pattern rule has two targets:

     %.tab.c %.tab.h: %.y
             bison -d $<

This tells make that the recipe ‘bison -dx.y’ willmake both x.tab.c andx.tab.h. If the filefoo depends on the filesparse.tab.o and scan.oand the filescan.o depends on the file parse.tab.h,whenparse.y is changed, the recipe ‘bison -d parse.y’will be executed only once, and the prerequisites of bothparse.tab.o andscan.o will be satisfied. (Presumablythe fileparse.tab.o will be recompiled from parse.tab.cand the file scan.o fromscan.c, while foo islinked fromparse.tab.o, scan.o, and its otherprerequisites, and it will execute happily ever after.)

Next:  ,Previous:  Pattern Examples,Up:  Pattern Rules

10.5.3 Automatic Variables

Suppose you are writing a pattern rule to compile a ‘.c’ file into a‘.o’ file: how do you write the ‘cc’ command so that it operateson the right source file name? You cannot write the name in the recipe,because the name is different each time the implicit rule is applied.

What you do is use a special feature of make, the automaticvariables. These variables have values computed afresh for each rule thatis executed, based on the target and prerequisites of the rule. In thisexample, you would use ‘$@’ for the object file name and ‘$<’for the source file name.

It's very important that you recognize the limited scope in whichautomatic variable values are available: they only have values withinthe recipe. In particular, you cannot use them anywherewithin the target list of a rule; they have no value there and willexpand to the empty string. Also, they cannot be accessed directlywithin the prerequisite list of a rule. A common mistake isattempting to use $@ within the prerequisites list; this willnot work. However, there is a special feature of GNUmake,secondary expansion (see Secondary Expansion), which will allowautomatic variable values to be used in prerequisite lists.

Here is a table of automatic variables:

$@
The file name of the target of the rule. If the target is an archivemember, then ‘ $@’ is the name of the archive file. In a patternrule that has multiple targets (see Introduction to Pattern Rules), ‘ $@’ is the name of whichever target caused therule's recipe to be run.


$%
The target member name, when the target is an archive member. See Archives. For example, if the target is foo.a(bar.o) then‘ $%’ is bar.o and ‘ $@’ is foo.a. ‘ $%’ isempty when the target is not an archive member.


$<
The name of the first prerequisite. If the target got its recipe froman implicit rule, this will be the first prerequisite added by theimplicit rule (see Implicit Rules).


$?
The names of all the prerequisites that are newer than the target, withspaces between them. For prerequisites which are archive members, onlythe named member is used (see Archives).
$^
The names of all the prerequisites, with spaces between them. Forprerequisites which are archive members, only the named member is used(see Archives). A target has only one prerequisite on each other fileit depends on, no matter how many times each file is listed as aprerequisite. So if you list a prerequisite more than once for a target,the value of $^ contains just one copy of the name. This listdoes not contain any of the order-only prerequisites; for thosesee the ‘ $|’ variable, below.
$+
This is like ‘ $^’, but prerequisites listed more than once areduplicated in the order they were listed in the makefile. This isprimarily useful for use in linking commands where it is meaningful torepeat library file names in a particular order.


$|
The names of all the order-only prerequisites, with spaces betweenthem.


$*
The stem with which an implicit rule matches (see How Patterns Match). If the target is dir/a.foo.b and the targetpattern is a.%.b then the stem is dir/foo. The stem isuseful for constructing names of related files. In a static pattern rule, the stem is part of the file name that matchedthe ‘ %’ in the target pattern.

In an explicit rule, there is no stem; so ‘$*’ cannot be determinedin that way. Instead, if the target name ends with a recognized suffix(seeOld-Fashioned Suffix Rules), ‘$*’ is set tothe target name minus the suffix. For example, if the target name is‘foo.c’, then ‘$*’ is set to ‘foo’, since ‘.c’ is asuffix. GNUmake does this bizarre thing only for compatibilitywith other implementations ofmake. You should generally avoidusing ‘$*’ except in implicit rules or static pattern rules.

If the target name in an explicit rule does not end with a recognizedsuffix, ‘$*’ is set to the empty string for that rule.

‘$?’ is useful even in explicit rules when you wish to operate on onlythe prerequisites that have changed. For example, suppose that an archivenamedlib is supposed to contain copies of several object files. This rule copies just the changed object files into the archive:

     lib: foo.o bar.o lose.o win.o
             ar r lib $?

Of the variables listed above, four have values that are single filenames, and three have values that are lists of file names. These sevenhave variants that get just the file's directory name or just the filename within the directory. The variant variables' names are formed byappending ‘D’ or ‘F’, respectively. These variants aresemi-obsolete in GNUmake since the functions dir andnotdir can be used to get a similar effect (seeFunctions for File Names). Note, however, that the‘D’ variants all omit the trailing slash which always appears inthe output of thedir function. Here is a table of the variants:

‘ $(@D)’
The directory part of the file name of the target, with the trailingslash removed. If the value of ‘ $@’ is dir/foo.o then‘ $(@D)’ is dir. This value is . if ‘ $@’ doesnot contain a slash.


‘ $(@F)’
The file-within-directory part of the file name of the target. If thevalue of ‘ $@’ is dir/foo.o then ‘ $(@F)’ is foo.o. ‘ $(@F)’ is equivalent to ‘ $(notdir $@)’.


‘ $(*D)’
‘ $(*F)’
The directory part and the file-within-directorypart of the stem; dir and foo in this example.


‘ $(%D)’
‘ $(%F)’
The directory part and the file-within-directory part of the targetarchive member name. This makes sense only for archive member targetsof the form archive(member) and is useful only when member may contain a directory name. (See Archive Members as Targets.)


‘ $(<D)’
‘ $(<F)’
The directory part and the file-within-directorypart of the first prerequisite.


‘ $(^D)’
‘ $(^F)’
Lists of the directory parts and the file-within-directoryparts of all prerequisites.


‘ $(+D)’
‘ $(+F)’
Lists of the directory parts and the file-within-directoryparts of all prerequisites, including multiple instances of duplicatedprerequisites.


‘ $(?D)’
‘ $(?F)’
Lists of the directory parts and the file-within-directory parts ofall prerequisites that are newer than the target.

Note that we use a special stylistic convention when we talk about theseautomatic variables; we write “the value of ‘$<’”, rather than“the variable <” as we would write for ordinary variablessuch asobjects and CFLAGS. We think this conventionlooks more natural in this special case. Please do not assume it has adeep significance; ‘$<’ refers to the variable named< justas ‘$(CFLAGS)’ refers to the variable namedCFLAGS. You could just as well use ‘$(<)’ in place of ‘$<’.

Next:  ,Previous:  Automatic Variables,Up:  Pattern Rules

10.5.4 How Patterns Match

A target pattern is composed of a ‘%’ between a prefix and a suffix,either or both of which may be empty. The pattern matches a file name onlyif the file name starts with the prefix and ends with the suffix, withoutoverlap. The text between the prefix and the suffix is called thestem. Thus, when the pattern ‘%.o’ matches the file nametest.o, the stem is ‘test’. The pattern rule prerequisites areturned into actual file names by substituting the stem for the character‘%’. Thus, if in the same example one of the prerequisites is writtenas ‘%.c’, it expands to ‘test.c’.

When the target pattern does not contain a slash (and it usually doesnot), directory names in the file names are removed from the file namebefore it is compared with the target prefix and suffix. After thecomparison of the file name to the target pattern, the directorynames, along with the slash that ends them, are added on to theprerequisite file names generated from the pattern rule's prerequisitepatterns and the file name. The directories are ignored only for thepurpose of finding an implicit rule to use, not in the application ofthat rule. Thus, ‘e%t’ matches the file namesrc/eat,with ‘src/a’ as the stem. When prerequisites are turned into filenames, the directories from the stem are added at the front, while therest of the stem is substituted for the ‘%’. The stem‘src/a’ with a prerequisite pattern ‘c%r’ gives the file namesrc/car.

A pattern rule can be used to build a given file only if there is atarget pattern that matches the file name,and allprerequisites in that rule either exist or can be built. The rulesyou write take precedence over those that are built in. Note however,that a rule whose prerequisites actually exist or are mentioned alwaystakes priority over a rule with prerequisites that must be made bychaining other implicit rules.

It is possible that more than one pattern rule will meet thesecriteria. In that case,make will choose the rule with theshortest stem (that is, the pattern that matches most specifically). If more than one pattern rule has the shortest stem,make willchoose the first one found in the makefile.

This algorithm results in more specific rules being preferred overmore generic ones; for example:

     %.o: %.c
             $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@
     
     %.o : %.f
             $(COMPILE.F) $(OUTPUT_OPTION) $<
     
     lib/%.o: lib/%.c
             $(CC) -fPIC -c $(CFLAGS) $(CPPFLAGS) $< -o $@

Given these rules and asked to build bar.o where bothbar.c andbar.f exist, make will choose the firstrule and compilebar.c into bar.o. In the samesituation wherebar.c does not exist, then make willchoose the second rule and compilebar.f into bar.o.

If make is asked to build lib/bar.o and bothlib/bar.c andlib/bar.f exist, then the third rule willbe chosen since the stem for this rule (‘bar’) is shorter thanthe stem for the first rule (‘lib/bar’). If lib/bar.cdoes not exist then the third rule is not eligible and the second rulewill be used, even though the stem is longer.

Next:  ,Previous:  Pattern Match,Up:  Pattern Rules

10.5.5 Match-Anything Pattern Rules

When a pattern rule's target is just ‘%’, it matches any file namewhatever. We call these rulesmatch-anything rules. They are veryuseful, but it can take a lot of time formake to think about them,because it must consider every such rule for each file name listed eitheras a target or as a prerequisite.

Suppose the makefile mentions foo.c. For this target,makewould have to consider making it by linking an object file foo.c.o,or by C compilation-and-linking in one step fromfoo.c.c, or byPascal compilation-and-linking fromfoo.c.p, and many otherpossibilities.

We know these possibilities are ridiculous since foo.c is a C sourcefile, not an executable. Ifmake did consider these possibilities,it would ultimately reject them, because files such asfoo.c.o andfoo.c.p would not exist. But these possibilities are sonumerous thatmake would run very slowly if it had to considerthem.

To gain speed, we have put various constraints on the way makeconsiders match-anything rules. There are two different constraints thatcan be applied, and each time you define a match-anything rule you mustchoose one or the other for that rule.

One choice is to mark the match-anything rule as terminal by definingit with a double colon. When a rule is terminal, it does not apply unlessits prerequisites actually exist. Prerequisites that could be made withother implicit rules are not good enough. In other words, no furtherchaining is allowed beyond a terminal rule.

For example, the built-in implicit rules for extracting sources from RCSand SCCS files are terminal; as a result, if the filefoo.c,v doesnot exist, make will not even consider trying to make it as anintermediate file fromfoo.c,v.o or from RCS/SCCS/s.foo.c,v. RCS and SCCS files are generally ultimate source files, which should not beremade from any other files; therefore,make can save time by notlooking for ways to remake them.

If you do not mark the match-anything rule as terminal, then it isnonterminal. A nonterminal match-anything rule cannot apply to a file namethat indicates a specific type of data. A file name indicates a specifictype of data if some non-match-anything implicit rule target matches it.

For example, the file name foo.c matches the target for the patternrule ‘%.c : %.y’ (the rule to run Yacc). Regardless of whether thisrule is actually applicable (which happens only if there is a filefoo.y), the fact that its target matches is enough to preventconsideration of any nonterminal match-anything rules for the filefoo.c. Thus,make will not even consider trying to makefoo.c as an executable file fromfoo.c.o, foo.c.c,foo.c.p, etc.

The motivation for this constraint is that nonterminal match-anythingrules are used for making files containing specific types of data (such asexecutable files) and a file name with a recognized suffix indicates someother specific type of data (such as a C source file).

Special built-in dummy pattern rules are provided solely to recognizecertain file names so that nonterminal match-anything rules will not beconsidered. These dummy rules have no prerequisites and no recipes, andthey are ignored for all other purposes. For example, the built-inimplicit rule

     %.p :

exists to make sure that Pascal source files such as foo.p match aspecific target pattern and thereby prevent time from being wasted lookingforfoo.p.o or foo.p.c.

Dummy pattern rules such as the one for ‘%.p’ are made for everysuffix listed as valid for use in suffix rules (seeOld-Fashioned Suffix Rules).

Previous:  Match-Anything Rules,Up:  Pattern Rules

10.5.6 Canceling Implicit Rules

You can override a built-in implicit rule (or one you have definedyourself) by defining a new pattern rule with the same target andprerequisites, but a different recipe. When the new rule is defined, thebuilt-in one is replaced. The new rule's position in the sequence ofimplicit rules is determined by where you write the new rule.

You can cancel a built-in implicit rule by defining a pattern rule with thesame target and prerequisites, but no recipe. For example, the followingwould cancel the rule that runs the assembler:

     %.o : %.s

Next:  ,Previous:  Pattern Rules,Up:  Implicit Rules

10.6 Defining Last-Resort Default Rules

You can define a last-resort implicit rule by writing a terminalmatch-anything pattern rule with no prerequisites (seeMatch-Anything Rules). This is just like any other pattern rule; the only thingspecial about it is that it will match any target. So such a rule'srecipe is used for all targets and prerequisites that have no recipeof their own and for which no other implicit rule applies.

For example, when testing a makefile, you might not care if the sourcefiles contain real data, only that they exist. Then you might do this:

     %::
             touch $@

to cause all the source files needed (as prerequisites) to be createdautomatically.

You can instead define a recipe to be used for targets for which thereare no rules at all, even ones which don't specify recipes. You dothis by writing a rule for the target.DEFAULT. Such a rule'srecipe is used for all prerequisites which do not appear as targets inany explicit rule, and for which no implicit rule applies. Naturally,there is no.DEFAULT rule unless you write one.

If you use .DEFAULT with no recipe or prerequisites:

     .DEFAULT:

the recipe previously stored for .DEFAULT is cleared. Thenmake acts as if you had never defined.DEFAULT at all.

If you do not want a target to get the recipe from a match-anythingpattern rule or.DEFAULT, but you also do not want any recipeto be run for the target, you can give it an empty recipe(seeDefining Empty Recipes).

You can use a last-resort rule to override part of another makefile. See Overriding Part of Another Makefile.

Next:  ,Previous:  Last Resort,Up:  Implicit Rules

10.7 Old-Fashioned Suffix Rules

Suffix rules are the old-fashioned way of defining implicit rules formake. Suffix rules are obsolete because pattern rules are moregeneral and clearer. They are supported in GNU make forcompatibility with old makefiles. They come in two kinds:double-suffix andsingle-suffix.

A double-suffix rule is defined by a pair of suffixes: the target suffixand the source suffix. It matches any file whose name ends with thetarget suffix. The corresponding implicit prerequisite is made byreplacing the target suffix with the source suffix in the file name. Atwo-suffix rule whose target and source suffixes are ‘.o’ and‘.c’ is equivalent to the pattern rule ‘%.o : %.c’.

A single-suffix rule is defined by a single suffix, which is the sourcesuffix. It matches any file name, and the corresponding implicitprerequisite name is made by appending the source suffix. A single-suffixrule whose source suffix is ‘.c’ is equivalent to the pattern rule‘% : %.c’.

Suffix rule definitions are recognized by comparing each rule's targetagainst a defined list of known suffixes. Whenmake sees a rulewhose target is a known suffix, this rule is considered a single-suffixrule. Whenmake sees a rule whose target is two known suffixesconcatenated, this rule is taken as a double-suffix rule.

For example, ‘.c’ and ‘.o’ are both on the default list ofknown suffixes. Therefore, if you define a rule whose target is‘.c.o’,make takes it to be a double-suffix rule with sourcesuffix ‘.c’ and target suffix ‘.o’. Here is the old-fashionedway to define the rule for compiling a C source file:

     .c.o:
             $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $<

Suffix rules cannot have any prerequisites of their own. If they have any,they are treated as normal files with funny names, not as suffix rules. Thus, the rule:

     .c.o: foo.h
             $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $<

tells how to make the file .c.o from the prerequisite filefoo.h, and is not at all like the pattern rule:

     %.o: %.c foo.h
             $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $<

which tells how to make ‘.o’ files from ‘.c’ files, and makes all‘.o’ files using this pattern rule also depend onfoo.h.

Suffix rules with no recipe are also meaningless. They do not removeprevious rules as do pattern rules with no recipe (seeCanceling Implicit Rules). They simply enter the suffix orpair of suffixes concatenated as a target in the data base.

The known suffixes are simply the names of the prerequisites of the specialtarget.SUFFIXES. You can add your own suffixes by writing a rulefor .SUFFIXES that adds more prerequisites, as in:

     .SUFFIXES: .hack .win

which adds ‘.hack’ and ‘.win’ to the end of the list of suffixes.

If you wish to eliminate the default known suffixes instead of just addingto them, write a rule for.SUFFIXES with no prerequisites. Byspecial dispensation, this eliminates all existing prerequisites of.SUFFIXES. You can then write another rule to add the suffixes youwant. For example,

     .SUFFIXES:            # Delete the default suffixes
     .SUFFIXES: .c .o .h   # Define our suffix list

The ‘-r’ or ‘--no-builtin-rules’ flag causes the defaultlist of suffixes to be empty.

The variable SUFFIXES is defined to the default list of suffixesbeforemake reads any makefiles. You can change the list of suffixeswith a rule for the special target.SUFFIXES, but that does not alterthis variable.

Previous:  Suffix Rules,Up:  Implicit Rules

10.8 Implicit Rule Search Algorithm

Here is the proceduremake uses for searching for an implicit rulefor a target t. This procedure is followed for each double-colonrule with no recipe, for each target of ordinary rules none of which havea recipe, and for each prerequisite that is not the target of any rule. Itis also followed recursively for prerequisites that come from implicitrules, in the search for a chain of rules.

Suffix rules are not mentioned in this algorithm because suffix rules areconverted to equivalent pattern rules once the makefiles have been read in.

For an archive member target of the form‘archive(member)’, the following algorithm is runtwice, first using the entire target namet, and second using‘(member)’ as the targett if the first run found norule.

  1. Split t into a directory part, called d, and the rest,calledn. For example, if t is ‘src/foo.o’, thend is ‘src/’ andn is ‘foo.o’.
  2. Make a list of all the pattern rules one of whose targets matchest orn. If the target pattern contains a slash, it ismatched against t; otherwise, againstn.
  3. If any rule in that list is not a match-anything rule, thenremove all nonterminal match-anything rules from the list.
  4. Remove from the list all rules with no recipe.
  5. For each pattern rule in the list:
    1. Find the stem s, which is the nonempty part of t or nmatched by the ‘%’ in the target pattern.
    2. Compute the prerequisite names by substituting s for ‘%’; ifthe target pattern does not contain a slash, appendd tothe front of each prerequisite name.
    3. Test whether all the prerequisites exist or ought to exist. (If afile name is mentioned in the makefile as a target or as an explicitprerequisite, then we say it ought to exist.)

      If all prerequisites exist or ought to exist, or there are no prerequisites,then this rule applies.

  6. If no pattern rule has been found so far, try harder. For each pattern rule in the list:
    1. If the rule is terminal, ignore it and go on to the next rule.
    2. Compute the prerequisite names as before.
    3. Test whether all the prerequisites exist or ought to exist.
    4. For each prerequisite that does not exist, follow this algorithmrecursively to see if the prerequisite can be made by an implicitrule.
    5. If all prerequisites exist, ought to exist, or can bemade by implicit rules, then this rule applies.
  7. If no implicit rule applies, the rule for .DEFAULT, if any,applies. In that case, givet the same recipe that.DEFAULT has. Otherwise, there is no recipe fort.

Once a rule that applies has been found, for each target pattern ofthe rule other than the one that matchedt or n, the‘%’ in the pattern is replaced withs and the resultantfile name is stored until the recipe to remake the target filetis executed. After the recipe is executed, each of these stored filenames are entered into the data base and marked as having been updatedand having the same update status as the filet.

When the recipe of a pattern rule is executed for t, theautomatic variables are set corresponding to the target andprerequisites. SeeAutomatic Variables.

Next:  ,Previous:  Implicit Rules,Up:  Top

11 Using make to Update Archive Files

Archive files are files containing named subfiles calledmembers; they are maintained with the programar and theirmain use is as subroutine libraries for linking.

Next:  ,Previous:  Archives,Up:  Archives

11.1 Archive Members as Targets

An individual member of an archive file can be used as a target orprerequisite inmake. You specify the member named member inarchive file archive as follows:

     archive(member)

This construct is available only in targets and prerequisites, not inrecipes! Most programs that you might use in recipes do not supportthis syntax and cannot act directly on archive members. Onlyar and other programs specifically designed to operate onarchives can do so. Therefore, valid recipes to update an archivemember target probably must usear. For example, this rulesays to create a member hack.o in archivefoolib bycopying the file hack.o:

     foolib(hack.o) : hack.o
             ar cr foolib hack.o

In fact, nearly all archive member targets are updated in just this wayand there is an implicit rule to do it for you.Please note: The‘c’ flag toar is required if the archive file does notalready exist.

To specify several members in the same archive, you can write all themember names together between the parentheses. For example:

     foolib(hack.o kludge.o)

is equivalent to:

     foolib(hack.o) foolib(kludge.o)

You can also use shell-style wildcards in an archive member reference. SeeUsing Wildcard Characters in File Names. Forexample, ‘foolib(*.o)’ expands to all existing members of thefoolib archive whose names end in ‘.o’; perhaps‘foolib(hack.o) foolib(kludge.o)’.

Next:  ,Previous:  Archive Members,Up:  Archives

11.2 Implicit Rule for Archive Member Targets

Recall that a target that looks like a(m) stands for themember namedm in the archive file a.

When make looks for an implicit rule for such a target, as a specialfeature it considers implicit rules that match(m), as well asthose that match the actual targeta(m).

This causes one special rule whose target is (%) to match. Thisrule updates the targeta(m) by copying the fileminto the archive. For example, it will update the archive member targetfoo.a(bar.o) by copying thefile bar.o into thearchive foo.a as a member named bar.o.

When this rule is chained with others, the result is very powerful. Thus, ‘make "foo.a(bar.o)"’ (the quotes are needed to protect the‘(’ and ‘)’ from being interpreted specially by the shell) inthe presence of a file bar.c is enough to cause the followingrecipe to be run, even without a makefile:

     cc -c bar.c -o bar.o
     ar r foo.a bar.o
     rm -f bar.o

Here make has envisioned the file bar.o as an intermediatefile. SeeChains of Implicit Rules.

Implicit rules such as this one are written using the automatic variable‘$%’. SeeAutomatic Variables.

An archive member name in an archive cannot contain a directory name, butit may be useful in a makefile to pretend that it does. If you write anarchive member targetfoo.a(dir/file.o), make will performautomatic updating with this recipe:

     ar r foo.a dir/file.o

which has the effect of copying the file dir/file.o into a membernamedfile.o. In connection with such usage, the automatic variables%D and%F may be useful.

Previous:  Archive Update,Up:  Archive Update

11.2.1 Updating Archive Symbol Directories

An archive file that is used as a library usually contains a special membernamed __.SYMDEF that contains a directory of the external symbolnames defined by all the other members. After you update any othermembers, you need to update__.SYMDEF so that it will summarize theother members properly. This is done by running theranlib program:

     ranlib archivefile

Normally you would put this command in the rule for the archive file,and make all the members of the archive file prerequisites of that rule. For example,

     libfoo.a: libfoo.a(x.o) libfoo.a(y.o) ...
             ranlib libfoo.a

The effect of this is to update archive members x.o,y.o,etc., and then update the symbol directory member__.SYMDEF byrunning ranlib. The rules for updating the members are not shownhere; most likely you can omit them and use the implicit rule which copiesfiles into the archive, as described in the preceding section.

This is not necessary when using the GNU ar program, whichupdates the__.SYMDEF member automatically.

Next:  ,Previous:  Archive Update,Up:  Archives

11.3 Dangers When Using Archives

It is important to be careful when using parallel execution (the-j switch; seeParallel Execution) and archives. If multiple ar commands run at the same time on the same archivefile, they will not know about each other and can corrupt the file.

Possibly a future version of make will provide a mechanism tocircumvent this problem by serializing all recipes that operate on thesame archive file. But for the time being, you must either write yourmakefiles to avoid this problem in some other way, or not use -j.

Previous:  Archive Pitfalls,Up:  Archives

11.4 Suffix Rules for Archive Files

You can write a special kind of suffix rule for dealing with archivefiles. See Suffix Rules, for a full explanation of suffix rules. Archive suffix rules are obsolete in GNUmake, because patternrules for archives are a more general mechanism (seeArchive Update). But they are retained for compatibility with othermakes.

To write a suffix rule for archives, you simply write a suffix ruleusing the target suffix ‘.a’ (the usual suffix for archive files). For example, here is the old-fashioned suffix rule to update a libraryarchive from C source files:

     .c.a:
             $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
             $(AR) r $@ $*.o
             $(RM) $*.o

This works just as if you had written the pattern rule:

     (%.o): %.c
             $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
             $(AR) r $@ $*.o
             $(RM) $*.o

In fact, this is just what make does when it sees a suffix rulewith ‘.a’ as the target suffix. Any double-suffix rule‘.x.a’ is converted to a pattern rule with the targetpattern ‘(%.o)’ and a prerequisite pattern of ‘%.x’.

Since you might want to use ‘.a’ as the suffix for some other kindof file,make also converts archive suffix rules to pattern rulesin the normal way (seeSuffix Rules). Thus a double-suffix rule‘.x.a’ produces two pattern rules: ‘(%.o):%.x’ and ‘%.a: %.x’.

Next:  ,Previous:  Archives,Up:  Top

12 Features of GNU make

Here is a summary of the features of GNUmake, for comparisonwith and credit to other versions of make. We consider thefeatures ofmake in 4.2 BSD systems as a baseline. If you areconcerned with writing portable makefiles, you should not use thefeatures ofmake listed here, nor the ones in Missing.

Many features come from the version of make in System V.

  • The VPATH variable and its special meaning. See Searching Directories for Prerequisites. This feature exists in System V make, but is undocumented. It is documented in 4.3 BSD make (which says it mimics System V'sVPATH feature).
  • Included makefiles. See Including Other Makefiles. Allowing multiple files to be included with a single directive is a GNUextension.
  • Variables are read from and communicated via the environment. See Variables from the Environment.
  • Options passed through the variable MAKEFLAGS to recursiveinvocations ofmake. See Communicating Options to a Sub-make.
  • The automatic variable $% is set to the member namein an archive reference. SeeAutomatic Variables.
  • The automatic variables $@, $*, $<, $%,and $? have corresponding forms like $(@F) and$(@D). We have generalized this to$^ as an obviousextension. See Automatic Variables.
  • Substitution variable references. See Basics of Variable References.
  • The command line options ‘-b’ and ‘-m’, accepted andignored. In System Vmake, these options actually do something.
  • Execution of recursive commands to run make via the variableMAKE even if ‘-n’, ‘-q’ or ‘-t’ is specified. SeeRecursive Use of make.
  • Support for suffix ‘.a’ in suffix rules. SeeArchive Suffix Rules. This feature is obsolete in GNUmake, because thegeneral feature of rule chaining (see Chains of Implicit Rules) allows one pattern rule for installing members in anarchive (seeArchive Update) to be sufficient.
  • The arrangement of lines and backslash-newline combinations inrecipes is retained when the recipes are printed, so they appear asthey do in the makefile, except for the stripping of initialwhitespace.

The following features were inspired by various other versions ofmake. In some cases it is unclear exactly which versions inspiredwhich others.

  • Pattern rules using ‘%’. This has been implemented in several versions ofmake. We're not sure who invented it first, but it's been spread around a bit. SeeDefining and Redefining Pattern Rules.
  • Rule chaining and implicit intermediate files. This was implemented by Stu Feldman in his version ofmakefor AT&T Eighth Edition Research Unix, and later by Andrew Hume ofAT&T Bell Labs in hismk program (where he terms it“transitive closure”). We do not really know ifwe got this from either of them or thought it up ourselves at thesame time. SeeChains of Implicit Rules.
  • The automatic variable $^ containing a list of all prerequisitesof the current target. We did not invent this, but we have no idea whodid. SeeAutomatic Variables. The automatic variable$+ is a simple extension of$^.
  • The “what if” flag (‘-W’ in GNU make) was (as far as we know)invented by Andrew Hume in mk. SeeInstead of Executing Recipes.
  • The concept of doing several things at once (parallelism) exists inmany incarnations ofmake and similar programs, though not in theSystem V or BSD implementations. SeeRecipe Execution.
  • Modified variable references using pattern substitution come fromSunOS 4. SeeBasics of Variable References. This functionality was provided in GNUmake by thepatsubst function before the alternate syntax was implementedfor compatibility with SunOS 4. It is not altogether clear whoinspired whom, since GNUmake had patsubst before SunOS4 was released.
  • The special significance of ‘+’ characters preceding recipe lines(seeInstead of Executing Recipes) ismandated by IEEE Standard 1003.2-1992 (POSIX.2).
  • The ‘+=’ syntax to append to the value of a variable comes from SunOS4make. See Appending More Text to Variables.
  • The syntax ‘archive(mem1 mem2...)’ to listmultiple members in a single archive file comes from SunOS 4make. See Archive Members.
  • The -include directive to include makefiles with no error for anonexistent file comes from SunOS 4make. (But note that SunOS 4make does not allow multiple makefiles to be specified in one-include directive.) The same feature appears with the namesinclude in SGImake and perhaps others.

The remaining features are inventions new in GNU make:

Next:  ,Previous:  Features,Up:  Top

13 Incompatibilities and Missing Features

Themake programs in various other systems support a few featuresthat are not implemented in GNUmake. The POSIX.2 standard(IEEE Standard 1003.2-1992) which specifiesmake does notrequire any of these features.

  • A target of the form ‘file((entry))’ stands for a memberof archive filefile. The member is chosen, not by name, but bybeing an object file which defines the linker symbolentry.

    This feature was not put into GNU make because of thenonmodularity of putting knowledge intomake of the internalformat of archive file symbol tables. See Updating Archive Symbol Directories.

  • Suffixes (used in suffix rules) that end with the character ‘~’have a special meaning to System Vmake;they refer to the SCCS file that correspondsto the file one would get without the ‘~’. For example, thesuffix rule ‘.c~.o’ would make the filen.o fromthe SCCS file s.n.c. For complete coverage, a wholeseries of such suffix rules is required. SeeOld-Fashioned Suffix Rules.

    In GNU make, this entire series of cases is handled by twopattern rules for extraction from SCCS, in combination with thegeneral feature of rule chaining. SeeChains of Implicit Rules.

  • In System V and 4.3 BSD make, files found by VPATHsearch (seeSearching Directories for Prerequisites) have their names changed inside recipes. We feel itis much cleaner to always use automatic variables and thus make thisfeature obsolete.
  • In some Unix makes, the automatic variable $* appearing inthe prerequisites of a rule has the amazingly strange “feature” ofexpanding to the full name of thetarget of that rule. We cannotimagine what went on in the minds of Unix make developers to dothis; it is utterly inconsistent with the normal definition of$*.
  • In some Unix makes, implicit rule search (see Using Implicit Rules) is apparently done for alltargets, not just those without recipes. This means you cando: 
              foo.o:
                  cc -c foo.c

    and Unix make will intuit that foo.o depends onfoo.c.

    We feel that such usage is broken. The prerequisite properties ofmake are well-defined (for GNUmake, at least),and doing such a thing simply does not fit the model.

  • GNU make does not include any built-in implicit rules forcompiling or preprocessing EFL programs. If we hear of anyone who isusing EFL, we will gladly add them.
  • It appears that in SVR4 make, a suffix rule can be specifiedwith no recipe, and it is treated as if it had an empty recipe(seeEmpty Recipes). For example: 
              .c.a:

    will override the built-in .c.a suffix rule.

    We feel that it is cleaner for a rule without a recipe to always simplyadd to the prerequisite list for the target. The above example can beeasily rewritten to get the desired behavior in GNUmake: 

              .c.a: ;
  • Some versions of make invoke the shell with the ‘-e’ flag,except under ‘-k’ (seeTesting the Compilation of a Program). The ‘-e’ flag tells the shell to exit as soon as anyprogram it runs returns a nonzero status. We feel it is cleaner towrite each line of the recipe to stand on its own and not require thisspecial treatment.

Next:  ,Previous:  Missing,Up:  Top

14 Makefile Conventions

Thisdescribes conventions for writing the Makefiles for GNU programs. Using Automake will help you write a Makefile that follows theseconventions. For more information on portable Makefiles, seeposix andPortable Make Programming.

Next:  ,Up:  Makefile Conventions

14.1 General Conventions for Makefiles

Every Makefile should contain this line:

     SHELL = /bin/sh

to avoid trouble on systems where the SHELL variable might beinherited from the environment. (This is never a problem with GNUmake.)

Different make programs have incompatible suffix lists andimplicit rules, and this sometimes creates confusion or misbehavior. Soit is a good idea to set the suffix list explicitly using only thesuffixes you need in the particular Makefile, like this:

     .SUFFIXES:
     .SUFFIXES: .c .o

The first line clears out the suffix list, the second introduces allsuffixes which may be subject to implicit rules in this Makefile.

Don't assume that . is in the path for command execution. Whenyou need to run programs that are a part of your package during themake, please make sure that it uses./ if the program is built aspart of the make or$(srcdir)/ if the file is an unchanging partof the source code. Without one of these prefixes, the current searchpath is used.

The distinction between ./ (the build directory) and$(srcdir)/ (thesource directory) is important becauseusers can build in a separate directory using the ‘--srcdir’ optiontoconfigure. A rule of the form:

     foo.1 : foo.man sedscript
             sed -f sedscript foo.man > foo.1

will fail when the build directory is not the source directory, becausefoo.man andsedscript are in the source directory.

When using GNU make, relying on ‘VPATH’ to find the sourcefile will work in the case where there is a single dependency file,since themake automatic variable ‘$<’ will represent thesource file wherever it is. (Many versions ofmake set ‘$<’only in implicit rules.) A Makefile target like

     foo.o : bar.c
             $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o

should instead be written as

     foo.o : bar.c
             $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@

in order to allow ‘VPATH’ to work correctly. When the target hasmultiple dependencies, using an explicit ‘$(srcdir)’ is the easiestway to make the rule work well. For example, the target above forfoo.1 is best written as:

     foo.1 : foo.man sedscript
             sed -f $(srcdir)/sedscript $(srcdir)/foo.man > $@

GNU distributions usually contain some files which are not sourcefiles—for example, Info files, and the output from Autoconf, Automake,Bison or Flex. Since these files normally appear in the sourcedirectory, they should always appear in the source directory, not in thebuild directory. So Makefile rules to update them should put theupdated files in the source directory.

However, if a file does not appear in the distribution, then theMakefile should not put it in the source directory, because building aprogram in ordinary circumstances should not modify the source directoryin any way.

Try to make the build and installation targets, at least (and all theirsubtargets) work correctly with a parallelmake.

Next:  ,Previous:  Makefile Basics,Up:  Makefile Conventions

14.2 Utilities in Makefiles

Write the Makefile commands (and any shell scripts, such asconfigure) to run undersh (both the traditional Bourneshell and the posix shell), notcsh. Don't use anyspecial features of ksh or bash, orposix featuresnot widely supported in traditional Bourne sh.

The configure script and the Makefile rules for building andinstallation should not use any utilities directly except these:

     awk cat cmp cp diff echo egrep expr false grep install-info ln ls
     mkdir mv printf pwd rm rmdir sed sleep sort tar test touch tr true

Compression programs such as gzip can be used in thedist rule.

Generally, stick to the widely-supported (usuallyposix-specified) options and features of these programs. Forexample, don't use ‘mkdir -p’, convenient as it may be, because afew systems don't support it at all and with others, it is not safefor parallel execution. For a list of known incompatibilities, seePortable Shell Programming.

It is a good idea to avoid creating symbolic links in makefiles, since afew file systems don't support them.

The Makefile rules for building and installation can also use compilersand related programs, but should do so viamake variables so that theuser can substitute alternatives. Here are some of the programs wemean:

     ar bison cc flex install ld ldconfig lex
     make makeinfo ranlib texi2dvi yacc

Use the following make variables to run those programs:

     $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
     $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)

When you use ranlib or ldconfig, you should make surenothing bad happens if the system does not have the program in question. Arrange to ignore an error from that command, and print a message beforethe command to tell the user that failure of this command does not meana problem. (The Autoconf ‘AC_PROG_RANLIB’ macro can help withthis.)

If you use symbolic links, you should implement a fallback for systemsthat don't have symbolic links.

Additional utilities that can be used via Make variables are:

     chgrp chmod chown mknod

It is ok to use other utilities in Makefile portions (or scripts)intended only for particular systems where you know those utilitiesexist.

Next:  ,Previous:  Utilities in Makefiles,Up:  Makefile Conventions

14.3 Variables for Specifying Commands

Makefiles should provide variables for overriding certain commands, options,and so on.

In particular, you should run most utility programs via variables. Thus, if you use Bison, have a variable namedBISON whose defaultvalue is set with ‘BISON = bison’, and refer to it with$(BISON) whenever you need to use Bison.

File management utilities such as ln, rm, mv, andso on, need not be referred to through variables in this way, since usersdon't need to replace them with other programs.

Each program-name variable should come with an options variable that isused to supply options to the program. Append ‘FLAGS’ to theprogram-name variable name to get the options variable name—forexample,BISONFLAGS. (The names CFLAGS for the Ccompiler, YFLAGS for yacc, and LFLAGS for lex, areexceptions to this rule, but we keep them because they are standard.) UseCPPFLAGS in any compilation command that runs thepreprocessor, and useLDFLAGS in any compilation command thatdoes linking as well as in any direct use ofld.

If there are C compiler options that must be used for propercompilation of certain files, do not include them inCFLAGS. Users expect to be able to specify CFLAGS freely themselves. Instead, arrange to pass the necessary options to the C compilerindependently ofCFLAGS, by writing them explicitly in thecompilation commands or by defining an implicit rule, like this:

     CFLAGS = -g
     ALL_CFLAGS = -I. $(CFLAGS)
     .c.o:
             $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<

Do include the ‘-g’ option in CFLAGS, because that is notrequired for proper compilation. You can consider it a defaultthat is only recommended. If the package is set up so that it iscompiled with GCC by default, then you might as well include ‘-O’in the default value ofCFLAGS as well.

Put CFLAGS last in the compilation command, after other variablescontaining compiler options, so the user can useCFLAGS tooverride the others.

CFLAGS should be used in every invocation of the C compiler,both those which do compilation and those which do linking.

Every Makefile should define the variable INSTALL, which is thebasic command for installing a file into the system.

Every Makefile should also define the variables INSTALL_PROGRAMandINSTALL_DATA. (The default for INSTALL_PROGRAM shouldbe$(INSTALL); the default for INSTALL_DATA should be${INSTALL} -m 644.) Then it should use those variables as thecommands for actual installation, for executables and non-executablesrespectively. Minimal use of these variables is as follows:

     $(INSTALL_PROGRAM) foo $(bindir)/foo
     $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a

However, it is preferable to support a DESTDIR prefix on thetarget files, as explained in the next section.

It is acceptable, but not required, to install multiple files in onecommand, with the final argument being a directory, as in:

     $(INSTALL_PROGRAM) foo bar baz $(bindir)

Next:  ,Previous:  Command Variables,Up:  Makefile Conventions

14.4 DESTDIR: Support for Staged Installs

DESTDIR is a variable prepended to each installed target file,like this:

     $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
     $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a

The DESTDIR variable is specified by the user on the makecommand line as an absolute file name. For example:

     make DESTDIR=/tmp/stage install

DESTDIR should be supported only in the install* anduninstall* targets, as those are the only targets where it isuseful.

If your installation step would normally install/usr/local/bin/foo and/usr/local/lib/libfoo.a, then aninstallation invoked as in the example above would install/tmp/stage/usr/local/bin/foo and/tmp/stage/usr/local/lib/libfoo.a instead.

Prepending the variable DESTDIR to each target in this wayprovides forstaged installs, where the installed files are notplaced directly into their expected location but are instead copiedinto a temporary location (DESTDIR). However, installed filesmaintain their relative directory structure and any embedded file nameswill not be modified.

You should not set the value of DESTDIR in your Makefileat all; then the files are installed into their expected locations bydefault. Also, specifyingDESTDIR should not change theoperation of the software in any way, so its value should not beincluded in any file contents.

DESTDIR support is commonly used in package creation. It isalso helpful to users who want to understand what a given package willinstall where, and to allow users who don't normally have permissionsto install into protected areas to build and install before gainingthose permissions. Finally, it can be useful with tools such asstow, where code is installed in one place but made to appearto be installed somewhere else using symbolic links or special mountoperations. So, we strongly recommend GNU packages supportDESTDIR, though it is not an absolute requirement.

Next:  ,Previous:  DESTDIR,Up:  Makefile Conventions

14.5 Variables for Installation Directories

Installation directories should always be named by variables, so it iseasy to install in a nonstandard place. The standard names for thesevariables and the values they should have in GNU packages aredescribed below. They are based on a standard file system layout;variants of it are used in GNU/Linux and other modern operatingsystems.

Installers are expected to override these values when callingmake (e.g.,make prefix=/usr install orconfigure (e.g.,configure --prefix=/usr). GNUpackages should not try to guess which value should be appropriate forthese variables on the system they are being installed onto: use thedefault settings specified here so that all GNU packages behaveidentically, allowing the installer to achieve any desired layout.

All installation directories, and their parent directories, should becreated (if necessary) before they are installed into.

These first two variables set the root for the installation. All theother installation directories should be subdirectories of one ofthese two, and nothing should be directly installed into these twodirectories.

prefix
A prefix used in constructing the default values of the variables listedbelow. The default value of prefix should be /usr/local. When building the complete GNU system, the prefix will be empty and /usr will be a symbolic link to /. (If you are using Autoconf, write it as ‘ @prefix@’.)

Running ‘make install’ with a different value ofprefix fromthe one used to build the program should not recompile theprogram.

exec_prefix
A prefix used in constructing the default values of some of thevariables listed below. The default value of exec_prefix shouldbe $(prefix). (If you are using Autoconf, write it as ‘ @exec_prefix@’.)

Generally, $(exec_prefix) is used for directories that containmachine-specific files (such as executables and subroutine libraries),while$(prefix) is used directly for other directories.

Running ‘make install’ with a different value ofexec_prefixfrom the one used to build the program should not recompile theprogram.

Executable programs are installed in one of the following directories.

bindir
The directory for installing executable programs that users can run. This should normally be /usr/local/bin, but write it as $(exec_prefix)/bin. (If you are using Autoconf, write it as ‘ @bindir@’.)
sbindir
The directory for installing executable programs that can be run fromthe shell, but are only generally useful to system administrators. Thisshould normally be /usr/local/sbin, but write it as $(exec_prefix)/sbin. (If you are using Autoconf, write it as ‘ @sbindir@’.)
libexecdir
The directory for installing executable programs to be run by otherprograms rather than by users. This directory should normally be /usr/local/libexec, but write it as $(exec_prefix)/libexec. (If you are using Autoconf, write it as ‘ @libexecdir@’.)

The definition of ‘libexecdir’ is the same for all packages, soyou should install your data in a subdirectory thereof. Most packagesinstall their data under$(libexecdir)/package-name/,possibly within additional subdirectories thereof, such as$(libexecdir)/package-name/machine/version.

Data files used by the program during its execution are divided intocategories in two ways.

  • Some files are normally modified by programs; others are never normallymodified (though users may edit some of these).
  • Some files are architecture-independent and can be shared by allmachines at a site; some are architecture-dependent and can be sharedonly by machines of the same kind and operating system; others may neverbe shared between two machines.

This makes for six different possibilities. However, we want todiscourage the use of architecture-dependent files, aside from objectfiles and libraries. It is much cleaner to make other data filesarchitecture-independent, and it is generally not hard.

Here are the variables Makefiles should use to specify directoriesto put these various kinds of files in:

‘ datarootdir’
The root of the directory tree for read-only architecture-independentdata files. This should normally be /usr/local/share, butwrite it as $(prefix)/share. (If you are using Autoconf, writeit as ‘ @datarootdir@’.) ‘ datadir’'s default value isbased on this variable; so are ‘ infodir’, ‘ mandir’, andothers.
‘ datadir’
The directory for installing idiosyncratic read-onlyarchitecture-independent data files for this program. This is usuallythe same place as ‘ datarootdir’, but we use the two separatevariables so that you can move these program-specific files withoutaltering the location for Info files, man pages, etc.

This should normally be /usr/local/share, but write it as$(datarootdir). (If you are using Autoconf, write it as‘@datadir@’.)

The definition of ‘datadir’ is the same for all packages, so youshould install your data in a subdirectory thereof. Most packagesinstall their data under$(datadir)/package-name/.

‘ sysconfdir’
The directory for installing read-only data files that pertain to asingle machine–that is to say, files for configuring a host. Mailerand network configuration files, /etc/passwd, and so forth belonghere. All the files in this directory should be ordinary ASCII textfiles. This directory should normally be /usr/local/etc, butwrite it as $(prefix)/etc. (If you are using Autoconf, write it as ‘ @sysconfdir@’.)

Do not install executables here in this directory (they probably belongin $(libexecdir) or $(sbindir)). Also do not installfiles that are modified in the normal course of their use (programswhose purpose is to change the configuration of the system excluded). Those probably belong in $(localstatedir).

‘ sharedstatedir’
The directory for installing architecture-independent data files whichthe programs modify while they run. This should normally be /usr/local/com, but write it as $(prefix)/com. (If you are using Autoconf, write it as ‘ @sharedstatedir@’.)
‘ localstatedir’
The directory for installing data files which the programs modify whilethey run, and that pertain to one specific machine. Users should neverneed to modify files in this directory to configure the package'soperation; put such configuration information in separate files that goin $(datadir) or $(sysconfdir). $(localstatedir)should normally be /usr/local/var, but write it as $(prefix)/var. (If you are using Autoconf, write it as ‘ @localstatedir@’.)

These variables specify the directory for installing certain specifictypes of files, if your program has them. Every GNU package shouldhave Info files, so every program needs ‘infodir’, but not allneed ‘libdir’ or ‘lispdir’.

‘ includedir’
The directory for installing header files to be included by userprograms with the C ‘ #include’ preprocessor directive. Thisshould normally be /usr/local/include, but write it as $(prefix)/include. (If you are using Autoconf, write it as ‘ @includedir@’.)

Most compilers other than GCC do not look for header files in directory/usr/local/include. So installing the header files this way isonly useful with GCC. Sometimes this is not a problem because somelibraries are only really intended to work with GCC. But some librariesare intended to work with other compilers. They should install theirheader files in two places, one specified byincludedir and onespecified by oldincludedir.

‘ oldincludedir’
The directory for installing ‘ #include’ header files for use withcompilers other than GCC. This should normally be /usr/include. (If you are using Autoconf, you can write it as ‘ @oldincludedir@’.)

The Makefile commands should check whether the value ofoldincludedir is empty. If it is, they should not try to useit; they should cancel the second installation of the header files.

A package should not replace an existing header in this directory unlessthe header came from the same package. Thus, if your Foo packageprovides a header filefoo.h, then it should install the headerfile in theoldincludedir directory if either (1) there is nofoo.h there or (2) thefoo.h that exists came from the Foopackage.

To tell whether foo.h came from the Foo package, put a magicstring in the file—part of a comment—andgrep for that string.

‘ docdir’
The directory for installing documentation files (other than Info) forthis package. By default, it should be /usr/local/share/doc/yourpkg, but it should be written as $(datarootdir)/doc/yourpkg. (If you are using Autoconf,write it as ‘ @docdir@’.) The yourpkg subdirectory, whichmay include a version number, prevents collisions among files withcommon names, such as README.
‘ infodir’
The directory for installing the Info files for this package. Bydefault, it should be /usr/local/share/info, but it should bewritten as $(datarootdir)/info. (If you are using Autoconf,write it as ‘ @infodir@’.) infodir is separate from docdir for compatibility with existing practice.
‘ htmldir’ ‘ dvidir’ ‘ pdfdir’ ‘ psdir’
Directories for installing documentation files in the particularformat. They should all be set to $(docdir) by default. (Ifyou are using Autoconf, write them as ‘ @htmldir@’,‘ @dvidir@’, etc.) Packages which supply several translationsof their documentation should install them in‘ $(htmldir)/’ ll, ‘ $(pdfdir)/’ ll, etc. where ll is a locale abbreviation such as ‘ en’ or ‘ pt_BR’.
‘ libdir’
The directory for object files and libraries of object code. Do notinstall executables here, they probably ought to go in $(libexecdir)instead. The value of libdir should normally be /usr/local/lib, but write it as $(exec_prefix)/lib. (If you are using Autoconf, write it as ‘ @libdir@’.)
‘ lispdir’
The directory for installing any Emacs Lisp files in this package. Bydefault, it should be /usr/local/share/emacs/site-lisp, but itshould be written as $(datarootdir)/emacs/site-lisp.

If you are using Autoconf, write the default as ‘@lispdir@’. In order to make ‘@lispdir@’ work, you need the following linesin yourconfigure.in file: 

          lispdir='${datarootdir}/emacs/site-lisp'
          AC_SUBST(lispdir)

‘ localedir’
The directory for installing locale-specific message catalogs for thispackage. By default, it should be /usr/local/share/locale, butit should be written as $(datarootdir)/locale. (If you areusing Autoconf, write it as ‘ @localedir@’.) This directoryusually has a subdirectory per locale.

Unix-style man pages are installed in one of the following:

‘ mandir’
The top-level directory for installing the man pages (if any) for thispackage. It will normally be /usr/local/share/man, but youshould write it as $(datarootdir)/man. (If you are usingAutoconf, write it as ‘ @mandir@’.)
‘ man1dir’
The directory for installing section 1 man pages. Write it as $(mandir)/man1.
‘ man2dir’
The directory for installing section 2 man pages. Write it as $(mandir)/man2
‘ ...’
Don't make the primary documentation for any GNU software be aman page. Write a manual in Texinfo instead. Man pages are just forthe sake of people running GNU software on Unix, which is a secondaryapplication only.
‘ manext’
The file name extension for the installed man page. This should containa period followed by the appropriate digit; it should normally be ‘ .1’.
‘ man1ext’
The file name extension for installed section 1 man pages.
‘ man2ext’
The file name extension for installed section 2 man pages.
‘ ...’
Use these names instead of ‘ manext’ if the package needs to install manpages in more than one section of the manual.

And finally, you should set the following variable:

‘ srcdir’
The directory for the sources being compiled. The value of thisvariable is normally inserted by the configure shell script. (If you are using Autoconf, use ‘ srcdir = @srcdir@’.)

For example:

     
     
     # Common prefix for installation directories.
     # NOTE: This directory must exist when you start the install.
     prefix = /usr/local
     datarootdir = $(prefix)/share
     datadir = $(datarootdir)
     exec_prefix = $(prefix)
     # Where to put the executable for the command `gcc'.
     bindir = $(exec_prefix)/bin
     # Where to put the directories used by the compiler.
     libexecdir = $(exec_prefix)/libexec
     # Where to put the Info files.
     infodir = $(datarootdir)/info

If your program installs a large number of files into one of thestandard user-specified directories, it might be useful to group theminto a subdirectory particular to that program. If you do this, youshould write theinstall rule to create these subdirectories.

Do not expect the user to include the subdirectory name in the value ofany of the variables listed above. The idea of having a uniform set ofvariable names for installation directories is to enable the user tospecify the exact same values for several different GNU packages. Inorder for this to be useful, all the packages must be designed so thatthey will work sensibly when the user does so.

At times, not all of these variables may be implemented in the currentrelease of Autoconf and/or Automake; but as of Autoconf 2.60, webelieve all of them are. When any are missing, the descriptions hereserve as specifications for what Autoconf will implement. As aprogrammer, you can either use a development version of Autoconf oravoid using these variables until a stable release is made whichsupports them.

Next:  ,Previous:  Directory Variables,Up:  Makefile Conventions

14.6 Standard Targets for Users

All GNU programs should have the following targets in their Makefiles:

‘ all’
Compile the entire program. This should be the default target. Thistarget need not rebuild any documentation files; Info files shouldnormally be included in the distribution, and DVI (and otherdocumentation format) files should be made only when explicitly askedfor.

By default, the Make rules should compile and link with ‘-g’, sothat executable programs have debugging symbols. Users who don't mindbeing helpless can strip the executables later if they wish.

‘ install’
Compile the program and copy the executables, libraries, and so on tothe file names where they should reside for actual use. If there is asimple test to verify that a program is properly installed, this targetshould run that test.

Do not strip executables when installing them. Devil-may-care users canuse theinstall-strip target to do that.

If possible, write the install target rule so that it does notmodify anything in the directory where the program was built, provided‘make all’ has just been done. This is convenient for building theprogram under one user name and installing it under another.

The commands should create all the directories in which files are to beinstalled, if they don't already exist. This includes the directoriesspecified as the values of the variablesprefix andexec_prefix, as well as all subdirectories that are needed. One way to do this is by means of aninstalldirs targetas described below.

Use ‘-’ before any command for installing a man page, so thatmake will ignore any errors. This is in case there are systemsthat don't have the Unix man page documentation system installed.

The way to install Info files is to copy them into $(infodir)with$(INSTALL_DATA) (see Command Variables), and then runtheinstall-info program if it is present. install-infois a program that edits the Infodir file to add or update themenu entry for the given Info file; it is part of the Texinfo package.

Here is a sample rule to install an Info file that also tries tohandle some additional situations, such asinstall-info notbeing present. 

          do-install-info: foo.info installdirs
                  $(NORMAL_INSTALL)
          # Prefer an info file in . to one in srcdir.
                  if test -f foo.info; then d=.; \
                   else d="$(srcdir)"; fi; \
                  $(INSTALL_DATA) $$d/foo.info \
                    "$(DESTDIR)$(infodir)/foo.info"
          # Run install-info only if it exists.
          # Use `if' instead of just prepending `-' to the
          # line so we notice real errors from install-info.
          # Use `$(SHELL) -c' because some shells do not
          # fail gracefully when there is an unknown command.
                  $(POST_INSTALL)
                  if $(SHELL) -c 'install-info --version' \
                     >/dev/null 2>&1; then \
                    install-info --dir-file="$(DESTDIR)$(infodir)/dir" \
                                 "$(DESTDIR)$(infodir)/foo.info"; \
                  else true; fi

When writing the install target, you must classify all thecommands into three categories: normal ones,pre-installationcommands and post-installation commands. SeeInstall Command Categories.

‘ install-html’ ‘ install-dvi’ ‘ install-pdf’ ‘ install-ps’
These targets install documentation in formats other than Info;they're intended to be called explicitly by the person installing thepackage, if that format is desired. GNU prefers Info files, so thesemust be installed by the install target.

When you have many documentation files to install, we recommend thatyou avoid collisions and clutter by arranging for these targets toinstall in subdirectories of the appropriate installation directory,such ashtmldir. As one example, if your package has multiplemanuals, and you wish to install HTML documentation with many files(such as the “split” mode output bymakeinfo --html), you'llcertainly want to use subdirectories, or two nodes with the same namein different manuals will overwrite each other.

Please make these install-format targets invoke thecommands for theformat target, for example, by makingformat a dependency.

‘ uninstall’
Delete all the installed files—the copies that the ‘ install’and ‘ install-*’ targets create.

This rule should not modify the directories where compilation is done,only the directories where files are installed.

The uninstallation commands are divided into three categories, just likethe installation commands. SeeInstall Command Categories.

‘ install-strip’
Like install, but strip the executable files while installingthem. In simple cases, this target can use the install target ina simple way: 
          install-strip:
                  $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
                          install

But if the package installs scripts as well as real executables, theinstall-strip target can't just refer to theinstalltarget; it has to strip the executables but not the scripts.

install-strip should not strip the executables in the builddirectory which are being copied for installation. It should only stripthe copies that are installed.

Normally we do not recommend stripping an executable unless you are surethe program has no bugs. However, it can be reasonable to install astripped executable for actual execution while saving the unstrippedexecutable elsewhere in case there is a bug.

‘ clean’
Delete all files in the current directory that are normally created bybuilding the program. Also delete files in other directories if theyare created by this makefile. However, don't delete the files thatrecord the configuration. Also preserve files that could be made bybuilding, but normally aren't because the distribution comes withthem. There is no need to delete parent directories that were createdwith ‘ mkdir -p’, since they could have existed anyway.

Delete .dvi files here if they are not part of the distribution.

‘ distclean’
Delete all files in the current directory (or created by thismakefile) that are created by configuring or building the program. Ifyou have unpacked the source and built the program without creatingany other files, ‘ make distclean’ should leave only the filesthat were in the distribution. However, there is no need to deleteparent directories that were created with ‘ mkdir -p’, since theycould have existed anyway.
‘ mostlyclean’
Like ‘ clean’, but may refrain from deleting a few files that peoplenormally don't want to recompile. For example, the ‘ mostlyclean’target for GCC does not delete libgcc.a, because recompiling itis rarely necessary and takes a lot of time.
‘ maintainer-clean’
Delete almost everything that can be reconstructed with this Makefile. This typically includes everything deleted by distclean, plusmore: C source files produced by Bison, tags tables, Info files, andso on.

The reason we say “almost everything” is that running the command‘make maintainer-clean’ should not deleteconfigure evenif configure can be remade using a rule in the Makefile. Moregenerally, ‘make maintainer-clean’ should not delete anythingthat needs to exist in order to run configure and then begin tobuild the program. Also, there is no need to delete parentdirectories that were created with ‘mkdir -p’, since they couldhave existed anyway. These are the only exceptions;maintainer-clean should delete everything else that can berebuilt.

The ‘maintainer-clean’ target is intended to be used by a maintainer ofthe package, not by ordinary users. You may need special tools toreconstruct some of the files that ‘make maintainer-clean’ deletes. Since these files are normally included in the distribution, we don'ttake care to make them easy to reconstruct. If you find you need tounpack the full distribution again, don't blame us.

To help make users aware of this, the commands for the specialmaintainer-clean target should start with these two:

          @echo 'This command is intended for maintainers to use; it'
          @echo 'deletes files that may need special tools to rebuild.'

‘ TAGS’
Update a tags table for this program.
‘ info’
Generate any Info files needed. The best way to write the rules is asfollows: 
          info: foo.info
          
          foo.info: foo.texi chap1.texi chap2.texi
                  $(MAKEINFO) $(srcdir)/foo.texi

You must define the variable MAKEINFO in the Makefile. It shouldrun themakeinfo program, which is part of the Texinfodistribution.

Normally a GNU distribution comes with Info files, and that means theInfo files are present in the source directory. Therefore, the Makerule for an info file should update it in the source directory. Whenusers build the package, ordinarily Make will not update the Info filesbecause they will already be up to date.

‘ dvi’ ‘ html’ ‘ pdf’ ‘ ps’
Generate documentation files in the given format. These targetsshould always exist, but any or all can be a no-op if the given outputformat cannot be generated. These targets should not be dependenciesof the all target; the user must manually invoke them.

Here's an example rule for generating DVI files from Texinfo: 

          dvi: foo.dvi
          
          foo.dvi: foo.texi chap1.texi chap2.texi
                  $(TEXI2DVI) $(srcdir)/foo.texi

You must define the variable TEXI2DVI in the Makefile. It shouldrun the programtexi2dvi, which is part of the Texinfodistribution.3 Alternatively,write just the dependencies, and allow GNUmake to provide the command.

Here's another example, this one for generating HTML from Texinfo: 

          html: foo.html
          
          foo.html: foo.texi chap1.texi chap2.texi
                  $(TEXI2HTML) $(srcdir)/foo.texi

Again, you would define the variable TEXI2HTML in the Makefile;for example, it might runmakeinfo --no-split --html(makeinfo is part of the Texinfo distribution).

‘ dist’
Create a distribution tar file for this program. The tar file should beset up so that the file names in the tar file start with a subdirectoryname which is the name of the package it is a distribution for. Thisname can include the version number.

For example, the distribution tar file of GCC version 1.40 unpacks intoa subdirectory namedgcc-1.40.

The easiest way to do this is to create a subdirectory appropriatelynamed, useln or cp to install the proper files in it, andthen tar that subdirectory.

Compress the tar file with gzip. For example, the actualdistribution file for GCC version 1.40 is calledgcc-1.40.tar.gz. It is ok to support other free compression formats as well.

The dist target should explicitly depend on all non-source filesthat are in the distribution, to make sure they are up to date in thedistribution. SeeMaking Releases.

‘ check’
Perform self-tests (if any). The user must build the program beforerunning the tests, but need not install the program; you should writethe self-tests so that they work when the program is built but notinstalled.

The following targets are suggested as conventional names, for programsin which they are useful.

installcheck
Perform installation tests (if any). The user must build and installthe program before running the tests. You should not assume that $(bindir) is in the search path.
installdirs
It's useful to add a target named ‘ installdirs’ to create thedirectories where files are installed, and their parent directories. There is a script called mkinstalldirs which is convenient forthis; you can find it in the Gnulib package. You can use a rule like this: 
          # Make sure all installation directories (e.g. $(bindir))
          # actually exist by making them if necessary.
          installdirs: mkinstalldirs
                  $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
                                          $(libdir) $(infodir) \
                                          $(mandir)

or, if you wish to support DESTDIR (strongly encouraged),

          # Make sure all installation directories (e.g. $(bindir))
          # actually exist by making them if necessary.
          installdirs: mkinstalldirs
                  $(srcdir)/mkinstalldirs \
                      $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
                      $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
                      $(DESTDIR)$(mandir)

This rule should not modify the directories where compilation is done. It should do nothing but create installation directories.

Previous:  Standard Targets,Up:  Makefile Conventions

14.7 Install Command Categories

When writing theinstall target, you must classify all thecommands into three categories: normal ones,pre-installationcommands and post-installation commands.

Normal commands move files into their proper places, and set theirmodes. They may not alter any files except the ones that come entirelyfrom the package they belong to.

Pre-installation and post-installation commands may alter other files;in particular, they can edit global configuration files or data bases.

Pre-installation commands are typically executed before the normalcommands, and post-installation commands are typically run after thenormal commands.

The most common use for a post-installation command is to runinstall-info. This cannot be done with a normal command, sinceit alters a file (the Info directory) which does not come entirely andsolely from the package being installed. It is a post-installationcommand because it needs to be done after the normal command whichinstalls the package's Info files.

Most programs don't need any pre-installation commands, but we have thefeature just in case it is needed.

To classify the commands in the install rule into these threecategories, insertcategory lines among them. A category linespecifies the category for the commands that follow.

A category line consists of a tab and a reference to a special Makevariable, plus an optional comment at the end. There are threevariables you can use, one for each category; the variable namespecifies the category. Category lines are no-ops in ordinary executionbecause these three Make variables are normally undefined (and youshould not define them in the makefile).

Here are the three possible category lines, each with a comment thatexplains what it means:

             $(PRE_INSTALL)     # Pre-install commands follow.
             $(POST_INSTALL)    # Post-install commands follow.
             $(NORMAL_INSTALL)  # Normal commands follow.

If you don't use a category line at the beginning of the installrule, all the commands are classified as normal until the first categoryline. If you don't use any category lines, all the commands areclassified as normal.

These are the category lines for uninstall:

             $(PRE_UNINSTALL)     # Pre-uninstall commands follow.
             $(POST_UNINSTALL)    # Post-uninstall commands follow.
             $(NORMAL_UNINSTALL)  # Normal commands follow.

Typically, a pre-uninstall command would be used for deleting entriesfrom the Info directory.

If the install or uninstall target has any dependencieswhich act as subroutines of installation, then you should starteach dependency's commands with a category line, and start themain target's commands with a category line also. This way, you canensure that each command is placed in the right category regardless ofwhich of the dependencies actually run.

Pre-installation and post-installation commands should not run anyprograms except for these:

     [ basename bash cat chgrp chmod chown cmp cp dd diff echo
     egrep expand expr false fgrep find getopt grep gunzip gzip
     hostname install install-info kill ldconfig ln ls md5sum
     mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
     test touch true uname xargs yes

The reason for distinguishing the commands in this way is for the sakeof making binary packages. Typically a binary package contains all theexecutables and other files that need to be installed, and has its ownmethod of installing them—so it does not need to run the normalinstallation commands. But installing the binary package does need toexecute the pre-installation and post-installation commands.

Programs to build binary packages work by extracting thepre-installation and post-installation commands. Here is one way ofextracting the pre-installation commands (the-s option tomake is needed to silence messages about enteringsubdirectories):

     make -s -n install -o all \
           PRE_INSTALL=pre-install \
           POST_INSTALL=post-install \
           NORMAL_INSTALL=normal-install \
       | gawk -f pre-install.awk

where the file pre-install.awk could contain this:

     $0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0}
     on {print $0}
     $0 ~ /^pre-install[ \t]*$/ {on = 1}

Next:  ,Previous:  Makefile Conventions,Up:  Top

Appendix A Quick Reference

This appendix summarizes the directives, text manipulation functions,and special variables which GNUmake understands. See Special Targets,Catalogue of Implicit Rules,and Summary of Options,for other summaries.

Here is a summary of the directives GNU make recognizes:

define variable define variable = define variable := define variable += define variable ?= endef
Define multi-line variables.
See Multi-Line.
undefine variable
Undefining variables.
See Undefine Directive.
ifdef variable ifndef variable ifeq ( a , b ) ifeq " a " " b " ifeq ' a ' ' b ' ifneq ( a , b ) ifneq " a " " b " ifneq ' a ' ' b ' else endif
Conditionally evaluate part of the makefile.
See Conditionals.
include file -include file sinclude file
Include another makefile.
See Including Other Makefiles.
override variable-assignment
Define a variable, overriding any previous definition, even one fromthe command line.
See The override Directive.
export
Tell make to export all variables to child processes by default.
See Communicating Variables to a Sub-make.
export variable export variable-assignment unexport variable
Tell make whether or not to export a particular variable to childprocesses.
See Communicating Variables to a Sub-make.
private variable-assignment
Do not allow this variable assignment to be inherited by prerequisites.
See Suppressing Inheritance.
vpath pattern path
Specify a search path for files matching a ‘ %’ pattern.
See The vpath Directive.
vpath pattern
Remove all search paths previously specified for pattern.
vpath
Remove all search paths previously specified in any vpathdirective.

Here is a summary of the built-in functions (see Functions):

$(subst from , to , text )
Replace from with to in text.
See Functions for String Substitution and Analysis.
$(patsubst pattern , replacement , text )
Replace words matching pattern with replacement in text.
See Functions for String Substitution and Analysis.
$(strip string )
Remove excess whitespace characters from string.
See Functions for String Substitution and Analysis.
$(findstring find , text )
Locate find in text.
See Functions for String Substitution and Analysis.
$(filter pattern ..., text )
Select words in text that match one of the pattern words.
See Functions for String Substitution and Analysis.
$(filter-out pattern ..., text )
Select words in text that do not match any of the pattern words.
See Functions for String Substitution and Analysis.
$(sort list )
Sort the words in list lexicographically, removing duplicates.
See Functions for String Substitution and Analysis.
$(word n , text )
Extract the nth word (one-origin) of text.
See Functions for String Substitution and Analysis.
$(words text )
Count the number of words in text.
See Functions for String Substitution and Analysis.
$(wordlist s , e , text )
Returns the list of words in text from s to e.
See Functions for String Substitution and Analysis.
$(firstword names ...)
Extract the first word of names.
See Functions for String Substitution and Analysis.
$(lastword names ...)
Extract the last word of names.
See Functions for String Substitution and Analysis.
$(dir names ...)
Extract the directory part of each file name.
See Functions for File Names.
$(notdir names ...)
Extract the non-directory part of each file name.
See Functions for File Names.
$(suffix names ...)
Extract the suffix (the last ‘ .’ and following characters) of each file name.
See Functions for File Names.
$(basename names ...)
Extract the base name (name without suffix) of each file name.
See Functions for File Names.
$(addsuffix suffix , names ...)
Append suffix to each word in names.
See Functions for File Names.
$(addprefix prefix , names ...)
Prepend prefix to each word in names.
See Functions for File Names.
$(join list1 , list2 )
Join two parallel lists of words.
See Functions for File Names.
$(wildcard pattern ...)
Find file names matching a shell file name pattern ( not a‘ %’ pattern).
See The Function wildcard.
$(realpath names ...)
For each file name in names, expand to an absolute name thatdoes not contain any ., .., nor symlinks.
See Functions for File Names.
$(abspath names ...)
For each file name in names, expand to an absolute name thatdoes not contain any . or .. components, but preservessymlinks.
See Functions for File Names.
$(error text ...)
When this function is evaluated, make generates a fatal errorwith the message text.
See Functions That Control Make.
$(warning text ...)
When this function is evaluated, make generates a warning withthe message text.
See Functions That Control Make.
$(shell command )
Execute a shell command and return its output.
See The shell Function.
$(origin variable )
Return a string describing how the make variable variable wasdefined.
See The origin Function.
$(flavor variable )
Return a string describing the flavor of the make variable variable.
See The flavor Function.
$(foreach var , words , text )
Evaluate text with var bound to each word in words,and concatenate the results.
See The foreach Function.
$(if condition , then-part [, else-part ])
Evaluate the condition condition; if it's non-empty substitutethe expansion of the then-part otherwise substitute theexpansion of the else-part.
See Functions for Conditionals.
$(or condition1 [, condition2 [, condition3 ...]])
Evaluate each condition conditionN one at a time; substitute thefirst non-empty expansion. If all expansions are empty, substitutethe empty string.
See Functions for Conditionals.
$(and condition1 [, condition2 [, condition3 ...]])
Evaluate each condition conditionN one at a time; if anyexpansion results in the empty string substitute the empty string. Ifall expansions result in a non-empty string, substitute the expansionof the last condition.
See Functions for Conditionals.
$(call var , param ,...)
Evaluate the variable var replacing any references to $(1), $(2) with the first, second, etc. param values.
See The call Function.
$(eval text )
Evaluate text then read the results as makefile commands. Expands to the empty string.
See The eval Function.
$(value var )
Evaluates to the contents of the variable var, with no expansionperformed on it.
See The value Function.

Here is a summary of the automatic variables. See Automatic Variables,for full information.

$@
The file name of the target.
$%
The target member name, when the target is an archive member.
$<
The name of the first prerequisite.
$?
The names of all the prerequisites that arenewer than the target, with spaces between them. For prerequisites which are archive members, onlythe named member is used (see Archives).
$^ $+
The names of all the prerequisites, with spaces between them. Forprerequisites which are archive members, only the named member is used(see Archives). The value of $^ omits duplicateprerequisites, while $+ retains them and preserves their order.
$*
The stem with which an implicit rule matches(see How Patterns Match).
$(@D) $(@F)
The directory part and the file-within-directory part of $@.
$(*D) $(*F)
The directory part and the file-within-directory part of $*.
$(%D) $(%F)
The directory part and the file-within-directory part of $%.
$(<D) $(<F)
The directory part and the file-within-directory part of $<.
$(^D) $(^F)
The directory part and the file-within-directory part of $^.
$(+D) $(+F)
The directory part and the file-within-directory part of $+.
$(?D) $(?F)
The directory part and the file-within-directory part of $?.

These variables are used specially by GNU make:

MAKEFILES
Makefiles to be read on every invocation of make.
See The Variable MAKEFILES.
VPATH
Directory search path for files not found in the current directory.
See VPATH Search Path for All Prerequisites.
SHELL
The name of the system default command interpreter, usually /bin/sh. You can set SHELL in the makefile to change the shell used to runrecipes. See Recipe Execution. The SHELLvariable is handled specially when importing from and exporting to theenvironment. See Choosing the Shell.
MAKESHELL
On MS-DOS only, the name of the command interpreter that is to be usedby make. This value takes precedence over the value of SHELL. See MAKESHELL variable.
MAKE
The name with which make was invoked. Using this variable inrecipes has special meaning. See How the MAKE Variable Works.
MAKELEVEL
The number of levels of recursion (sub- makes).
See Variables/Recursion.
MAKEFLAGS
The flags given to make. You can set this in the environment ora makefile to set flags.
See Communicating Options to a Sub-make.

It is never appropriate to use MAKEFLAGS directly in arecipe line: its contents may not be quoted correctly for use in theshell. Always allow recursivemake's to obtain these valuesthrough the environment from its parent.

MAKECMDGOALS
The targets given to make on the command line. Setting thisvariable has no effect on the operation of make.
See Arguments to Specify the Goals.
CURDIR
Set to the pathname of the current working directory (after all -C options are processed, if any). Setting this variable has noeffect on the operation of make.
See Recursive Use of make.
SUFFIXES
The default list of suffixes before make reads any makefiles.
.LIBPATTERNS
Defines the naming of the libraries make searches for, and theirorder.
See Directory Search for Link Libraries.

Next:  ,Previous:  Quick Reference,Up:  Top

Appendix B Errors Generated by Make

Here is a list of the more common errors you might see generated bymake, and some information about what they mean and how to fixthem.

Sometimes make errors are not fatal, especially in the presenceof a- prefix on a recipe line, or the -k command lineoption. Errors that are fatal are prefixed with the string***.

Error messages are all either prefixed with the name of the program(usually ‘make’), or, if the error is found in a makefile, the nameof the file and linenumber containing the problem.

In the table below, these common prefixes are left off.

‘ [foo] ErrorNN’ ‘ [foo] signal description’
These errors are not really make errors at all. They mean that aprogram that make invoked as part of a recipe returned anon-0 error code (‘ ErrorNN’), which make interpretsas failure, or it exited in some other abnormal fashion (with asignal of some type). See Errors in Recipes.

If no *** is attached to the message, then the subprocess failedbut the rule in the makefile was prefixed with the- specialcharacter, so make ignored the error.

‘ missing separator. Stop.’ ‘ missing separator (did you mean TAB instead of 8 spaces?). Stop.’
This means that make could not understand much of anythingabout the makefile line it just read. GNU make looks forvarious separators ( :, =, recipe prefix characters,etc.) to indicate what kind of line it's parsing. This message meansit couldn't find a valid one.

One of the most common reasons for this message is that you (orperhaps your oh-so-helpful editor, as is the case with many MS-Windowseditors) have attempted to indent your recipe lines with spacesinstead of a tab character. In this case,make will use thesecond form of the error above. Remember that every line in therecipe must begin with a tab character (unless you set.RECIPEPREFIX; seeSpecial Variables). Eight spaces do notcount. SeeRule Syntax.

‘ recipe commences before first target. Stop.’ ‘ missing rule before recipe. Stop.’
This means the first thing in the makefile seems to be part of arecipe: it begins with a recipe prefix character and doesn't appear tobe a legal make directive (such as a variable assignment). Recipes must always be associated with a target.

The second form is generated if the line has a semicolon as the firstnon-whitespace character;make interprets this to mean you leftout the "target: prerequisite" section of a rule. SeeRule Syntax.

‘ No rule to make target `xxx'.’ ‘ No rule to make target `xxx', needed by `yyy'.’
This means that make decided it needed to build a target, butthen couldn't find any instructions in the makefile on how to do that,either explicit or implicit (including in the default rules database).

If you want that file to be built, you will need to add a rule to yourmakefile describing how that target can be built. Other possiblesources of this problem are typos in the makefile (if that filename iswrong) or a corrupted source tree (if that file is not supposed to bebuilt, but rather only a prerequisite).

‘ No targets specified and no makefile found. Stop.’ ‘ No targets. Stop.’
The former means that you didn't provide any targets to be built on thecommand line, and make couldn't find any makefiles to read in. The latter means that some makefile was found, but it didn't contain anydefault goal and none was given on the command line. GNU makehas nothing to do in these situations. See Arguments to Specify the Makefile.
‘ Makefile `xxx' was not found.’ ‘ Included makefile `xxx' was not found.’
A makefile specified on the command line (first form) or included(second form) was not found.
‘ warning: overriding recipe for target `xxx'’ ‘ warning: ignoring old recipe for target `xxx'’
GNU make allows only one recipe to be specified per target(except for double-colon rules). If you give a recipe for a targetwhich already has been defined to have one, this warning is issued andthe second recipe will overwrite the first. See Multiple Rules for One Target.
‘ Circular xxx <-yyy dependency dropped.’
This means that make detected a loop in the dependency graph:after tracing the prerequisite yyy of target xxx, and itsprerequisites, etc., one of them depended on xxx again.
‘ Recursive variable `xxx' references itself (eventually). Stop.’
This means you've defined a normal (recursive) make variable xxx that, when it's expanded, will refer to itself ( xxx). This is not allowed; either use simply-expanded variables ( :=) oruse the append operator ( +=). See How to Use Variables.
‘ Unterminated variable reference. Stop.’
This means you forgot to provide the proper closing parenthesisor brace in your variable or function reference.
‘ insufficient arguments to function `xxx'. Stop.’
This means you haven't provided the requisite number of arguments forthis function. See the documentation of the function for a descriptionof its arguments. See Functions for Transforming Text.
‘ missing target pattern. Stop.’ ‘ multiple target patterns. Stop.’ ‘ target pattern contains no `%'. Stop.’ ‘ mixed implicit and static pattern rules. Stop.’
These are generated for malformed static pattern rules. The first meansthere's no pattern in the target section of the rule; the second meansthere are multiple patterns in the target section; the third meansthe target doesn't contain a pattern character ( %); and thefourth means that all three parts of the static pattern rule containpattern characters ( %)–only the first two parts should. See Syntax of Static Pattern Rules.
‘ warning: -jN forced in submake: disabling jobserver mode.’
This warning and the next are generated if make detects errorconditions related to parallel processing on systems wheresub- makes can communicate (see Communicating Options to a Sub-make). This warning isgenerated if a recursive invocation of a make process is forcedto have ‘ -jN’ in its argument list (where N is greaterthan one). This could happen, for example, if you set the MAKEenvironment variable to ‘ make -j2’. In this case, thesub- make doesn't communicate with other make processes andwill simply pretend it has two jobs of its own.
‘ warning: jobserver unavailable: using -j1. Add `+' to parent make rule.’
In order for make processes to communicate, the parent will passinformation to the child. Since this could result in problems if thechild process isn't actually a make, the parent will only do thisif it thinks the child is a make. The parent uses the normalalgorithms to determine this (see How the MAKE Variable Works). If the makefile is constructed such that the parentdoesn't know the child is a make process, then the child willreceive only part of the information necessary. In this case, the childwill generate this warning message and proceed with its build in asequential manner.

Next:  ,Previous:  Error Messages,Up:  Top

Appendix C Complex Makefile Example

Here is the makefile for the GNU tar program. This is amoderately complex makefile.

Because it is the first target, the default goal is ‘all’. Aninteresting feature of this makefile is thattestpad.h is asource file automatically created by thetestpad program,itself compiled from testpad.c.

If you type ‘make’ or ‘make all’, thenmake createsthe tar executable, thermt daemon that providesremote tape access, and thetar.info Info file.

If you type ‘make install’, then make not only createstar, rmt, andtar.info, but also installsthem.

If you type ‘make clean’, then make removes the ‘.o’files, and thetar, rmt,testpad,testpad.h, andcore files.

If you type ‘make distclean’, then make not only removesthe same files as does ‘make clean’ but also theTAGS,Makefile, and config.status files. (Although it is not evident, this makefile (andconfig.status) is generated by the user with theconfigure program, which is provided in the tardistribution, but is not shown here.)

If you type ‘make realclean’, then make removes the samefiles as does ‘make distclean’ and also removes the Info filesgenerated fromtar.texinfo.

In addition, there are targets shar and dist that createdistribution kits.

     # Generated automatically from Makefile.in by configure.
     # Un*x Makefile for GNU tar program.
     # Copyright (C) 1991 Free Software Foundation, Inc.
     
     # This program is free software; you can redistribute
     # it and/or modify it under the terms of the GNU
     # General Public License ...
     ...
     ...
     
     SHELL = /bin/sh
     
     #### Start of system configuration section. ####
     
     srcdir = .
     
     # If you use gcc, you should either run the
     # fixincludes script that comes with it or else use
     # gcc with the -traditional option.  Otherwise ioctl
     # calls will be compiled incorrectly on some systems.
     CC = gcc -O
     YACC = bison -y
     INSTALL = /usr/local/bin/install -c
     INSTALLDATA = /usr/local/bin/install -c -m 644
     
     # Things you might add to DEFS:
     # -DSTDC_HEADERS        If you have ANSI C headers and
     #                       libraries.
     # -DPOSIX               If you have POSIX.1 headers and
     #                       libraries.
     # -DBSD42               If you have sys/dir.h (unless
     #                       you use -DPOSIX), sys/file.h,
     #                       and st_blocks in `struct stat'.
     # -DUSG                 If you have System V/ANSI C
     #                       string and memory functions
     #                       and headers, sys/sysmacros.h,
     #                       fcntl.h, getcwd, no valloc,
     #                       and ndir.h (unless
     #                       you use -DDIRENT).
     # -DNO_MEMORY_H         If USG or STDC_HEADERS but do not
     #                       include memory.h.
     # -DDIRENT              If USG and you have dirent.h
     #                       instead of ndir.h.
     # -DSIGTYPE=int         If your signal handlers
     #                       return int, not void.
     # -DNO_MTIO             If you lack sys/mtio.h
     #                       (magtape ioctls).
     # -DNO_REMOTE           If you do not have a remote shell
     #                       or rexec.
     # -DUSE_REXEC           To use rexec for remote tape
     #                       operations instead of
     #                       forking rsh or remsh.
     # -DVPRINTF_MISSING     If you lack vprintf function
     #                       (but have _doprnt).
     # -DDOPRNT_MISSING      If you lack _doprnt function.
     #                       Also need to define
     #                       -DVPRINTF_MISSING.
     # -DFTIME_MISSING       If you lack ftime system call.
     # -DSTRSTR_MISSING      If you lack strstr function.
     # -DVALLOC_MISSING      If you lack valloc function.
     # -DMKDIR_MISSING       If you lack mkdir and
     #                       rmdir system calls.
     # -DRENAME_MISSING      If you lack rename system call.
     # -DFTRUNCATE_MISSING   If you lack ftruncate
     #                       system call.
     # -DV7                  On Version 7 Unix (not
     #                       tested in a long time).
     # -DEMUL_OPEN3          If you lack a 3-argument version
     #                       of open, and want to emulate it
     #                       with system calls you do have.
     # -DNO_OPEN3            If you lack the 3-argument open
     #                       and want to disable the tar -k
     #                       option instead of emulating open.
     # -DXENIX               If you have sys/inode.h
     #                       and need it 94 to be included.
     
     DEFS =  -DSIGTYPE=int -DDIRENT -DSTRSTR_MISSING \
             -DVPRINTF_MISSING -DBSD42
     # Set this to rtapelib.o unless you defined NO_REMOTE,
     # in which case make it empty.
     RTAPELIB = rtapelib.o
     LIBS =
     DEF_AR_FILE = /dev/rmt8
     DEFBLOCKING = 20
     
     CDEBUG = -g
     CFLAGS = $(CDEBUG) -I. -I$(srcdir) $(DEFS) \
             -DDEF_AR_FILE=\"$(DEF_AR_FILE)\" \
             -DDEFBLOCKING=$(DEFBLOCKING)
     LDFLAGS = -g
     
     prefix = /usr/local
     # Prefix for each installed program,
     # normally empty or `g'.
     binprefix =
     
     # The directory to install tar in.
     bindir = $(prefix)/bin
     
     # The directory to install the info files in.
     infodir = $(prefix)/info
     
     #### End of system configuration section. ####
     
     SRCS_C  = tar.c create.c extract.c buffer.c   \
               getoldopt.c update.c gnu.c mangle.c \
               version.c list.c names.c diffarch.c \
               port.c wildmat.c getopt.c getopt1.c \
               regex.c
     SRCS_Y  = getdate.y
     SRCS    = $(SRCS_C) $(SRCS_Y)
     OBJS    = $(SRCS_C:.c=.o) $(SRCS_Y:.y=.o) $(RTAPELIB)
     AUX =   README COPYING ChangeLog Makefile.in  \
             makefile.pc configure configure.in \
             tar.texinfo tar.info* texinfo.tex \
             tar.h port.h open3.h getopt.h regex.h \
             rmt.h rmt.c rtapelib.c alloca.c \
             msd_dir.h msd_dir.c tcexparg.c \
             level-0 level-1 backup-specs testpad.c
     
     .PHONY: all
     all:    tar rmt tar.info
     
     tar:    $(OBJS)
             $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)
     
     rmt:    rmt.c
             $(CC) $(CFLAGS) $(LDFLAGS) -o $@ rmt.c
     
     tar.info: tar.texinfo
             makeinfo tar.texinfo
     
     .PHONY: install
     install: all
             $(INSTALL) tar $(bindir)/$(binprefix)tar
             -test ! -f rmt || $(INSTALL) rmt /etc/rmt
             $(INSTALLDATA) $(srcdir)/tar.info* $(infodir)
     
     $(OBJS): tar.h port.h testpad.h
     regex.o buffer.o tar.o: regex.h
     # getdate.y has 8 shift/reduce conflicts.
     
     testpad.h: testpad
             ./testpad
     
     testpad: testpad.o
             $(CC) -o $@ testpad.o
     
     TAGS:   $(SRCS)
             etags $(SRCS)
     
     .PHONY: clean
     clean:
             rm -f *.o tar rmt testpad testpad.h core
     
     .PHONY: distclean
     distclean: clean
             rm -f TAGS Makefile config.status
     
     .PHONY: realclean
     realclean: distclean
             rm -f tar.info*
     
     .PHONY: shar
     shar: $(SRCS) $(AUX)
             shar $(SRCS) $(AUX) | compress \
               > tar-`sed -e '/version_string/!d' \
                          -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
                          -e q
                          version.c`.shar.Z
     
     .PHONY: dist
     dist: $(SRCS) $(AUX)
             echo tar-`sed \
                  -e '/version_string/!d' \
                  -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
                  -e q
                  version.c` > .fname
             -rm -rf `cat .fname`
             mkdir `cat .fname`
             ln $(SRCS) $(AUX) `cat .fname`
             tar chZf `cat .fname`.tar.Z `cat .fname`
             -rm -rf `cat .fname` .fname
     
     tar.zoo: $(SRCS) $(AUX)
             -rm -rf tmp.dir
             -mkdir tmp.dir
             -rm tar.zoo
             for X in $(SRCS) $(AUX) ; do \
                 echo $$X ; \
                 sed 's/$$/^M/' $$X \
                 > tmp.dir/$$X ; done
             cd tmp.dir ; zoo aM ../tar.zoo *
             -rm -rf tmp.dir

Next:  ,Previous:  Complex Makefile,Up:  Top

C.1 GNU Free Documentation License

Version 1.3, 3 November 2008 
     Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
     http://fsf.org/
     
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or otherfunctional and useful documentfree in the sense of freedom: toassure everyone the effective freedom to copy and redistribute it,with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a wayto get credit for their work, while not being considered responsiblefor modifications made by others.

    This License is a kind of “copyleft”, which means that derivativeworks of the document must themselves be free in the same sense. Itcomplements the GNU General Public License, which is a copyleftlicense designed for free software.

    We have designed this License in order to use it for manuals for freesoftware, because free software needs free documentation: a freeprogram should come with manuals providing the same freedoms that thesoftware does. But this License is not limited to software manuals;it can be used for any textual work, regardless of subject matter orwhether it is published as a printed book. We recommend this Licenseprincipally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work, in any medium, thatcontains a notice placed by the copyright holder saying it can bedistributed under the terms of this License. Such a notice grants aworld-wide, royalty-free license, unlimited in duration, to use thatwork under the conditions stated herein. The “Document”, below,refers to any such manual or work. Any member of the public is alicensee, and is addressed as “you”. You accept the license if youcopy, modify or distribute the work in a way requiring permissionunder copyright law.

    A “Modified Version” of the Document means any work containing theDocument or a portion of it, either copied verbatim, or withmodifications and/or translated into another language.

    A “Secondary Section” is a named appendix or a front-matter sectionof the Document that deals exclusively with the relationship of thepublishers or authors of the Document to the Document's overallsubject (or to related matters) and contains nothing that could falldirectly within that overall subject. (Thus, if the Document is inpart a textbook of mathematics, a Secondary Section may not explainany mathematics.) The relationship could be a matter of historicalconnection with the subject or with related matters, or of legal,commercial, philosophical, ethical or political position regardingthem.

    The “Invariant Sections” are certain Secondary Sections whose titlesare designated, as being those of Invariant Sections, in the noticethat says that the Document is released under this License. If asection does not fit the above definition of Secondary then it is notallowed to be designated as Invariant. The Document may contain zeroInvariant Sections. If the Document does not identify any InvariantSections then there are none.

    The “Cover Texts” are certain short passages of text that are listed,as Front-Cover Texts or Back-Cover Texts, in the notice that says thatthe Document is released under this License. A Front-Cover Text maybe at most 5 words, and a Back-Cover Text may be at most 25 words.

    A “Transparent” copy of the Document means a machine-readable copy,represented in a format whose specification is available to thegeneral public, that is suitable for revising the documentstraightforwardly with generic text editors or (for images composed ofpixels) generic paint programs or (for drawings) some widely availabledrawing editor, and that is suitable for input to text formatters orfor automatic translation to a variety of formats suitable for inputto text formatters. A copy made in an otherwise Transparent fileformat whose markup, or absence of markup, has been arranged to thwartor discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amountof text. A copy that is not “Transparent” is called “Opaque”.

    Examples of suitable formats for Transparent copies include plainASCII without markup, Texinfo input format, LaTeX inputformat, SGML or XML using a publicly availableDTD, and standard-conforming simple HTML,PostScript or PDF designed for human modification. Examplesof transparent image formats include PNG, XCF andJPG. Opaque formats include proprietary formats that can beread and edited only by proprietary word processors, SGML orXML for which the DTD and/or processing tools arenot generally available, and the machine-generated HTML,PostScript or PDF produced by some word processors foroutput purposes only.

    The “Title Page” means, for a printed book, the title page itself,plus such following pages as are needed to hold, legibly, the materialthis License requires to appear in the title page. For works informats which do not have any title page as such, “Title Page” meansthe text near the most prominent appearance of the work's title,preceding the beginning of the body of the text.

    The “publisher” means any person or entity that distributes copiesof the Document to the public.

    A section “Entitled XYZ” means a named subunit of the Document whosetitle either is precisely XYZ or contains XYZ in parentheses followingtext that translates XYZ in another language. (Here XYZ stands for aspecific section name mentioned below, such as “Acknowledgements”,“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title”of such a section when you modify the Document means that it remains asection “Entitled XYZ” according to this definition.

    The Document may include Warranty Disclaimers next to the notice whichstates that this License applies to the Document. These WarrantyDisclaimers are considered to be included by reference in thisLicense, but only as regards disclaiming warranties: any otherimplication that these Warranty Disclaimers may have is void and hasno effect on the meaning of this License.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, eithercommercially or noncommercially, provided that this License, thecopyright notices, and the license notice saying this License appliesto the Document are reproduced in all copies, and that you add no otherconditions whatsoever to those of this License. You may not usetechnical measures to obstruct or control the reading or furthercopying of the copies you make or distribute. However, you may acceptcompensation in exchange for copies. If you distribute a large enoughnumber of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, andyou may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies (or copies in media that commonly haveprinted covers) of the Document, numbering more than 100, and theDocument's license notice requires Cover Texts, you must enclose thecopies in covers that carry, clearly and legibly, all these CoverTexts: Front-Cover Texts on the front cover, and Back-Cover Texts onthe back cover. Both covers must also clearly and legibly identifyyou as the publisher of these copies. The front cover must presentthe full title with all words of the title equally prominent andvisible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preservethe title of the Document and satisfy these conditions, can be treatedas verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fitlegibly, you should put the first ones listed (as many as fitreasonably) on the actual cover, and continue the rest onto adjacentpages.

    If you publish or distribute Opaque copies of the Document numberingmore than 100, you must either include a machine-readable Transparentcopy along with each Opaque copy, or state in or with each Opaque copya computer-network location from which the general network-usingpublic has access to download using public-standard network protocolsa complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps,when you begin distribution of Opaque copies in quantity, to ensurethat this Transparent copy will remain thus accessible at the statedlocation until at least one year after the last time you distribute anOpaque copy (directly or through your agents or retailers) of thatedition to the public.

    It is requested, but not required, that you contact the authors of theDocument well before redistributing any large number of copies, to givethem a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document underthe conditions of sections 2 and 3 above, provided that you releasethe Modified Version under precisely this License, with the ModifiedVersion filling the role of the Document, thus licensing distributionand modification of the Modified Version to whoever possesses a copyof it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinctfrom that of the Document, and from those of previous versions(which should, if there were any, be listed in the History sectionof the Document). You may use the same title as a previous versionif the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entitiesresponsible for authorship of the modifications in the ModifiedVersion, together with at least five of the principal authors of theDocument (all of its principal authors, if it has fewer than five),unless they release you from this requirement.
    3. State on the Title page the name of the publisher of theModified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modificationsadjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license noticegiving the public permission to use the Modified Version under theterms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sectionsand required Cover Texts given in the Document's license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section Entitled “History”, Preserve its Title, and addto it an item stating at least the title, year, new authors, andpublisher of the Modified Version as given on the Title Page. Ifthere is no section Entitled “History” in the Document, create onestating the title, year, authors, and publisher of the Document asgiven on its Title Page, then add an item describing the ModifiedVersion as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document forpublic access to a Transparent copy of the Document, and likewisethe network locations given in the Document for previous versionsit was based on. These may be placed in the “History” section. You may omit a network location for a work that was published atleast four years before the Document itself, or if the originalpublisher of the version it refers to gives permission.
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preservethe Title of the section, and preserve in the section all thesubstance and tone of each of the contributor acknowledgements and/ordedications given therein.
    12. Preserve all the Invariant Sections of the Document,unaltered in their text and in their titles. Section numbersor the equivalent are not considered part of the section titles.
    13. Delete any section Entitled “Endorsements”. Such a sectionmay not be included in the Modified Version.
    14. Do not retitle any existing section to be Entitled “Endorsements” orto conflict in title with any Invariant Section.
    15. Preserve any Warranty Disclaimers.

    If the Modified Version includes new front-matter sections orappendices that qualify as Secondary Sections and contain no materialcopied from the Document, you may at your option designate some or allof these sections as invariant. To do this, add their titles to thelist of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

    You may add a section Entitled “Endorsements”, provided it containsnothing but endorsements of your Modified Version by variousparties—for example, statements of peer review or that the text hasbeen approved by an organization as the authoritative definition of astandard.

    You may add a passage of up to five words as a Front-Cover Text, and apassage of up to 25 words as a Back-Cover Text, to the end of the listof Cover Texts in the Modified Version. Only one passage ofFront-Cover Text and one of Back-Cover Text may be added by (orthrough arrangements made by) any one entity. If the Document alreadyincludes a cover text for the same cover, previously added by you orby arrangement made by the same entity you are acting on behalf of,you may not add another; but you may replace the old one, on explicitpermission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this Licensegive permission to use their names for publicity for or to assert orimply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under thisLicense, under the terms defined in section 4 above for modifiedversions, provided that you include in the combination all of theInvariant Sections of all of the original documents, unmodified, andlist them all as Invariant Sections of your combined work in itslicense notice, and that you preserve all their Warranty Disclaimers.

    The combined work need only contain one copy of this License, andmultiple identical Invariant Sections may be replaced with a singlecopy. If there are multiple Invariant Sections with the same name butdifferent contents, make the title of each such section unique byadding at the end of it, in parentheses, the name of the originalauthor or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list ofInvariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections Entitled “History”in the various original documents, forming one section Entitled“History”; likewise combine any sections Entitled “Acknowledgements”,and any sections Entitled “Dedications”. You must delete allsections Entitled “Endorsements.”

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documentsreleased under this License, and replace the individual copies of thisLicense in the various documents with a single copy that is included inthe collection, provided that you follow the rules of this License forverbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distributeit individually under this License, provided you insert a copy of thisLicense into the extracted document, and follow this License in allother respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separateand independent documents or works, in or on a volume of a storage ordistribution medium, is called an “aggregate” if the copyrightresulting from the compilation is not used to limit the legal rightsof the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does notapply to the other works in the aggregate which are not themselvesderivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to thesecopies of the Document, then if the Document is less than one half ofthe entire aggregate, the Document's Cover Texts may be placed oncovers that bracket the Document within the aggregate, or theelectronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the wholeaggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you maydistribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires specialpermission from their copyright holders, but you may includetranslations of some or all Invariant Sections in addition to theoriginal versions of these Invariant Sections. You may include atranslation of this License, and all the license notices in theDocument, and any Warranty Disclaimers, provided that you also includethe original English version of this License and the original versionsof those notices and disclaimers. In case of a disagreement betweenthe translation and the original version of this License or a noticeor disclaimer, the original version will prevail.

    If a section in the Document is Entitled “Acknowledgements”,“Dedications”, or “History”, the requirement (section 4) to Preserveits Title (section 1) will typically require changing the actualtitle.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Documentexcept as expressly provided under this License. Any attemptotherwise to copy, modify, sublicense, or distribute it is void, andwill automatically terminate your rights under this License.

    However, if you cease all violation of this License, then your licensefrom a particular copyright holder is reinstated (a) provisionally,unless and until the copyright holder explicitly and finallyterminates your license, and (b) permanently, if the copyright holderfails to notify you of the violation by some reasonable means prior to60 days after the cessation.

    Moreover, your license from a particular copyright holder isreinstated permanently if the copyright holder notifies you of theviolation by some reasonable means, this is the first time you havereceived notice of violation of this License (for any work) from thatcopyright holder, and you cure the violation prior to 30 days afteryour receipt of the notice.

    Termination of your rights under this section does not terminate thelicenses of parties who have received copies or rights from you underthis License. If your rights have been terminated and not permanentlyreinstated, receipt of a copy of some or all of the same material doesnot give you any rights to use it.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versionsof the GNU Free Documentation License from time to time. Such newversions will be similar in spirit to the present version, but maydiffer in detail to address new problems or concerns. Seehttp://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of thisLicense “or any later version” applies to it, you have the option offollowing the terms and conditions either of that specified version orof any later version that has been published (not as a draft) by theFree Software Foundation. If the Document does not specify a versionnumber of this License, you may choose any version ever published (notas a draft) by the Free Software Foundation. If the Documentspecifies that a proxy can decide which future versions of thisLicense can be used, that proxy's public statement of acceptance of aversion permanently authorizes you to choose that version for theDocument.

  12. RELICENSING

    “Massive Multiauthor Collaboration Site” (or “MMC Site”) means anyWorld Wide Web server that publishes copyrightable works and alsoprovides prominent facilities for anybody to edit those works. Apublic wiki that anybody can edit is an example of such a server. A“Massive Multiauthor Collaboration” (or “MMC”) contained in thesite means any set of copyrightable works thus published on the MMCsite.

    “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0license published by Creative Commons Corporation, a not-for-profitcorporation with a principal place of business in San Francisco,California, as well as future copyleft versions of that licensepublished by that same organization.

    “Incorporate” means to publish or republish a Document, in whole orin part, as part of another Document.

    An MMC is “eligible for relicensing” if it is licensed under thisLicense, and if all works that were first published under this Licensesomewhere other than this MMC, and subsequently incorporated in wholeor in part into the MMC, (1) had no cover texts or invariant sections,and (2) were thus incorporated prior to November 1, 2008.

    The operator of an MMC Site may republish an MMC contained in the siteunder CC-BY-SA on the same site at any time before August 1, 2009,provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy ofthe License in the document and put the following copyright andlicense notices just after the title page:

       Copyright (C)  year  your name.
       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, no Front-Cover Texts, and no Back-Cover
       Texts.  A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,replace the “with...Texts.” line with this:

         with the Invariant Sections being list their titles, with
         the Front-Cover Texts being list, and with the Back-Cover Texts
         being list.

If you have Invariant Sections without Cover Texts, or some othercombination of the three, merge those two alternatives to suit thesituation.

If your document contains nontrivial examples of program code, werecommend releasing these examples in parallel under your choice offree software license, such as the GNU General Public License,to permit their use in free software.

Next:  ,Previous:  GNU Free Documentation License,Up:  Top

Index of Concepts

Previous:  Concept Index,Up:  Top

Index of Functions, Variables, & Directives

Footnotes

[1] GNU Make compiled for MS-DOS and MS-Windows behaves as ifprefix has been defined to be the root of the DJGPP treehierarchy.

[2] OnMS-DOS, the value of current working directory isglobal, sochanging it will affect the following recipe lines on thosesystems.

[3] texi2dvi uses TeX to do the real workof formatting. TeX is not distributed with Texinfo.

perry_peng
关注
专栏目录
windows 安装make （gnu make）
03-04
在Windows操作系统上安装GNU Make是开发过程中的常见需求，尤其是对于那些经常进行C或C++编程，或是使用基于Makefile的构建系统的人来说。GNU Make是一个自动化构建工具，它能够读取名为“Makefile”的文件，根据...
centos7离线源码安装make
11-26
在Linux系统中，`make`是一个非常重要的工具，它帮助开发者构建、编译源代码，大大简化了软件的编译过程。在CentOS 7环境下，由于网络限制或安全策略，有时我们需要离线方式进行源码安装`make`。本文将详细介绍如何...
wget
perry_peng的专栏
01-07 1万+
<!-- pre.display {font-family:inherit} pre.format {font-family:inherit} pre.smalldisplay {font-family:inherit; font-size:smaller} pre.smallformat {font-family:inherit; font-size:smalle
wget使用 （代理，header，referer 超时限制,次数限制）
guoguo1980的专栏
02-21 1万+
wget -Y on -e "http_proxy=http://[User]:[Password]@ProxyServer:Port/""http://www.jukuu.com"-O a.html -t 2 --timeout=40 --header="User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; zh-CN; rv:1
wget命令详解_Linux命令详解（一）
weixin_39681644的博客
12-12 116
Linux命令详解(一)今日详解 ❍locate▶locate 命令可以快速的定位文件，特别是在用户完全不知道文件放在哪里的时候，locate命令是个不错的选择，如下：[WWW@log01 ~]$ locate *exe/usr/bin/gzexe/usr/lib64/python2.6/distutils/command/wininst-6.0.exe/usr/lib64/python...
Linux shell编程学习笔记80：gzip命令——让文件瘦身
最新发布
Purpleendurer@CSDN
09-14 1616
之前我们分别介绍了用于文件和目录归档的tar和cpio命令，为了缩小归档文件的体积，我们还可以使用压缩软件对归档文件进行压缩。在Windows系统中，我们常用的压缩软件有，在Linux系统中，用的压缩软件有gzip，pbzip2等。今天我们重点研究gzip。
automake使用说明
weixin_33757609的博客
08-15 312
automake Automake is a tool for automatically generating Makefile.in files compliant with the GNU Coding Standards. Automake requires the use of Autoconf. 复制代码 目前automake支持三种目录层次：flat、shallow和deep。 ...
windows 64位的 make 工具
10-21
"Windows 64位的make工具"是指在64位Windows操作系统上使用的构建系统工具，它使得开发者能够在该平台上执行类似Unix/Linux系统的make命令来管理项目构建流程。在Windows环境下，make工具通常被用来协调C++或者其他...
make-3.81.rar
08-18
《make-3.81在Windows环境下的应用与安装》 `make-3.81.rar`是一个包含`make-3.81.exe`可执行文件的压缩包，主要用于在Windows 10操作系统中安装`make`命令工具。`make`是软件构建工具，它在编程领域中扮演着至关...
linux中无make命令的问题(make: *** 没有指明目标并且找不到 makefile及make命令安装方法)
09-14
在Linux操作系统中，`make`命令是一个至关重要的工具，它用于自动化构建软件项目，特别是当项目包含大量编译和链接步骤时。`make`通过读取名为`Makefile`的文件来确定如何构建项目。然而，有时候在新安装或者精简版...
man gzip
weixin_30508241的博客
05-09 269
GZIP(1) GZIP(1) NAME/名称 gzip, gunzip, zcat - compress or expand files/压缩或展开文件 SYNOPSIS/简介 gzip [ -acdfhlLnNrtvV19 ] [...
GZIP(1)
weixin_34029680的博客
05-29 203
为什么80%的码农都做不了架构师？>>> ...
linux如何压缩为gz文件,将一个.gz文件拆分为多个1GB压缩（.gz）文件
weixin_31702225的博客
04-28 3368
我在Linux上有一个250GB的压缩文件，我想将它拆分为250个1GB文件，并在运行时压缩生成的部分文件(只要一个文件被生成，它应该被压缩)。 我试图用这个 -将一个.gz文件拆分为多个1GB压缩(.gz)文件zcat file.gz | split -b 1G – file.gz.part但这产生未压缩的文件有很强的针对性。我修改它看起来像这样，但得到了一个错误：zcat file.gz | ...
wget下载网盘分享文件
turnaroundfor的博客
05-08 3404
下载思路 网页或迅雷打开分享链接 获取真实下载地址 使用wget进行下载 百度网盘 用户分享： 链接：https://pan.baidu.com/s/1tMQ3lix2YrGZif8c3_qJ6A 提取码：p2ge 使用迅雷打开分享链接 点击下载 获取真实链接地址：https://xact02.baidupcs.com/file/a08fbaa64p87a4791129004804b3...
buildroot制作编译环境全过程解决 － 2
merry3688的专栏
07-08 5666
<br />上接:<br />buildroot制作编译环境全过程解决<br />http://hi.baidu.com/serial_story/blog/item/1684ef16c04a3711962b433e.html<br />------------------------------------------------------------------------------------------------------------------------<br /><br />找到最后，
wget使用
weixin_34234823的博客
08-31 985
一 wget简介wget是linux上的命令行的下载工具。这是一个GPL许可证下的自由软件。wget支持HTTP和FTP协议，支持代理服务器和断点续传功能，能够自动递归远程主机的目录，找到合乎条件的文件并将其下载到本地硬盘上；如果必要，wget将恰当地转换页面中的超级连接以在本地生成可浏览的镜像。由于没有交互式界面，wget可在后台运行，截获并忽略HANGUP信号，因此在用户推出登录以后，仍可继续...
用命令:tar -zxvf，解压tar.gz包失败的问题解决。
热门推荐
liuzhongye博客
05-14 2万+
问题描述： 主机上，使用tar -zxvf 解压tar.gz包的时候，出现以下错误： gzip: stdin: not in gzip format tar: Child returned status 1 tar: Error is not recoverable: exiting now 问题办法： 开门见山，先给出解决我这问题的办法。我的错误原因很简单：就是要解压的tar.gz包格式有错误。 用file FILE_NAME 命令，发现是data。 正确的格式应该是：gzip com
永久屏蔽警告：grep: warning: GREP_OPTIONS is deprecated； please use an alias or script
o0haidee0o的博客
06-29 7138
临时方法： unset GREP_OPTIONS 永久方法： 编辑~/.bashrc文件 vim ~/.bashrc 注释掉如下语句 export GREP_OPTIONS="--color=auto" GREP_COLOR="1;31" 保存退出后就不会再出现这个警告了，但是你会发现，grep没有高亮颜色了。所以，在这句话后面再加两行（注意缩进）： alias grep='grep --color=always -i' export GREP_COLOR="1;31" 修
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值