| \input texinfo @c -*- Texinfo -*- |
| @setfilename make.info |
| @synindex vr fn |
| |
| @c $Header$ |
| |
| @ifinfo |
| This file documents the GNU Make utility. |
| |
| Copyright (C) 1988 Free Software Foundation, Inc. |
| |
| Permission is granted to make and distribute verbatim copies of |
| this manual provided the copyright notice and this permission notice |
| are preserved on all copies. |
| |
| @ignore |
| Permission is granted to process this file through TeX and print the |
| results, provided the printed document carries copying permission |
| notice identical to this one except for the removal of this paragraph |
| (this paragraph not being relevant to the printed manual). |
| |
| @end ignore |
| Permission is granted to copy and distribute modified versions of this |
| manual under the conditions for verbatim copying, provided that the entire |
| resulting derived work is distributed under the terms of a permission |
| notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this manual |
| into another language, under the above conditions for modified versions. |
| @end ifinfo |
| @c |
| @setchapternewpage odd |
| @settitle Make |
| |
| @titlepage |
| @sp 6 |
| @center @titlefont{GNU Make} |
| @sp 1 |
| @center A Program for Directing Recompilation |
| @sp 2 |
| @center April 1988 |
| @sp 5 |
| @center Richard M. Stallman, Roland McGrath |
| @page |
| @vskip 0pt plus 1filll |
| Copyright @copyright{} 1988 Free Software Foundation, Inc. |
| |
| Permission is granted to make and distribute verbatim copies of |
| this manual provided the copyright notice and this permission notice |
| are preserved on all copies. |
| |
| Permission is granted to copy and distribute modified versions of this |
| manual under the conditions for verbatim copying, provided that the entire |
| resulting derived work is distributed under the terms of a permission |
| notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this manual |
| into another language, under the above conditions for modified versions. |
| @end titlepage |
| @page |
| |
| @node Top, Bugs,, (DIR) |
| @chapter Overview of @code{make} |
| |
| The purpose of the @code{make} utility is to determine automatically which |
| pieces of a large program need to be recompiled, and issue the commands to |
| recompile them. This manual describes the GNU implementation of |
| @code{make}, which was implemented by Richard Stallman and Roland McGrath. |
| |
| Our examples show C programs, since they are most common, but you can use |
| @code{make} with any programming language whose compiler can be run with a |
| shell command. In fact, @code{make} is not limited to programs. You can |
| use it to describe any task where some files must be updated automatically |
| from others whenever the others change. |
| |
| To prepare to use @code{make}, you must write a file called |
| the @dfn{makefile} that describes the relationships among files |
| in your program, and the states the commands for updating each file. |
| In a program, typically the executable file is updated from object |
| files, which are in turn made by compiling source files.@refill |
| |
| Once a suitable makefile exists, each time you change some source files, |
| this simple shell command: |
| |
| @example |
| make |
| @end example |
| |
| @noindent |
| suffices to perform all necessary recompilations. The @code{make} program |
| uses the makefile data base and the last-modification times of the files to |
| decide which of the files need to be updated. For each of those files, it |
| issues the commands recorded in the data base. |
| |
| @iftex |
| Command arguments to @code{make} can be used to control which files should |
| be recompiled, or how. @xref{Running}. |
| @end iftex |
| |
| @menu |
| * Bugs:: If you have problems, or think you've found a bug. |
| * Simple:: A simple example explained. |
| * Makefiles:: The data base contains rules and variable definitions. |
| * Rules:: A rule says how and when to remake one file. |
| * Commands:: A rule contains shell commands that say how to remake. |
| * Variables:: A variable holds a text string for substitution into rules. |
| * Conditionals::Makefiles that do one thing or another depending on |
| variable values. |
| * Functions:: Functions can do text-processing within @code{make}. |
| |
| * Running:: How to run @code{make}; how you can adjust the way |
| @code{make} uses the makefile. |
| |
| * Implicit:: Implicit rules take over if the makefile doesn't say |
| how a file is to be remade. |
| * Archives:: How to use @code{make} to update archive files. |
| |
| * Features:: GNU @code{make}'s advanced features and how GNU @code{make} |
| relates to other versions of @code{make}. |
| * Missing:: Features of other @code{make}s not supported |
| by GNU @code{make}. |
| |
| * Concept Index::Index of cross-references to where concepts are discussed. |
| * Name Index:: Index of cross-references for names of @code{make}'s |
| variables, functions, special targets and directives. |
| @end menu |
| |
| @node Bugs, Simple, Top, Top |
| @section Problems and Bugs |
| |
| If you have problems with GNU @code{make} or think you've found a bug, |
| please report it to Roland McGrath; he doesn't promise to do anything |
| but he might well want to fix it. |
| |
| Before reporting a bug, make sure you've actually found a real bug. |
| Carefully re-read the documentation and see if it really says you can do |
| what you're trying to do. If it's not clear whether you should be able |
| to do something or not, report that too; it's a bug in the documentation! |
| |
| Before reporting a bug or trying to fix it yourself, try to isolate it to |
| the smallest possible makefile that reproduces the problem. Then send |
| us the makefile and the exact results @code{make} gave you. Also say what |
| you expected to occur; this will help us decide whether the problem |
| was really in the documentation. |
| |
| Once you've got a precise problem, send email to (Internet) |
| @samp{bug-gnu-utils@@prep.ai.mit.edu} or (UUCP) |
| @samp{mit-eddie!prep.ai.mit.edu!bug-gnu-utils}. Please include the version |
| number of @code{make} you are using. You can get this information with the |
| command @samp{make -v -f /dev/null}.@refill |
| |
| Non-bug suggestions are always welcome as well. |
| If you have questions about things that are unclear in the documentation |
| or are just obscure features, ask Roland McGrath; he'll be happy to help |
| you out (but no promises). You can send him electronic mail at Internet |
| address @samp{roland@@wheaties.ai.mit.edu} or UUCP path |
| @samp{mit-eddie!wheaties.ai.mit.edu!roland}. |
| |
| @node Simple, Makefiles, Bugs, Top |
| @section Simple Example of @code{make} |
| |
| Suppose we have a text editor consisting of eight C source files and three |
| header files. We need a makefile to tell @code{make} how to compile and |
| link the editor. Assume that all the C files include @file{defs.h}, but |
| only those defining editing commands include @file{commands.h} and only low |
| level files that change the editor buffer include @file{buffer.h}. |
| |
| To recompile the editor, each changed C source file must be recompiled. If |
| a header file has changed, to be safe each C source file that |
| includes the header file must be recompiled. Each compilation produces an |
| object file corresponding to the source file. Finally, if any source file |
| has been recompiled, all the object files, whether newly made or saved from |
| previous compilations, must be linked together to produce the new |
| executable editor. |
| |
| Here is a straightforward makefile that describes these criteria and says |
| how to compile and link when the time comes: |
| |
| @example |
| edit : main.o kbd.o commands.o display.o \ |
| insert.o search.o files.o utils.o |
| cc -o edit main.o kbd.o commands.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 |
| commands.o : command.c defs.h command.h |
| cc -c commands.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 |
| @end example |
| |
| We split each long line into two lines using a backslash-newline; this is |
| like using one long line, but is easier to read. |
| |
| Each file that is generated by a program---that is to say, each file except |
| for source files---is the @dfn{target} of a @dfn{rule} (@pxref{Rules}). |
| (In this example, these are the object files such as @file{main.o}, |
| @file{kbd.o}, etc., and the executable file @file{edit}.) The target |
| appears at the beginning of a line, followed by a colon. |
| |
| After the colon come the target's @dfn{dependencies}: all the files that |
| are used as input when the target file is updated. A target file needs to |
| be recompiled or relinked if any of its dependencies changes. In addition, |
| any dependencies that are themselves automatically generated should be |
| updated first. In this example, @file{edit} depends on each of the eight |
| object files; the object file @file{main.o} depends on the source file |
| @file{main.c} and on the header file @file{defs.h}. |
| |
| By default, @code{make} starts with the first rule (not counting rules |
| whose target names start with @samp{.}). This is called the @dfn{default |
| goal}. Therefore, we put the rule for the executable program @file{edit} |
| first. The other rules are processed because their targets appear as |
| dependencies of the goal. |
| |
| After each line containing a target and dependencies come one or more lines |
| of shell commands that say how to update the target file. These lines |
| start with a tab to tell @code{make} that they are command lines. But |
| @code{make} does not know anything about how the commands work. It is up |
| to you to supply commands that will update the target file properly. |
| All @code{make} does is execute the commands you have specified when the |
| target file needs to be updated. |
| |
| @subsection How @code{make} Processes This Makefile |
| |
| After reading the makefile, @code{make} begins its real work by processing |
| the first rule, the one for relinking @file{edit}; but before it can fully |
| process this rule, it must process the rules for the files @file{edit} |
| depends on: all the object files. Each of these files is processed |
| according to its own rule. These rules say to update the @samp{.o} file by |
| compiling its source file. The recompilation must be done if the source |
| file, or any of the header files named as dependencies, is more recent than |
| the object file, or if the object file does not exist. |
| |
| Before recompiling an object file, @code{make} considers updating its |
| dependencies, the source file and header files. This makefile does not |
| specify anything to be done for them---the @samp{.c} and @samp{.h} files |
| are not the targets of any rules---so nothing needs to be done. But |
| automatically generated C programs, such as made by Yacc (or Bison), would |
| be updated by their own rules at this time. |
| |
| After recompiling whichever object files need it, @code{make} can now |
| decide whether to relink @file{edit}. This must be done if the file |
| @file{edit} does not exist, or if any of the object files are newer than |
| it. If an object file was just recompiled, it is now newer than |
| @file{edit}, so @file{edit} will be relinked. |
| |
| @subsection Variables Make Makefiles Simpler |
| |
| In our example, we had to list all the object files twice in the rule for |
| @file{edit} (repeated here): |
| |
| @example |
| edit : main.o kbd.o commands.o display.o \ |
| insert.o search.o files.o utils.o |
| cc -o edit main.o kbd.o commands.o display.o \ |
| insert.o search.o files.o utils.o |
| @end example |
| |
| @vindex objects |
| Such duplication is error-prone; if a new object file is added to the |
| system, we might add it to one list and forget the other. We can eliminate |
| the risk and simplify the makefile by using a @dfn{variable}. Variables |
| allow a text string to be defined once and substituted in multiple places |
| later (@pxref{Variables}). |
| |
| It's standard practice for every makefile to have a variable named |
| @code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj} or |
| @code{OBJ} which is a list of all object file names. We would define |
| such a variable @code{objects} with a line like this in the makefile:@refill |
| |
| @example |
| objects = main.o kbd.o commands.o display.o \ |
| insert.o search.o files.o utils.o |
| @end example |
| |
| @noindent |
| Then, each place we want to put a list of the object file names, we can |
| substitute the variable's value by writing @samp{$(objects)} |
| (@pxref{Variables}). Here is how the rule for @code{edit} looks as a |
| result: |
| |
| @example |
| edit : $(objects) |
| cc -o edit $(objects) |
| @end example |
| |
| @subsection Letting @code{make} Deduce the Commands |
| |
| It is not necessary to spell out the commands for compiling the individual |
| C source files, because @code{make} can figure them out: it has an |
| @dfn{implicit rule} for updating a @samp{.o} file from a correspondingly |
| named @samp{.c} file using a @samp{cc -c} command. For example, it will |
| use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into |
| @file{main.o}. We can therefore omit the commands from the rules for the |
| object files. @xref{Implicit}.@refill |
| |
| When a @samp{.c} file is used automatically in this way, it is also |
| automatically added to the list of dependencies. We can therefore omit |
| the @samp{.c} files from the dependencies, provided we omit the commands. |
| |
| Here is the entire example, with both of these changes, and a variable |
| @code{objects} as suggested above: |
| |
| @example |
| objects = main.o kbd.o commands.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 |
| commands.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 |
| @end example |
| |
| @noindent |
| This is how we would write the makefile in actual practice. |
| |
| @subsection Another Style of Makefile |
| |
| Since the rules for the object files specify only dependencies, no |
| commands, one can alternatively combine them by dependency instead of by |
| target. Here is what it looks like: |
| |
| @example |
| objects = main.o kbd.o commands.o display.o \ |
| insert.o search.o files.o utils.o |
| |
| edit : $(objects) |
| cc -o edit $(objects) |
| |
| $(objects) : defs.h |
| kbd.o commands.o files.o : command.h |
| display.o insert.o search.o files.o : buffer.h |
| @end example |
| |
| @noindent |
| Here @file{defs.h} is given as a dependency of all the object files; |
| @file{commands.h} and @file{buffer.h} are dependencies of the specific |
| object files listed for them. |
| |
| Whether this is better is a matter of taste: it is more compact, but some |
| people dislike it because they find it clearer to put all the information |
| about each target in one place. |
| |
| @node Makefiles, Rules, Simple, Top |
| @chapter Writing Makefiles |
| |
| @cindex makefile |
| The information that tells @code{make} how to recompile a system comes from |
| reading a data base called the @dfn{makefile}. |
| |
| @menu |
| * Contents: Makefile Contents. Overview of what you put in a makefile. |
| * Names: Makefile Names. Where @code{make} finds the makefile. |
| * MAKEFILES Variable:: The environment can specify extra makefiles. |
| * Include:: How one makefile can use another makefile. |
| @end menu |
| |
| @node Makefile Contents, Makefile Names, Makefiles, Makefiles |
| @section What Makefiles Contain |
| |
| Makefiles contain four kinds of things: @dfn{rules}, @dfn{variable |
| definitions}, @dfn{directives} and @dfn{comments}. Rules, variables and |
| directives are described at length in later chapters.@refill |
| |
| @itemize @bullet |
| @item |
| A rule says when and how to remake one or more files, called the rule's |
| @dfn{targets}. It lists the other files that the targets @dfn{depend on}, |
| and may also give commands to use to create or update the targets. |
| @xref{Rules}. |
| |
| @item |
| A variable definition is a line that specifies a text string value for |
| a @dfn{variable} that can be substituted into the text later. The |
| simple makefile example (@pxref{Simple}) shows a variable definition |
| for @code{objects} as a list of all object files. @xref{Variables}, |
| for full details. |
| |
| @item |
| A directive is a command for @code{make} to do something special while |
| reading the makefile. These include: |
| |
| @itemize @bullet |
| @item |
| Reading another makefile (@pxref{Include}). |
| |
| @item |
| Deciding (based on the values of variables) whether to use or |
| ignore a part of the makefile (@pxref{Conditionals}). |
| |
| @item |
| Defining a variable from a verbatim string containing multiple lines |
| (@pxref{Defining}). |
| @end itemize |
| |
| @item |
| @cindex comments |
| @samp{#} in a line of a makefile starts a comment. It and the rest of |
| the line are ignored. Comments may appear on any of the lines in the |
| makefile, except within a @code{define} directive, and perhaps within |
| commands (where the shell decides what is a comment). A line |
| containing just a comment (with perhaps spaces before it) is |
| effectively blank, and is ignored. |
| @end itemize |
| |
| @node Makefile Names, MAKEFILES Variable, Makefile Contents, Makefiles |
| @section What Name to Give Your Makefile |
| |
| By default, when @code{make} looks for the makefile, it tries the names |
| @file{./makefile} and @file{./Makefile} in that order. So normally you call |
| your makefile by one of these two names, and @code{make} finds it |
| automatically. We recommend @file{Makefile} because it appears prominently |
| near the beginning of a directory listing (right near other important |
| files such as @file{README}).@refill |
| |
| If @code{make} finds neither of these two names, it does not use any |
| makefile. Then you must specify a goal with a command argument, and |
| @code{make} will attempt to figure out how to remake it using only its |
| built-in implicit rules. @xref{Implicit}. |
| |
| If you want to use a nonstandard name for your makefile, you can specify |
| the makefile name with the @samp{-f} option. The arguments @samp{-f |
| @var{name}} tell @code{make} to read the file @var{name} as the makefile. |
| If you use more than one @samp{-f} option, you can specify several |
| makefiles. All the makefiles are effectively concatenated in the order |
| specified. The default makefile names @file{./makefile} and |
| @file{./Makefile} are not used if you specify @samp{-f}.@refill |
| |
| @node MAKEFILES Variable, Include, Makefile Names, Makefiles |
| @section The Variable @code{MAKEFILES} |
| |
| @vindex MAKEFILES |
| If the environment variable @code{MAKEFILES} is defined, @code{make} |
| considers its value as a list of names (separated by whitespace) of |
| additional makefiles to be read before the others. This works much like |
| the @code{include} directive: various directories are searched for those |
| files and the default goal is never taken from them. @xref{Include}. In |
| addition, it is not an error if the files listed in @code{MAKEFILES} are |
| not found.@refill |
| |
| The main use of @code{MAKEFILES} is in communication between recursive |
| invocations of @code{make} (@pxref{Recursion}). It usually isn't |
| desirable to set the environment variable before a top-level invocation |
| of @code{make}, because it is usually better not to mess with a makefile |
| from outside. However, if you are running @code{make} without a specific |
| makefile, a makefile in @code{MAKEFILES} can do useful things to help the |
| built-in implicit rules work better, such as defining search paths. |
| |
| Some users are tempted to set @code{MAKEFILES} in the environment |
| automatically on login, and program makefiles to expect this to be done. |
| This is a very bad idea, because such makefiles will fail to work if run by |
| anyone else. It is much better to write explicit @code{include} directives |
| in the makefiles. |
| |
| @node Include,, MAKEFILES Variable, Makefiles |
| @section Including Other Makefiles |
| |
| @findex include |
| The @code{include} directive tells @code{make} to suspend reading the |
| current makefile and read another makefile before continuing. The |
| directive is a line in the makefile that looks like this: |
| |
| @example |
| include @var{filename} |
| @end example |
| |
| Extra spaces are allowed and ignored at the beginning of the line, but a |
| tab is not allowed. (If the line begins with a tab, it will be considered |
| a command line.) Whitespace is required between @code{include} and |
| @var{filename}; extra whitespace is ignored there and at the end of the |
| directive. A comment starting with @samp{#} is allowed at the end of the |
| line. |
| |
| Reading of the containing makefile is temporarily suspended while the file |
| @var{filename} is read as a makefile. When that is finished, @code{make} |
| goes on with reading the makefile in which the directive appears. |
| |
| The default goal target is never taken from an included makefile |
| (@pxref{Goals}). |
| |
| One occasion for using @code{include} directives is when several programs, |
| handled by individual makefiles in various directories, need to use a |
| common set of variable definitions (@pxref{Setting}) or pattern rules |
| (@pxref{Pattern Rules}). |
| |
| Another such occasion is when you want to automatically generate |
| dependencies from source files; the dependencies can be put in a file that |
| is included by the main makefile. This practice is generally cleaner than |
| that of somehow appending the dependencies to the end of the main makefile |
| as has been traditionally done with other versions of @code{make}. |
| |
| If the specified name does not start with a slash, and the file is not |
| found in the current directory, several other directories are searched. |
| First, any directories you have specified with the @samp{-I} option are |
| searched (@pxref{Options}). Then the following directories (if they |
| exist) are searched, in this order: @file{/usr/gnu/include}, |
| @file{/usr/local/include}, @file{/usr/include}. |
| If an included makefile cannot be found in any of these directories, a |
| warning message is generated, but it is not a fatal error.@refill |
| |
| @node Rules, Commands, Makefiles, Top |
| @chapter Writing Rules |
| |
| @cindex rule |
| @cindex target |
| @cindex dependency |
| A @dfn{rule} appears in the makefile and says when and how to remake |
| certain files, called the rule's @dfn{targets} (usually only one per rule). |
| It lists the other files that are the @dfn{dependencies} of the target, and |
| @dfn{commands} to use to create or update the target. |
| |
| The order of rules is not significant, except for determining the |
| @dfn{default goal}: the target for @code{make} to consider, if you do not |
| otherwise specify one. The default goal comes from the first rule (not |
| counting included makefiles) whose target does not start with a period. |
| Therefore, the first rule is normally one for compiling the entire program |
| or all the programs described by the makefile. @xref{Goals}. |
| |
| @menu |
| * Rule Example:: An explained example of a rule. |
| * Rule Syntax:: General syntax of rules, with explanation. |
| |
| * Wildcards:: Using wildcard characters like `*' in file names. |
| * Directory Search:: Searching other directories for source files. |
| |
| * Phony Targets:: Using a target that isn't a real file's name. |
| * Special Targets:: Targets with special built-in meanings. |
| * Empty Targets:: Real files that are empty--only the date matters. |
| * Multiple Targets:: When it is useful to have several targets in a rule. |
| * Static Pattern:: Static pattern rules apply to multiple targets |
| and can vary the dependencies according to the |
| target name. |
| * Multiple Rules:: Using several rules with the same target. |
| * Double-Colon:: Special kind of rule allowing |
| several independent rules for one target. |
| * Commands:: Special features and details of how commands |
| in a rule are executed. |
| @end menu |
| |
| @ifinfo |
| @node Rule Example, Rule Syntax, Rules, Rules |
| @isubsection Rule Example |
| |
| Here is an example of a rule: |
| |
| @example |
| foo.o : foo.c defs.h # module for twiddling the frobs |
| cc -c -g foo.c |
| @end example |
| |
| Its target is @file{foo.o} and its dependencies are @file{foo.c} and |
| @file{defs.h}. It has one command, which is @samp{cc -c -g foo.c}. |
| The command line starts with a tab to identify it as a command. |
| |
| This rule says two things: |
| |
| @itemize @bullet |
| @item |
| How to decide whether @file{foo.o} is out of date: it is out of date |
| if it does not exist, or if either @file{foo.c} or @file{defs.h} is |
| more recent than it. |
| |
| @item |
| How to update the file @file{foo.o}: by running @code{cc} as stated. |
| The command does not explicitly mention @file{defs.h}, but we presume |
| that @file{foo.c} includes it, and that that is why @file{defs.h} was |
| added to the dependencies. |
| @end itemize |
| @end ifinfo |
| |
| @node Rule Syntax, Wildcards, Rule Example, Rules |
| @section Rule Syntax |
| |
| In general, a rule looks like this: |
| |
| @example |
| @var{targets} : @var{dependencies} |
| @var{command} |
| @var{command} |
| ... |
| @end example |
| |
| @noindent |
| or like this: |
| |
| @example |
| @var{targets} : @var{dependencies} ; @var{command} |
| @var{command} |
| @var{command} |
| ... |
| @end example |
| |
| The @var{targets} are file names, separated by spaces. Wild card |
| characters may be used (@pxref{Wildcards}) and a name of the form |
| @file{@var{a}(@var{m})} represents member @var{m} in archive file @var{a} |
| (@pxref{Archive Members}). Usually there is only one target per rule, but |
| occasionally there is a reason to have more (@pxref{Multiple Targets}). |
| |
| The @var{command} lines start with a tab character. The first command may |
| appear on the line after the dependencies, with a tab character, or may |
| appear on the same line, with a semicolon. Either way, the effect is the |
| same. @xref{Commands}. |
| |
| Because dollar signs are used to start variable references, if you really |
| want a dollar sign in the rule you must write two of them (@samp{$$}). |
| @xref{Variables}. A long line may be split by inserting a backslash |
| followed by a newline, but this is not required, as there is no limit on |
| the length of a line. |
| |
| A rule tells @code{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 the |
| @var{dependencies}, which consist of file names separated by spaces. |
| (Wildcards and archive members are allowed here too.) A target is out of |
| date if it does not exist or if it is older than any of the dependencies |
| (by comparison of last-modification times). The idea is that the contents |
| of the target file are computed based on information in the dependencies, |
| so if any of the dependencies changes, the contents of the existing target |
| file are no longer necessarily valid. |
| |
| How to update is specified by @var{commands}. These are lines to be |
| executed by the shell (normally @samp{sh}), but with some extra features |
| (@pxref{Commands}). |
| |
| @node Wildcards, Directory Search, Rule Syntax, Rules |
| @section Using Wildcards Characters in File Names |
| @cindex wildcard |
| @cindex file name |
| |
| A single file name can specify many files using @dfn{wildcard characters}. |
| The wildcard characters in @code{make} are @samp{*}, @samp{?} and |
| @samp{[@dots{}]}, the same as in the Bourne shell. For example, @file{*.c} |
| specifies a list of all the files (in the working directory) whose names |
| end in @samp{.c}.@refill |
| |
| Wildcard expansion happens automatically in targets, in dependencies, and |
| in commands. In other contexts, wildcard expansion happens only if you |
| request it explicitly with the @code{wildcard} function. |
| |
| The special significance of a wildcard character can be turned off by |
| preceding it with a backslash. Thus, @file{foo\*bar} would refer to a |
| specific file whose name consists of @samp{foo}, an asterisk, and |
| @samp{bar}.@refill |
| |
| @menu |
| * Examples: Wildcard Examples. Some simple examples. |
| * Pitfall: Wildcard Pitfall. @code{*.o} won't do what you want! |
| * Function: Wildcard Function. |
| How to do wildcard expansion when defining a variable |
| using the function @code{wildcard}. |
| @end menu |
| |
| @node Wildcard Examples, Wildcard Function, Wildcards, Wildcards |
| @subsection Wildcard Examples |
| |
| Wildcards can be used in the commands of a rule. For example, here is a |
| rule to delete all the object files: |
| |
| @example |
| clean: |
| rm -f *.o |
| @end example |
| |
| Wildcards are also useful in the dependencies of a rule. With the |
| following rule in the makefile, @samp{make print} will print all the |
| @samp{.c} files that have changed since the last time you printed them: |
| |
| @example |
| print: *.c |
| lpr -p $? |
| touch print |
| @end example |
| |
| @noindent |
| This rule uses @file{print} as an empty target file; @pxref{Empty Targets}. |
| |
| Wildcard expansion does not happen when you define a variable. Thus, if |
| you write this: |
| |
| @example |
| objects=*.o |
| @end example |
| |
| @noindent |
| then the value of the variable @code{objects} is the actual string |
| @samp{*.o}. However, if you use the value of @code{objects} in a target, |
| dependency or command, wildcard expansion will take place at that time. |
| |
| @node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards |
| @subsection Pitfalls of Using Wildcards |
| |
| Now here is an example of a naive way of using wildcard expansion, that |
| does not do what you would intend. Suppose you would like to say that the |
| executable file @file{foo} is made from all the object files in the |
| directory, and you write this: |
| |
| @example |
| objects=*.o |
| |
| foo : $(objects) |
| cc -o foo $(CFLAGS) $(objects) |
| @end example |
| |
| @noindent |
| The value of @code{objects} is the actual string @samp{*.o}. Wildcard |
| expansion happens in the rule for @file{foo}, so that each @emph{existing} |
| @samp{.o} file becomes a dependency of @file{foo} and will be recompiled if |
| necessary. |
| |
| But what if you delete all the @samp{.o} files? Then @samp{*.o} will |
| expand into @emph{nothing}. The target @file{foo} will have no |
| dependencies and would be remade by linking no object files. This is not |
| what you want! |
| |
| Actually you can use wildcard expansion for this purpose, but you need more |
| sophisticated techniques, including the @code{wildcard} function and string |
| substitution. |
| @ifinfo |
| @xref{Wildcard Function}. |
| @end ifinfo |
| @iftex |
| These are described in the following section. |
| @end iftex |
| |
| @node Wildcard Function,, Wildcard Pitfall, Wildcards |
| @subsection The Function @code{wildcard} |
| @findex wildcard |
| |
| Wildcard expansion happens automatically in rules. But wildcard expansion |
| does not normally take place when a variable is set, or inside the |
| arguments of a function. If you want to do wildcard expansion in such |
| places, you need to use the @code{wildcard} function, like this: |
| |
| @example |
| $(wildcard @var{pattern}) |
| @end example |
| |
| This string, used anywhere in a makefile, is replaced by a space-separated |
| list of names of existing files that match the pattern @var{pattern}. |
| |
| One use of the @code{wildcard} function is to get a list of all the C source |
| files in a directory, like this: |
| |
| @example |
| $(wildcard *.c) |
| @end example |
| |
| We can change the list of C source files into a list of object files by |
| substituting @samp{.o} for @samp{.c} in the result, like this: |
| |
| @example |
| $(subst .c,.o,$(wildcard *.c)) |
| @end example |
| |
| Here we have used another function, @code{subst} (@pxref{Text Functions}). |
| |
| Thus, a makefile to compile all C source files in the directory and then |
| link them together could be written as follows: |
| |
| @example |
| objects:=$(subst .c,.o,$(wildcard *.c)) |
| |
| foo : $(objects) |
| cc -o foo $(LDFLAGS) $(objects) |
| @end example |
| |
| @noindent |
| (This takes advantage of the implicit rule for compiling C programs, so |
| there is no need to write explicit rules for compiling the files.) |
| |
| @node Directory Search, Phony Targets, Wildcards, Rules |
| @section Searching Directories for Dependencies |
| @vindex VPATH |
| @findex vpath |
| @cindex vpath |
| @cindex search path for dependencies |
| @cindex directory search |
| |
| For large systems, it is often desirable to put sources in a separate |
| directory from the binaries. The @dfn{directory search} features of |
| @code{make} facilitate this by searching several directories automatically |
| to find a dependency. When you redistribute the files among directories, |
| you do not need to change the individual rules, just the search paths. |
| |
| @menu |
| * General Search:: The @code{VPATH} variable specifies a search path |
| that applies to every dependency. |
| * Selective Search:: The @code{vpath} directive specifies a search path |
| for a specified class of names. |
| * Commands/Search:: How to write shell commands that work together |
| with search paths. |
| * Implicit/Search:: How search paths affect implicit rules. |
| * Libraries/Search:: Directory search for link libraries. |
| @end menu |
| |
| @node General Search, Selective Search, Directory Search, Directory Search |
| @subsection @code{VPATH}: Search Path for All Dependencies |
| |
| The value of the variable @code{VPATH} is a list of directories which |
| @code{make} should search (in the order specified) for dependency files. |
| The directory names are separated by colons. For example: |
| |
| @example |
| VPATH = src:../headers |
| @end example |
| |
| @noindent |
| specifies a path containing two directories, @file{src} and @file{../headers}. |
| |
| Whenever a file listed as a dependency does not exist in the current |
| directory, the directories listed in @code{VPATH} are searched for a file |
| with that name. If a file is found in one of them, that file becomes the |
| dependency. Rules may then specify the names of source files as if they |
| all existed in the current directory. |
| |
| Using the value of @code{VPATH} set in the previous example, a rule like this: |
| |
| @example |
| foo.o : foo.c |
| @end example |
| |
| @noindent |
| is interpreted as if it were written like this: |
| |
| @example |
| foo.o : src/foo.c |
| @end example |
| |
| @noindent |
| assuming the file @file{foo.c} does not exist in the current directory but |
| is found in the directory @file{src}. |
| |
| @node Selective Search, Commands/Search, General Search, Directory Search |
| @subsection The @code{vpath} Directive |
| |
| Similar to the @code{VPATH} variable but more selective is the @code{vpath} |
| directive, which allows you to specify a search path for a particular class |
| of filenames, those that match a particular pattern. Thus you can supply |
| certain search directories for one class of filenames and other directories |
| (or none) for other filenames. |
| |
| There are three forms of the @code{vpath} directive: |
| |
| @table @code |
| @item vpath @var{pattern} @var{directories} |
| Specify the search path @var{directories} for filenames that match |
| @code{pattern}. If another path was previously specified for the same |
| pattern, the new path replaces it. Note that it does @emph{not} add |
| to the old path for this pattern.@refill |
| |
| The search path, @var{directories}, is a colon-separated list of |
| directories to be searched, just like the search path used in the |
| @code{VPATH} variable. |
| |
| @item vpath @var{pattern} |
| Clear out the search path associated with @var{pattern}. |
| |
| @item vpath |
| Clear all search paths previously specified with @code{vpath} directives. |
| @end table |
| |
| A @code{vpath} pattern is a string containing a @samp{%} character. The |
| string must match the filename of a dependency that is being searched for, |
| the @samp{%} character matching any sequence of zero or more characters (as |
| in pattern rules; @pxref{Pattern Rules}). (It is valid to omit the |
| @samp{%}, but then the pattern must match the dependency exactly, which may |
| not be very useful.) |
| |
| When a dependency fails to exist in the current directory, if the |
| @var{pattern} in a @code{vpath} directive matches the name of the |
| dependency file, then the @var{directories} in that directive are searched |
| just like (and before) the directories in the @code{VPATH} variable.@refill |
| |
| If several @code{vpath} patterns match the dependency file's name, then |
| @code{make} processes each matching @code{vpath} directive one by one, |
| searching all the directories mentioned in each directive. The @code{vpath} |
| directives are processed in the order in which they appear in the makefiles. |
| |
| @node Commands/Search, Implicit/Search, Selective Search, Directory Search |
| @subsection Writing Shell-Commands with Directory Search |
| |
| When a dependency is found in another directory through directory search, |
| this cannot change the commands of the rule; they will execute as written. |
| Therefore, you must write the commands with care so that they will look for |
| the dependency in the directory where @code{make} finds it. |
| |
| This is done with the @dfn{automatic variables} such as @samp{$^} |
| (@pxref{Automatic}). For instance, the value of @samp{$^} is a list of all |
| the dependencies of the rule, including the names of the directories in |
| which they were found, and the value of @samp{$@@} is the target. Thus: |
| |
| @example |
| foo.o : foo.c |
| cc -c $(CFLAGS) $^ -o $@@ |
| @end example |
| |
| @noindent |
| The variable @code{CFLAGS} exists so you can specify flags for C |
| compilation by implicit rule; we use it here for consistency so it will |
| affect all C compilations uniformly (@pxref{Implicit Variables}). |
| |
| Often the dependencies include header files as well, which you don't want |
| to mention in the commands. The function @code{firstword} can be used to |
| extract just the first dependency from the entire list, as shown here |
| (@pxref{Filename Functions}): |
| |
| @example |
| VPATH = src:../headers |
| foo.o : foo.c defs.h hack.h |
| cc -c $(CFLAGS) $(firstword $^) -o $@@ |
| @end example |
| |
| @noindent |
| Here the value of @samp{$^} would be something like @samp{src/foo.c |
| ../headers/defs.h hack.h}, from which @samp{$(firstword $^)} extracts just |
| @samp{src/foo.c}.@refill |
| |
| @node Implicit/Search, Libraries/Search, Commands/Search, Directory Search |
| @subsection Directory Search and Implicit Rules |
| |
| The search through the directories specified in @code{VPATH} or with |
| @code{vpath} happens also during consideration of implicit rules |
| (@pxref{Implicit}). |
| |
| For example, when a file @file{foo.o} has no explicit rule, @code{make} |
| considers implicit rules, such as to compile @file{foo.c} if that file |
| exists. If such a file is lacking in the current directory, the |
| appropriate directories are searched for it. If @file{foo.c} exists (or is |
| mentioned in the makefile) in any of the directories, the implicit rule for |
| C compilation is applicable. |
| |
| The commands of all the built-in implicit rules normally use automatic |
| variables as a matter of necessity; consequently they will use the file |
| names found by directory search with no extra effort. |
| |
| @node Libraries/Search,, Implicit/Search, Directory Search |
| @subsection Directory Search for Link Libraries |
| |
| Directory search applies in a special way to libraries used with the |
| linker. This special feature comes into play when you write a dependency |
| whose name is of the form @samp{-l@var{name}}. (You can tell something |
| funny is going on here because the dependency is normally the name of a |
| file, and the @emph{file name} of the library looks like |
| @file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill |
| |
| When a dependency's name has the form @samp{-l@var{name}}, @code{make} |
| handles it specially by searching for the file @samp{lib@var{name}.a} in |
| the directories @samp{/lib} and @samp{/usr/lib}, and then using matching |
| @code{vpath} search paths and the @code{VPATH} search path.@refill |
| |
| For example, |
| |
| @example |
| foo : foo.c -lcurses |
| cc $^ -o $@@ |
| @end example |
| |
| @noindent |
| would cause the command @samp{cc foo.c -lcurses -o foo} to be executed when |
| @file{foo} is older than @file{foo.c} or than @file{libcurses.a} (which has |
| probably been found by directory search in the file |
| @file{/usr/lib/libcurses.a}).@refill |
| |
| As shown by the example above, the file name found by directory search is |
| used only for comparing the file time with the target file's time. It |
| does not replace the file's name in later usage (such as in automatic |
| variables like @code{$^}); the name remains unchanged, still starting |
| with @samp{-l}. This leads to the correct results because the linker |
| will repeat the appropriate search when it processes its arguments.@refill |
| |
| @node Phony Targets, Empty Targets, Directory Search, Rules |
| @section Phony Targets |
| @cindex phony targets |
| |
| A phony target is one that is not really the name of a file. |
| It is only a name for some commands to be executed when explicitly |
| requested. |
| |
| If you write a rule whose commands will not create the target file, the |
| commands will be executed every time the target comes up for remaking. |
| Here is an example: |
| |
| @example |
| clean: |
| rm *.o temp |
| @end example |
| |
| @noindent |
| Because the @code{rm} command does not create a file named @file{clean}, |
| probably no such file will ever exist. Therefore, the @code{rm} command |
| will be executed every time you say @samp{make clean}. |
| |
| @findex .PHONY |
| The phony target will cease to work if anything ever does create a file |
| named @file{clean} in this directory. Since there are no dependencies, the |
| @file{clean} would be considered up to date and its commands would not be |
| executed. To avoid this problem, you can explicitly declare the target to |
| be phony, using the special target @code{.PHONY} (@pxref{Special Targets}) |
| as follows: |
| |
| @example |
| .PHONY : clean |
| @end example |
| |
| @noindent |
| Once this is done, @code{make} will run the commands regardless of whether |
| there is a file named @file{clean}. |
| |
| A phony target should not be a dependency of a real target file; strange |
| things can result from that. As long as you don't do that, the phony |
| target commands will be executed only when the phony target is a goal |
| (@pxref{Goals}). |
| |
| Phony targets can have dependencies. When one directory contains multiple |
| programs, it is most convenient to describe all of the programs in one |
| makefile @file{./Makefile}. Since the target remade by default will be the |
| first one in the makefile, it is common to make this a phony target named |
| @samp{all} and give it, as dependencies, all the individual programs. For |
| example: |
| |
| @example |
| all : prog1 prog2 prog3 |
| .PHONY : all |
| |
| prog1 : prog1.o utils.o |
| cc -o prog1 prog1.o utils.o |
| |
| prog2 : prog2.o |
| cc -o prog2 prog2.o |
| |
| prog3 : prog3.o sort.o utils.o |
| cc -o prog3 prog3.o sort.o utils.o |
| @end example |
| |
| @noindent |
| Now you can say just @samp{make} to remake all three programs, or specify |
| as arguments the ones to remake (as in @samp{make prog1 prog3}). |
| |
| When one phony target is a dependency of another, it serves as a subroutine |
| of the other. For example, here @samp{make cleanall} will delete the |
| object files, the difference files, and the file @file{program}: |
| |
| @example |
| cleanall : cleanobj cleandiff |
| rm program |
| |
| cleanobj : |
| rm *.o |
| |
| cleandiff : |
| rm *.diff |
| @end example |
| |
| @node Empty Targets, Special Targets, Phony Targets, Rules |
| @section Empty Target Files to Record Events |
| @cindex empty targets |
| |
| The @dfn{empty target} is a variant of the phony target; it is used to hold |
| commands for an action that you request explicitly from time to time. |
| Unlike a phony target, this target file can really exist; but the file's |
| contents do not matter, and usually are empty. |
| |
| The purpose of the empty target file is to record, with its |
| last-modification-time, when the rule's commands were last executed. It |
| does so because one of the commands is a @code{touch} command to update the |
| target file. |
| |
| The empty target file must have some dependencies. When you ask to remake |
| the empty target, the commands are executed if any dependency is more |
| recent than the target; in other words, if a dependency has changed since |
| the last time you remade the target. Here is an example: |
| |
| @example |
| print: foo.c bar.c |
| lpr -p $? |
| touch print |
| @end example |
| |
| @noindent |
| With this rule, @samp{make print} will execute the @code{lpr} command if |
| either source file has changed since the last @samp{make print}. The |
| automatic variable @samp{$?} is used to print only those files that have |
| changed (@pxref{Automatic}). |
| |
| @node Special Targets, Multiple Targets, Empty Targets, Rules |
| @section Special Built-in Target Names |
| @cindex special targets |
| |
| Certain names have special meanings if they appear as targets. |
| |
| @table @code |
| @item .PHONY |
| The dependencies of the special target @code{.PHONY} are considered to |
| be phony targets. When it is time to consider such a target, |
| @code{make} will run its commands unconditionally, regardless of |
| whether a file with that name exists or what its last-modification |
| time is. @xref{Phony Targets}. |
| |
| @item .SUFFIXES |
| The dependencies of the special target @code{.SUFFIXES} are the list |
| of suffixes to be used in checking for suffix rules (@pxref{Suffix |
| Rules}). |
| |
| @item .DEFAULT |
| The commands specified for @code{.DEFAULT} are used for any target for |
| which no other commands are known (either explicitly or through an |
| implicit rule). If @code{.DEFAULT} commands are specified, every |
| nonexistent file mentioned as a dependency will have these commands |
| executed on its behalf. @xref{Search Algorithm}. |
| |
| @item .PRECIOUS |
| @cindex precious targets |
| The targets which @code{.PRECIOUS} depends on are given this special |
| treatment: if @code{make} is killed or interrupted during the |
| execution of their commands, the target is not deleted. |
| @xref{Interrupts}. |
| |
| @item .IGNORE |
| Simply by being mentioned as a target, @code{.IGNORE} says to ignore |
| errors in execution of commands. The dependencies and commands for |
| @code{.IGNORE} are not meaningful. |
| |
| @samp{.IGNORE} exists for historical compatibility. Since |
| @code{.IGNORE} affects every command in the makefile, it is not very |
| useful; we recommend you use the more selective ways to ignore errors |
| in specific commands (@pxref{Errors}). |
| |
| @item .SILENT |
| Simply by being mentioned as a target, @code{.SILENT} says not to |
| print commands before executing them. The dependencies and commands |
| for @code{.SILENT} are not meaningful. |
| |
| @samp{.SILENT} exists for historical compatibility. We recommend you |
| use the more selective ways to silence specific commands |
| (@pxref{Echoing}). |
| @end table |
| |
| An entire class of special targets have names made of the concatenation of |
| two implicit rule suffixes (two members of the list of dependencies of |
| @code{.SUFFIXES}). Such special targets are suffix rules, an obsolete way |
| of defining implicit rules (but a way still widely used). In principle, |
| any target name could be special in this way if you break it in two and add |
| both pieces to the suffix list. In practice, suffixes normally begin with |
| @samp{.}, so these special target names also begin with @samp{.}. |
| @xref{Suffix Rules}. |
| |
| @node Multiple Targets, Multiple Rules, Special Targets, Rules |
| @section Multiple Targets in a Rule |
| |
| A rule with multiple targets is equivalent to writing many rules, each with |
| one target, and all identical aside from that. The same commands apply to |
| all the targets, but their effects may vary because you can substitute the |
| actual target name into the command using @samp{$@@}. The rule contributes |
| the same dependencies to all the targets also. |
| |
| This is useful in two cases. |
| |
| @itemize @bullet |
| @item |
| You want just dependencies, no commands. For example: |
| |
| @example |
| kbd.o commands.o files.o: command.h |
| @end example |
| |
| @noindent |
| gives an additional dependency to each of the three object files |
| mentioned. |
| |
| @item |
| Similar commands work for all the targets. The commands do not need |
| to be absolutely identical, since the automatic variable @samp{$@@} |
| can be used to substitute the particular target to be remade into the |
| commands (@pxref{Automatic}). For example: |
| |
| @group |
| @example |
| bigoutput littleoutput : text.g |
| generate text.g -$(subst output,,$@@) > $@@ |
| @end example |
| @end group |
| |
| @noindent |
| is equivalent to |
| |
| @example |
| bigoutput : text.g |
| generate text.g -big > bigoutput |
| littleoutput : text.g |
| generate text.g -little > littleoutput |
| @end example |
| |
| @noindent |
| Here we assume the hypothetical program @code{generate} makes two |
| types of output, one if given @samp{-big} and one if given |
| @samp{-little}.@refill |
| @end itemize |
| |
| @ifinfo |
| Suppose you would like to vary the dependencies according to the target, |
| much as the variable @samp{$@@} allows you to vary the commands. |
| You cannot do this with multiple targets in an ordinary rule, but you can |
| do it with a @dfn{static pattern rule}. @xref{Static Pattern}. |
| @end ifinfo |
| |
| @node Static Pattern, Multiple Rules, Multiple Targets, Rules |
| @section Static Pattern Rules |
| @cindex static pattern rules |
| @cindex varying dependencies |
| |
| @dfn{Static pattern rules} are rules which specify multiple targets and |
| construct the dependency names for each target based on the target name. |
| They are more general than ordinary rules with multiple targets because the |
| targets don't have to have identical dependencies. Their dependencies must |
| be @emph{analogous}, but not necessarily @emph{identical}. |
| |
| @menu |
| * Usage: Static Usage. How to use static pattern rules. |
| * Static vs Implicit:: When are they better than implicit rules? |
| @end menu |
| |
| @node Static Usage, Static vs Implicit, Static Pattern, Static Pattern |
| @subsection Syntax of Static Pattern Rules |
| |
| Here is the syntax of a static pattern rule: |
| |
| @example |
| @var{targets}: @var{target-pattern}: @var{dep-patterns} @dots{} |
| @var{commands} |
| @dots{} |
| @end example |
| |
| @noindent |
| The @var{targets} gives the list of targets that the rule applies to. The |
| targets can contain wildcard characters, just like the targets of ordinary |
| rules (@pxref{Wildcards}). |
| |
| The @var{target-pattern} and @var{dep-patterns} say how to compute the |
| dependencies of each target. Each target is matched against the |
| @var{target-pattern} to extract a part of the target name, called the |
| @dfn{stem}. This stem is substituted into each of the @var{dep-patterns} |
| to make the dependency names (one from each @var{dep-pattern}). |
| |
| Each pattern normally contains the character @samp{%} just once. When the |
| @var{target-pattern} matches a target, the @samp{%} can match any part of |
| the target name; this part is called the @dfn{stem}. The rest of the |
| pattern must match exactly. For example, the target @file{foo.o} matches |
| the pattern @samp{%.o}, with @samp{foo} as the stem. The targets |
| @file{foo.c} and @file{foo.out} don't match that pattern.@refill |
| |
| The dependency names for each target are made by substituting the stem for |
| the @samp{%} in each dependency pattern. For example, if one dependency |
| pattern is @file{%.c}, then substitution of the stem @samp{foo} gives the |
| dependency name @file{foo.c}. It is fine to write a dependency pattern that |
| doesn't contain @samp{%}; then this dependency is the same for all targets. |
| |
| Here is an example, which compiles each of @file{foo.o} and @file{bar.o} |
| from the corresponding @file{.c} file: |
| |
| @example |
| objects := foo.o bar.o |
| |
| $(objects): %.o: %.c |
| $(CC) -c $(CFLAGS) $< -o $@@ |
| @end example |
| |
| Each target specified must match the target pattern; a warning is issued |
| for each that does not. If you have a list of files, only some of which |
| will match the pattern, you can use the @code{filter} function to remove |
| nonmatching filenames (@pxref{Text Functions}): |
| |
| @example |
| files := foo.elc bar.o |
| |
| $(filter %.o,$(files)): %.o: %.c |
| $(CC) -c $(CFLAGS) $< -o $@@ |
| $(filter %.elc,$(files)): %.elc: %.el |
| emacs -f batch-byte-compile $< |
| @end example |
| |
| @noindent |
| Here the result of @samp{$(filter %.o,$(files))} is just @file{bar.o}, and |
| the first static pattern rule causes it to be made from @file{bar.c}. The |
| result of @samp{$(filter %.elc,$(files))} is @file{foo.elc}, which is |
| made from @file{foo.el}.@refill |
| |
| @node Static vs Implicit,, Static Usage, Static Pattern |
| @subsection Static Pattern Rules versus Implicit Rules |
| |
| A static pattern rule has much in common with an implicit rule defined as a |
| pattern rule (@pxref{Pattern Rules}). Both have a pattern for the target |
| and patterns for constructing the names of dependencies. The difference is |
| in how @code{make} decides @emph{when} the rule applies. |
| |
| An implicit rule @emph{can} apply to any target that matches its pattern, |
| but it @emph{does} apply only when the target has no commands otherwise |
| specified, and only when the dependencies can be found. If more than one |
| implicit rule appears applicable, only one applies; the choice depends on |
| the order of rules. |
| |
| By contrast, a static pattern rule applies to the precise list of targets |
| that you specify in the rule. It cannot apply to any other target and it |
| invariably does apply to each of the targets specified. If two conflicting |
| rules apply, and both have commands, that's an error. |
| |
| The static pattern rule can be better than an implicit rule for these |
| reasons: |
| |
| @itemize @bullet |
| @item |
| You may wish to override the usual implicit rule for a few files whose |
| names cannot be categorized syntactically but can be given in an |
| explicit list. |
| |
| @item |
| If you cannot be sure of the precise contents of the directories you |
| are using, you may not be sure which other irrelevant files might lead |
| @code{make} to use the wrong implicit rule. The choice might depend |
| on the order in which the implicit rule search is done. With static |
| pattern rules, there is no uncertainty: each rule applies to precisely |
| the targets specified. |
| @end itemize |
| |
| @node Multiple Rules, Double-Colon, Static Pattern, Rules |
| @section Multiple Rules for One Target |
| |
| One file can be the target of several rules if at most one rule has commands. |
| The other rules can only have dependencies. All the dependencies mentioned |
| in all the rules are merged into one list of dependencies for the target. |
| If the target is older than any dependency from any rule, the commands are |
| executed. |
| |
| An extra rule with just dependencies can be used to give a few extra |
| dependencies to many files at once. For example, one usually has a |
| variable named @code{objects} containing a list of all the compiler output |
| files in the system being made. An easy way to say that all of them must |
| be recompiled if @file{config.h} changes is to write |
| |
| @example |
| objects = foo.o bar.o |
| foo.o : defs.h |
| bar.o : defs.h test.h |
| $(objects) : config.h |
| @end example |
| |
| This could be inserted or taken out without changing the rules that really |
| say how to make the object files, making it a convenient form to use if |
| you wish to add the additional dependency intermittently. |
| |
| Another wrinkle is that the additional dependencies could be specified with |
| a variable that you could set with a command argument to @code{make} |
| (@pxref{Overriding}). For example, |
| |
| @example |
| extradeps= |
| $(objects) : $(extradeps) |
| @end example |
| |
| @noindent |
| means that the command @samp{make extradeps=foo.h} will consider |
| @file{foo.h} as a dependency of each object file, but plain @samp{make} |
| will not. |
| |
| If none of the explicit rules for a target has commands, then @code{make} |
| searches for an applicable implicit rule to find some commands. |
| @xref{Implicit}. |
| |
| @node Double-Colon,, Multiple Rules, Rules |
| @section Double-Colon Rules |
| @cindex double-colon rule |
| |
| @dfn{Double-colon} rules are rules written with @samp{::} instead of |
| @samp{:} after the target names. They are handled differently from |
| ordinary rules when the same target appears in more than one rule. |
| |
| When a target appears in multiple rules, all the rules must be the same |
| type: all ordinary, or all double-colon. If they are double-colon, each of |
| them is independent of the others. Each double-colon rule's commands are |
| executed if the target is older than any dependencies of that rule. This |
| can result in executing none, any or all of the double-colon rules. |
| |
| The double-colon rules for a target are executed in the order they appear |
| in the makefile. However, the cases where double-colon rules really make |
| sense are those where the order of executing the commands would not matter. |
| |
| Each double-colon rule should specify commands; if it does not, an |
| implicit rule will be used if one applies. @xref{Implicit}. |
| |
| @node Commands, Variables, Rules, Top |
| @chapter Writing the Commands in Rules |
| @cindex commands |
| |
| The commands of a rule consist of shell command lines to be executed one by |
| one. Each command line must start with a tab, except that the first |
| command line may be attached to the target-and-dependencies line with a |
| semicolon in between. Blank lines and lines of just comments may appear |
| among the command lines; they are ignored. |
| |
| Users use many different shell programs, but commands in makefiles are |
| always interpreted by @file{/bin/sh} unless the makefile specifies otherwise. |
| |
| Whether comments can be written on command lines, and what syntax they use, |
| is under the control of the shell that is in use. If it is @file{/bin/sh}, |
| a @samp{#} at the start of a word starts a comment. |
| |
| @menu |
| * Echoing:: Normally commands are echoed before execution, |
| but you can control this in several ways. |
| * Execution:: How commands are executed. |
| * Errors:: What happens after an error in command execution. |
| How to ignore errors in certain commands. |
| * Interrupts:: If a command is interrupted or killed, |
| the target may be deleted. |
| * Recursion:: Invoking @code{make} from commands in makefiles. |
| * Sequences:: Defining canned sequences of commands. |
| @end menu |
| |
| @node Echoing, Execution, Commands, Commands |
| @section Command Echoing |
| |
| @cindex echoing (of commands) |
| @cindex silent operation |
| @cindex @@ (in commands) |
| @cindex -n |
| Normally @code{make} prints each command line before it is executed. We |
| call this @dfn{echoing} because it gives the appearance that you are typing |
| the commands yourself. |
| |
| When a line starts with @samp{@@}, it is normally not echoed. The |
| @samp{@@} is discarded before the command is passed to the shell. Typically |
| you would use this for a command whose only effect is to print something, |
| such as an @code{echo} command. |
| |
| When @code{make} is given the flag @samp{-n}, echoing is all that happens, |
| no execution. @xref{Options}. In this case and only this case, even the |
| commands starting with @samp{@@} are printed. This flag is useful for |
| finding out which commands @code{make} thinks are necessary without |
| actually doing them. |
| |
| @cindex -s |
| @findex .SILENT |
| The @samp{-s} flag to @code{make} prevents all echoing, as if all commands |
| started with @samp{@@}. A rule in the makefile for the special target |
| @code{.SILENT} has the same effect (@pxref{Special Targets}). |
| @code{.SILENT} is essentially obsolete since @samp{@@} is more |
| general.@refill |
| |
| @node Execution, Errors, Echoing, Commands |
| @section Command Execution |
| @cindex execution |
| @cindex shell |
| |
| When it is time to execute commands to update a target, they are executed |
| one at a time by making a new subshell for each line. (In practice, |
| @code{make} may take shortcuts that do not affect the results.) |
| |
| This implies that shell commands such as @code{cd} that set variables local |
| to each process will not affect the following command lines. If you want |
| to use @code{cd} to affect the next command, put the two on a single line |
| with a semicolon between them. Then @code{make} will consider them a |
| single command and pass them, together, to a shell which will execute them |
| in sequence. For example: |
| |
| @example |
| foo : bar/lose |
| cd bar; gobble lose > ../foo |
| @end example |
| |
| If you would like to split a single shell command into multiple lines of |
| text, you must use a backslash at the end of all but the last subline. |
| Such a sequence of lines is combined into a single line, by deleting the |
| backslash-newline sequences, before passing it to the shell. Thus, the |
| following is equivalent to the preceding example: |
| |
| @group |
| @example |
| foo : bar/lose |
| cd bar; \ |
| gobble lose > ../foo |
| @end example |
| @end group |
| |
| @vindex SHELL |
| The program used as the shell is taken from the variable @code{SHELL}. By |
| default, the program @file{/bin/sh} is used. |
| |
| Unlike most variables, the variable @code{SHELL} will not be set from the |
| environment, except in a recursive @code{make}. This is because the |
| environment variable @code{SHELL} is used to specify your personal choice |
| of shell program for interactive use. It would be very bad for personal |
| choices like this to affect the functioning of makefiles. |
| @xref{Environment}. |
| |
| @node Errors, Interrupts, Execution, Commands |
| @section Errors in Commands |
| |
| @cindex error (in commands) |
| After each shell command returns, @code{make} looks at its exit status. |
| If the command completed successfully, the next command line is executed in |
| a new shell, or after the last command line the rule is finished. |
| |
| If there is an error (the exit status is nonzero), @code{make} gives up on |
| the current rule, and perhaps on all rules. |
| |
| Sometimes it does not matter whether a command fails. For example, you |
| may use the @code{mkdir} command to insure that a directory exists. If |
| the directory already exists, @code{mkdir} will report an error, but you |
| probably want @code{make} to continue regardless. |
| |
| @cindex - (in commands) |
| To ignore errors in a command line, write a @samp{-} at the beginning of |
| the line's text (after the initial tab). The @samp{-} is discarded before |
| the command is passed to the shell for execution. |
| |
| @cindex -i |
| @findex .IGNORE |
| When @code{make} is run with the @samp{-i} flag, errors are ignored in |
| all commands of all rules. A rule in the makefile for the special target |
| @code{.IGNORE} has the same effect. These ways of ignoring errors are |
| obsolete because @samp{-} is more general. |
| |
| When errors are to be ignored, because of either a @samp{-} or the |
| @samp{-i} flag, @code{make} treats an error return just like success. |
| |
| @cindex -k |
| When an error happens that @code{make} has not been told to ignore, |
| it implies that the current target cannot be correctly remade, and neither |
| can any other that depends on it either directly or indirectly. No further |
| commands will be executed for these targets, since their preconditions |
| have not been achieved. |
| |
| Normally @code{make} gives up immediately in this circumstance, returning a |
| nonzero status. However, if the @samp{-k} flag is specified, @code{make} |
| continues to consider the other dependencies 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, @samp{make -k} |
| will continue compiling other object files even though it already knows |
| that linking them will be impossible. @xref{Options}. |
| |
| The usual behavior assumes that your purpose is to get the specified |
| targets up to date; once @code{make} learns that this is impossible, it |
| might as well report the failure immediately. The @samp{-k} option says |
| that the real purpose is to test as much as possible of the changes made in |
| the program, perhaps to find several independent problems so that you can |
| correct them all before the next attempt to compile. This is why Emacs's |
| @code{compile} command passes the @samp{-k} flag by default. |
| |
| @node Interrupts, Recursion, Errors, Commands |
| @section Interrupting or Killing @code{make} |
| @cindex interrupt |
| @cindex signal |
| @cindex deletion of target files |
| |
| If @code{make} gets a fatal signal while a command is executing, it may |
| delete the target file that the command was supposed to update. This is |
| done if the target file's last-modification time has changed since |
| @code{make} first checked it. |
| |
| The purpose of deleting the target is to make sure that it is remade from |
| scratch when @code{make} is next run. Otherwise, a partially written file |
| could appear to be valid, since it is more recent than the dependencies. |
| |
| @findex .PRECIOUS |
| You can prevent the deletion of a target file in this way by making the |
| special target @code{.PRECIOUS} depend on it. Before remaking a target, |
| @code{make} checks to see whether it appears on the dependencies of |
| @code{.PRECIOUS}, and thereby decides whether the target should be deleted |
| if a signal happens. Some reasons why you might do this are that the |
| target is updated in some atomic fashion or exists only to record a |
| modification-time (its contents do not matter) or will cause trouble if it |
| ever fails to exist. |
| |
| @node Recursion, Sequences, Interrupts, Commands |
| @section Recursive Use of @code{make} |
| @cindex recursion |
| |
| Recursive use of @code{make} means using @code{make} as a command in a |
| makefile. This technique is useful when you want separate makefiles for |
| various subsystems that compose a larger system. For example, suppose you |
| have a subdirectory @file{subdir} which has its own makefile, and you would |
| like the containing directory's makefile to run @code{make} on the |
| subdirectory. You can do it by writing this: |
| |
| @example |
| subsystem: |
| cd subdir; $(MAKE) |
| @end example |
| |
| @noindent |
| or, equivalently, this (@pxref{Options}): |
| |
| @example |
| subsystem: |
| $(MAKE) -c subdir |
| @end example |
| |
| You can write recursive @code{make} commands just by copying this example, |
| but there are many things to know about how they work and why, and about |
| how the sub-@code{make} relates to the top-level @code{make}. |
| |
| @menu |
| * MAKE Variable:: Special effects of using @samp{$(MAKE)}. |
| * Variables/Recursion:: How variables are communicated to a sub-@code{make}. |
| * Options/Recursion:: How options are communicated to a sub-@code{make}. |
| * -w Option:: The @samp{-w} option facilitates debugging |
| makefiles with recursive @code{make} commands. |
| @end menu |
| |
| @node MAKE Variable, Variables/Recursion, Recursion, Recursion |
| @subsection How the @code{MAKE} Variable Works |
| @vindex MAKE |
| |
| Recursive @code{make} commands should always use the variable @code{MAKE}, |
| not the explicit command name @samp{make}, as shown here: |
| |
| @example |
| subsystem: |
| cd subdir; $(MAKE) |
| @end example |
| |
| The value of this variable is the file name with which @code{make} was |
| invoked. If this file name was @file{/bin/make}, then the command executed |
| is @samp{cd subdir; /bin/make}. If you use a special version of |
| @code{make} to run the top-level makefile, the same special version will be |
| executed for recursive invocations. |
| |
| Also, any arguments that define variable values are added to @code{MAKE}, |
| so the sub-@code{make} gets them too. Thus, if you do @samp{make |
| CFLAGS=-O}, so that all C-compilations will be optimized, the |
| sub-@code{make} is run with @samp{cd subdir; /bin/make CFLAGS=-O}.@refill |
| |
| As a special feature, using the variable @code{MAKE} in the commands of a |
| rule alters the effects of the @samp{-t}, @samp{-n} or @samp{-q} option. |
| (@xref{Instead of Execution}.)@refill |
| |
| Consider the command @samp{make -t} in the above example. Following the |
| usual definition of @samp{-t}, this would create a file named |
| @file{subsystem} and do nothing else. What you really want it to do is run |
| @samp{cd subdir; make -t}; but that would require executing the command, |
| and @samp{-t} says not to execute commands.@refill |
| |
| The special feature makes this do what you want: whenever a rule's commands |
| use the variable @code{MAKE}, the flags @samp{-t}, @samp{-n} or @samp{-q} |
| do not apply to that rule. The commands of that rule are executed normally |
| despite the presence of a flag that causes most commands not to be run. |
| The usual @code{MAKEFLAGS} mechanism passes the flags to the |
| sub-@code{make} (@pxref{Options/Recursion}), so your request to touch the |
| files, or print the commands, is propagated to the subsystem.@refill |
| |
| @node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion |
| @subsection Communicating Variables to a Sub-@code{make} |
| @cindex environment and recursion |
| |
| Most variable values of the top-level @code{make} are passed to the |
| sub-@code{make} through the environment. These variables are defined in |
| the sub-@code{make} as defaults, but do not override what is specified in |
| the sub-@code{make}'s makefile. (Variables are passed down if their names |
| consist of letters, numbers and underscores.) |
| |
| The way this works is that @code{make} adds each variable and its value to |
| the environment for running each command. (Variables whose names start |
| with non-alphanumeric characters are left out.) The sub-@code{make}, in |
| turn, uses the environment to initialize its table of variable values. |
| @xref{Environment}. |
| |
| @vindex MAKELEVEL |
| As a special feature, the variable @code{MAKELEVEL} is changed when it is |
| passed down from level to level. This variable's value is a string which |
| is the depth of the level as a decimal number. The value is @samp{0} for |
| the top-level @code{make}; @samp{1} for a sub-@code{make}, @samp{2} for a |
| sub-sub-@code{make}, and so on. The incrementation happens when |
| @code{make} sets up the environment for a command.@refill |
| |
| The main use of @code{MAKELEVEL} is to test it in a conditional directive |
| (@pxref{Conditionals}); this way you can write a makefile that behaves one |
| way if run recursively and another way if run directly by you. |
| |
| @vindex MAKEFILES |
| You can use the variable @code{MAKEFILES} to cause all sub-@code{make} |
| commands to use additional makefiles. The value of @code{MAKEFILES} is a |
| whitespace-separated list of filenames. This variable, if defined in the |
| outer-level makefile, is passed down through the environment as usual; then |
| it serves as a list of extra makefiles for the sub-@code{make} to read |
| before the usual or specified ones. @xref{MAKEFILES Variable}. |
| |
| @node Options/Recursion, -w Option, Variables/Recursion, Recursion |
| @subsection Communicating Options to a Sub-@code{make} |
| @cindex options and recursion |
| |
| @vindex MAKEFLAGS |
| Flags such as @samp{-s} and @samp{-k} are passed automatically to the |
| sub-@code{make} through the variable @code{MAKEFLAGS}. This variable is |
| set up automatically by @code{make} to contain the flag letters that |
| @code{make} received. Thus, if you do @samp{make -ks} then |
| @code{MAKEFLAGS} gets the value @samp{ks}.@refill |
| |
| As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS} |
| in its environment. In response, it takes the flags from that value and |
| processes them as if they had been given as arguments. @xref{Options}. |
| |
| The options @samp{-c}, @samp{-d}, @samp{-f}, @samp{-I}, @samp{-o}, and |
| @samp{-p} are not put into @code{MAKEFLAGS}; these options are not passed |
| down.@refill |
| |
| If you don't want to pass the other the flags down, you must change the |
| value of @code{MAKEFLAGS}, like this: |
| |
| @example |
| subsystem: |
| cd subdir; $(MAKE) MAKEFLAGS= |
| @end example |
| |
| @vindex MFLAGS |
| A similar variable @code{MFLAGS} exists also, for historical compatibility. |
| It has the same value as @code{MAKEFLAGS} except that a hyphen is added at |
| the beginning if it is not empty. @code{MFLAGS} was traditionally used |
| explicitly in the recursive @code{make} command, like this: |
| |
| @example |
| subsystem: |
| cd subdir; $(MAKE) $(MFLAGS) |
| @end example |
| |
| @noindent |
| but now @code{MAKEFLAGS} makes this usage redundant. |
| |
| @node -w Option,, Options/Recursion, Recursion |
| @subsection The @samp{-w} Option |
| |
| If you are running @code{make} over a large directory tree, the @samp{-w} |
| option can make the output a lot easier to understand by showing each |
| directory as it is entered and exited. For example, if @samp{make -w} is |
| run in the directory @file{/u/gnu/make}, @code{make} will print a line of |
| the form:@refill |
| |
| @example |
| make: Entering directory `/u/gnu/make'. |
| @end example |
| |
| @noindent |
| before doing anything else, and a line of this form: |
| |
| @example |
| make: Leaving directory `/u/gnu/make'. |
| @end example |
| |
| @noindent |
| when processing is completed. |
| |
| @node Sequences,, Recursion, Commands |
| @section Defining Canned Command Sequences |
| @cindex sequences of commands |
| |
| When the same sequence of commands is useful in making various targets, you |
| can define it as a canned sequence with the @code{define} directive, and |
| refer to the canned sequence from the rules for those targets. The canned |
| sequence is actually a variable, so the name must not conflict with other |
| variable names. |
| |
| Here is an example of defining a canned sequence of commands: |
| |
| @example |
| define run-yacc |
| yacc $(firstword $^) |
| mv y.tab.c $@@ |
| endef |
| @end example |
| |
| @noindent |
| Here @code{run-yacc} is the name of the variable being defined; |
| @code{endef} marks the end of the definition; the lines in between are the |
| commands. The @code{define} directive does not expand variable references |
| and function calls in the canned sequence; the @samp{$} characters, |
| parentheses, variable names, and so on, all become part of the value of the |
| variable you are defining. @xref{Defining}, for a complete explanation of |
| @code{define}. |
| |
| The first command in this example runs Yacc on the first dependency (of |
| whichever rule uses the canned sequence). The output file from Yacc is |
| always named @file{y.tab.c}. The second command moves the output to the |
| rule's target file name. |
| |
| To use the canned sequence, substitute the variable into the commands of a |
| rule. You can substitute it like any other variable (@pxref{Reference}). |
| Because variables defined by @code{define} are recursively expanded |
| variables, all the variable references you wrote inside the @code{define} |
| are expanded now. For example: |
| |
| @example |
| foo.c : foo.y |
| $(run-yacc) |
| @end example |
| |
| @noindent |
| @samp{foo.y} will substituted for the variable @samp{$^} when it occurs in |
| @code{run-yacc}'s value, and @samp{foo.c} for @samp{$@@}.@refill |
| |
| This is a realistic example, but this particular one is not needed in |
| practice because @code{make} has an implicit rule to figure out these |
| commands based on the file names involved. @xref{Implicit}. |
| |
| @node Variables, Conditionals, Commands, Top |
| @chapter How to Use Variables |
| @cindex variable |
| @cindex value |
| @cindex recursive variable expansion |
| @cindex simple variable expansion |
| |
| A @dfn{variable} is a name defined within @code{make} to represent a string |
| of text, called the variable's @dfn{value}. These values can be |
| substituted by explicit request into targets, dependencies, commands and |
| other parts of the makefile. |
| |
| Variables can represent lists of file names, options to pass to compilers, |
| programs to run, directories to look in for source files, directories to |
| write output in, or anything else you can imagine. |
| |
| A variable name may be any sequence characters not containing @samp{:}, |
| @samp{#}, @samp{=}, leading or trailing whitespace. However, |
| variable names containing characters other than letters, numbers and |
| underscores should be avoided, as they may be given special meanings in the |
| future, and they are not passed through the environment to a |
| sub-@code{make} (@pxref{Variables/Recursion}). |
| |
| It is traditional to use upper case letters in variable names, but we |
| recommend using lower case letters for variable names that serve internal |
| purposes in the makefile, and reserving upper case for parameters that |
| control implicit rules or for parameters that the user should override with |
| command options (@pxref{Overriding}). |
| |
| @menu |
| * Reference:: How to use the value of a variable. |
| * Values:: All the ways variables get their values. |
| * Flavors:: Variables come in two flavors. |
| * Setting:: How to set a variable in the makefile. |
| * Override Directive:: Setting a variable in the makefile |
| even if the user has set it with a command argument. |
| * Defining:: An alternate way to set a variable to a verbatim string. |
| * Environment:: Variable values can come from the environment. |
| @end menu |
| |
| @node Reference, Values, Variables, Variables |
| @section Reference to Variables |
| @cindex reference to variables |
| @cindex $ (variable reference) |
| |
| To substitute a variable's value, write a dollar sign followed by the name |
| of the variable in parentheses or braces: either @samp{$(foo)} or |
| @samp{$@{foo@}} is a valid reference to the variable @code{foo}. This |
| special significance of @samp{$} is why you must write @samp{$$} to have |
| the effect of a single dollar sign in a file name or command. |
| |
| Variable references can be used in any context: targets, dependencies, |
| commands, most directives, and new variable values. Here is a common kind |
| of example, where a variable holds the names of all the object files in a |
| program: |
| |
| @example |
| objects = program.o foo.o utils.o |
| program : $(objects) |
| cc -o program $(objects) |
| |
| $(objects) : defs.h |
| @end example |
| |
| Variable references work by strict textual substitution. Thus, the rule |
| |
| @example |
| foo = c |
| prog.o : prog.c |
| $(foo)$(foo) prog.c |
| @end example |
| |
| @noindent |
| could be used to compile a C program @file{prog.c}. (Since spaces around |
| the variable value are ignored in variable assignments, the value of |
| @code{foo} is precisely @samp{c}.) |
| |
| A dollar sign followed by a character other than a dollar sign, |
| open-parenthesis or open-brace treats that single character as the variable |
| name. Thus, you could reference the variable @code{x} with @samp{$x}. |
| However, this practice is strongly discouraged, except with the automatic |
| variables (@pxref{Automatic}). |
| |
| |
| @subsection Modified References |
| @cindex modified variable reference |
| @cindex substitution variable reference |
| |
| In addition to simple references, variables can be referenced in a manner |
| which modifies the value of the reference but do not modify the value of |
| the variable referenced. Such a reference is a @dfn{substitution reference}. |
| |
| A @dfn{substitution reference} is really a simplified form of the |
| @code{patsubst} expansion function (@pxref{Functions}). It has the form |
| @samp{$(var:a=b)} (or @samp{$@{var:a=b@}}) and is equivalent to |
| @samp{$(patsubst %a,%b,$(var))}. This means that it replaces every |
| @samp{a} at the end of a whitespace-separated word with a @samp{b}. |
| For example:@refill |
| |
| @example |
| foo := a.o b.o c.o |
| bar := $(foo:.o=.c) |
| @end example |
| |
| @noindent |
| sets @samp{bar} to @samp{a.c b.c c.c}. @xref{Setting}. |
| |
| @subsection Recursive References |
| @cindex recursive variable reference |
| |
| Variables may be referenced inside a variable reference. This is called |
| a @dfn{recursive variable reference}. For example, |
| |
| @example |
| x = y |
| y = z |
| a := $($(x)) |
| @end example |
| |
| @noindent |
| defines @samp{a} as @samp{z}: the @samp{$(x)} inside @samp{$($(x))} expands |
| to @samp{y}, so @samp{$($(x))} expands to @samp{$(y)} which in turn expands |
| to @samp{z}.@refill |
| |
| Recursive variable references can get yet more recursive. For example, |
| |
| @example |
| x = $(y) |
| y = z |
| z = Hello |
| a := $($(x)) |
| @end example |
| |
| @noindent |
| defines @samp{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))} |
| which becomes @samp{$(z)} which becomes @samp{Hello}. This sort of |
| recursion can go on for as many levels as you like (and can comprehend), |
| though it's not clear that very many levels of recursion are useful.@refill |
| |
| Recursive variable references can also contain modified references and |
| function invokations (@pxref{Functions}), just like any other reference. |
| For example, using the @code{subst} function (@pxref{Text Functions}): |
| |
| @example |
| x = variable1 |
| variable2 := Hello |
| y = $(subst 1,2,$(x)) |
| z = y |
| a := $($($(z))) |
| @end example |
| |
| @noindent |
| eventually defines @samp{a} as @samp{Hello}. It is doubtful that anyone |
| would ever want to write a recursive reference as convoluted as this one, |
| but it works: @samp{$($($(z)))} expands to @samp{$($(y))} which becomes |
| @samp{$($(subst 1,2,$(x)))} which changes @samp{variable1} to |
| @samp{variable2} in @samp{$(x)} and finally expands to @samp{$(variable2)}, |
| a simple variable reference that becomes @samp{Hello}.@refill |
| |
| Recursive variable references are a complicated concept needed only for |
| very complex makefile programming. You need not worry about them in |
| general, except to know that making a variable with a dollar sign in its |
| name might have strange results. Note also that @dfn{recursive variable |
| references} are quite different from @dfn{recursive variables} |
| (@pxref{Flavors}), though both are used together in complex ways when |
| doing makefile programming.@refill |
| |
| @node Values, Flavors, Reference, Variables |
| @section How Variables Get Their Values |
| |
| Variables can get values in several different ways: |
| |
| @itemize @bullet |
| @item |
| You can specify an overriding value when you run @code{make}. |
| @xref{Overriding}. |
| |
| @item |
| You can specify a value in the makefile, either with an assignment |
| (@pxref{Setting}) or with a verbatim definition (@pxref{Defining}). |
| |
| @item |
| Values are inherited from the environment. @xref{Environment}. |
| |
| @item |
| Several @dfn{automatic} variables are given new values for each rule. |
| @xref{Automatic}. |
| |
| @item |
| Several variables have constant initial values. @xref{Implicit Variables}. |
| @end itemize |
| |
| @node Flavors, Setting, Values, Variables |
| @section The Two Flavors of Variables |
| @cindex flavors (of variables) |
| @cindex recursive variable expansion |
| |
| There are two kinds of variables in GNU @code{make}. They are |
| distinguished by two things: how they are defined and how they are expanded. |
| |
| The first flavor of variable is a @dfn{recursively expanded} variable. |
| Variables of this sort are defined by lines using @samp{=} |
| @ifinfo |
| (@pxref{Setting}). |
| @end ifinfo |
| @iftex |
| (see the next section). |
| @end iftex |
| The value you specify is installed verbatim; if it contains references to |
| other variables, these references are expanded whenever this variable is |
| substituted (in the course of expanding some other string). When this |
| happens, it is recursive expansion. |
| |
| For example, |
| |
| @example |
| foo = $(bar) |
| bar = $(ugh) |
| ugh = Huh? |
| |
| all:;echo $(foo) |
| @end example |
| |
| @noindent |
| will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which |
| expands to @samp{$(ugh)} which finally expands to @samp{Huh?}.@refill |
| |
| This flavor of variable is the only sort supported by other versions of |
| @code{make}. It has its advantages and its disadvantages. An advantage |
| (most would say) is that: |
| |
| @example |
| CFLAGS = $(include_dirs) -O |
| include_dirs = -Ifoo -Ibar |
| @end example |
| |
| @noindent |
| will do what was intended: when @samp{CFLAGS} is expanded in a command, |
| it will expand to @samp{-Ifoo -Ibar}. A major disadvantage is that you |
| can't append something on the end of a variable, as in |
| |
| @example |
| CFLAGS = $(CFLAGS) -O |
| @end example |
| |
| @noindent |
| because it will cause an infinite loop in the variable expansion. |
| (Actually @code{make} detects the infinite loop and reports an error.) |
| |
| Another disadvantage is that any functions (@pxref{Functions}) referenced |
| in the definition will be executed every time the variable is expanded. |
| This makes @code{make} run slower; worse, it causes the @code{wildcard} |
| function to give unpredictable results. |
| |
| To avoid all the problems and inconveniences of recursively expanded |
| variables, there is another flavor: @dfn{simply expanded} variables. |
| Simply expanded variables are defined by lines using @samp{:=} |
| @ifinfo |
| (@pxref{Setting}). |
| @end ifinfo |
| @iftex |
| (see the next section). |
| @end iftex |
| The value of a simply expanded variable is scanned once and for all, |
| expanding any references to other variables and functions, when the |
| variable is defined. The actual value of the simply expanded variable is |
| the result of expanding the value you write. It does not contain any |
| references to other variables; it contains their values @emph{as of the |
| time this variable was defined}. Therefore, |
| |
| @example |
| x := foo |
| y := $(x) bar |
| x := later |
| @end example |
| |
| @noindent |
| is equivalent to |
| |
| @example |
| y := foo bar |
| x := later |
| @end example |
| |
| When a simply expanded variable is referenced, its value is substituted |
| verbatim. |
| |
| Simply expanded variables generally make complicated makefile programming |
| more predictable because they work like variables in most programming |
| languages. They allow you to redefine a variable using its own value (or |
| its value processed in some way by one of the expansion functions) and to |
| use the expansion functions much more efficiently (@pxref{Functions}). |
| |
| You can also use them to introduce controlled leading or trailing spaces |
| into variable values. Such spaces are discarded from your input before |
| substitution of variable references and function calls; this means you can |
| include leading or trailing spaces in a variable value by protecting them |
| with variable references, like this: |
| |
| @example |
| nullstring := |
| space := $(nullstring) $(nullstring) |
| @end example |
| |
| @noindent |
| Here the value of the variable @code{space} is precisely one space. |
| |
| @node Setting, Override Directive, Flavors, Variables |
| @section Setting Variables |
| @cindex setting variables |
| @cindex = |
| @cindex := |
| |
| To set a variable from the makefile, write a line starting with the |
| variable name followed by @samp{=} or @samp{:=}. Whatever follows the |
| @samp{=} or @samp{:=} on the line becomes the value. For example, |
| |
| @example |
| objects = main.o foo.o bar.o utils.o |
| @end example |
| |
| @noindent |
| defines a variable named @code{objects}. Spaces around the variable name |
| are ignored, and so are spaces after the @samp{=} or at the end of the |
| line. |
| |
| Variables defined with @samp{=} are @dfn{recursively expanded} variables. |
| Variables defined with @samp{:=} are @dfn{simply expanded} variables; these |
| definitions can contain variable references which will be expanded before |
| the definition is made. @xref{Flavors}. |
| |
| There is no limit on the length of the value of a variable except the |
| amount of swapping space on the computer. When a variable definition is |
| long, it is a good idea to break it into several lines by inserting |
| backslash-newline at convenient places in the definition. This will not |
| affect the functioning of @code{make}, but it will make the makefile easier |
| to read. |
| |
| Most variable names are considered to have the empty string as a value if |
| you have never set them. Several variables have built-in initial values |
| that are not empty, but can be set by you in the usual ways |
| (@pxref{Implicit Variables}). Several special variables are set |
| automatically to a new value for each rule; these are called the |
| @dfn{automatic} variables (@pxref{Automatic}). |
| |
| @node Override Directive, Defining, Setting, Variables |
| @section The @code{override} Directive |
| @findex override |
| |
| If a variable has been set with a command argument (@pxref{Overriding}), |
| then ordinary assignments in the makefile are ignored. If you want to set |
| the variable in the makefile even though it was set with a command |
| argument, you can use an @code{override} directive, which is a line that |
| looks like this: |
| |
| @example |
| override @var{variable} = @var{value} |
| @end example |
| |
| or |
| |
| @example |
| override @var{variable} := @var{value} |
| @end example |
| |
| The @code{override} directive was not invented for escalation in the war |
| between makefiles and command arguments. It was invented so you can alter |
| and add to values that the user specifies with command arguments. |
| |
| For example, suppose you always want the @samp{-g} switch when you run the |
| C compiler, but you would like to allow the user to specify the other |
| switches with a command argument just as usual. You could use this |
| @code{override} directive: |
| |
| @example |
| override CFLAGS := $(CFLAGS) -g |
| @end example |
| |
| @node Defining, Environment, Override Directive, Variables |
| @section Defining Variables Verbatim |
| @findex define |
| @findex endef |
| |
| Another way to set the value of a variable is to use the @code{define} |
| directive. This directive has a different syntax which allows newline |
| characters to be included in the value, which is convenient for defining |
| canned sequences of commands (@pxref{Sequences}). |
| |
| The @code{define} directive is followed on the same line the name of the |
| variable and nothing more. The value to give the variable appears on the |
| following lines. The end of the value is marked by a line containing just |
| the word @code{endef}. Aside from this difference in syntax, @code{define} |
| works just like @samp{=}; it creates a recursively-expanded variable |
| (@pxref{Flavors}). |
| |
| @example |
| define two-lines |
| echo foo |
| echo $(bar) |
| endef |
| @end example |
| |
| The value in an ordinary assignment cannot contain a newline; but the |
| newlines that separate the lines of the value in a @code{define} become |
| part of the variable's value (except for the final newline which precedes |
| the @code{endef} and is not considered part of the value).@refill |
| |
| The previous example is functionally equivalent to this: |
| |
| @example |
| two-lines = echo foo; echo $(bar) |
| @end example |
| |
| @noindent |
| since the shell will interpret the semicolon and the newline identically. |
| |
| @node Environment,, Defining, Variables |
| @section Variables from the Environment |
| |
| @cindex environment |
| Variables in @code{make} can come from the environment with which |
| @code{make} is run. Every environment variable that @code{make} sees when |
| it starts up is transformed into a @code{make} variable with the same name |
| and value. But an explicit assignment in the makefile, or with a command |
| argument, overrides the environment. (If the @samp{-e} flag is specified, |
| then values from the environment override assignments in the makefile. |
| @xref{Options}. But this is not recommended practice.) |
| |
| By setting the variable @code{CFLAGS} in your environment, you can cause |
| all C compilations in most makefiles to use the compiler switches you |
| prefer. This is safe for variables with standard or conventional meanings |
| because you know that no makefile will use them for other things. (But |
| this is not totally reliable; some makefiles set @code{CFLAGS} explicitly |
| and therefore are not affected by the value in the environment.) |
| |
| When @code{make} is invoked recursively, variables defined in the outer |
| invocation are automatically passed to inner invocations through the |
| environment (@pxref{Recursion}). This is the main purpose of turning |
| environment variables into @code{make} variables, and it requires no |
| attention from you. |
| |
| Other use of variables from the environment is not recommended. It is not |
| wise for makefiles to depend for their functioning on environment variables |
| set up outside their control, since this would cause different users to get |
| different results from the same makefile. This is against the whole |
| purpose of most makefiles. |
| |
| Such problems would be especially likely with the variable @code{SHELL}, |
| which is normally present in the environment to specify the user's choice |
| of interactive shell. It would be very undesirable for this choice to |
| affect @code{make}. So @code{make} ignores the environment value of |
| @code{SHELL} if the value of @code{MAKELEVEL} is zero (which is normally |
| true except in recursive invocations of @code{make}).@refill |
| |
| @node Conditionals, Functions, Variables, Top |
| @chapter Conditional Parts of Makefiles |
| |
| @cindex conditionals |
| A @dfn{conditional} causes part of a makefile to be obeyed or ignored |
| depending on the values of variables. Conditionals can compare the value |
| of one variable with another, or the value of a variable with a constant |
| string. Conditionals control what @code{make} actually ``sees'' in the |
| makefile, so they @emph{cannot} be used to control shell commands at the |
| time of execution.@refill |
| |
| @menu |
| * Example: Conditional Example. An annotated example. |
| * Syntax: Conditional Syntax. Precise rules for syntax of conditionals. |
| * Flags: Testing Flags. Conditionals testing flags such as @samp{-t}. |
| @end menu |
| |
| @node Conditional Example, Conditional Syntax, Conditionals, Conditionals |
| @section Example of a Conditional |
| |
| This conditional tells @code{make} to use one set of libraries if the |
| @code{CC} variable is @samp{gcc}, and a different set of libraries |
| otherwise. It works by controlling which of two command lines will be used |
| as the command for a rule. The result is that @samp{CC=gcc} as an argument |
| to @code{make} not only changes which compiler is used but also which |
| libraries are linked. |
| |
| @example |
| 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 |
| @end example |
| |
| @noindent |
| This conditional uses three directives: one @code{ifeq}, one @code{else} |
| and one @code{endif}. |
| |
| The @code{ifeq} directive contains two arguments, separated by a comma and |
| surrounded by parentheses. Variable substitution is performed on both |
| arguments and then they are compared. The lines of the makefile following |
| the @code{ifeq} are obeyed if the two arguments match; otherwise they are |
| ignored. |
| |
| The @code{else} directive causes the following lines to be obeyed if the |
| previous conditional failed. In the example above, this means that the |
| second alternative linking command is used whenever the first alternative |
| is not used. It is optional to have an @code{else} in a conditional. |
| |
| The @code{endif} directive ends the conditional. Every conditional must |
| end with an @code{endif}. Unconditional makefile text follows. |
| |
| When the variable @code{CC} has the value @samp{gcc}, the above example has |
| this effect: |
| |
| @example |
| foo: $(objects) |
| $(CC) -o foo $(objects) $(libs_for_gcc) |
| @end example |
| |
| @noindent |
| When the variable @code{CC} has any other value, this effect is this: |
| |
| @example |
| foo: $(objects) |
| $(CC) -o foo $(objects) $(normal_libs) |
| @end example |
| |
| Equivalent results can be obtained in another way by conditionalizing a |
| variable assignment and then using the variable unconditionally: |
| |
| @example |
| 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) |
| @end example |
| |
| @node Conditional Syntax, Testing Flags, Conditional Example, Conditionals |
| @section Syntax of Conditionals |
| @findex ifdef |
| @findex ifeq |
| @findex else |
| @findex endif |
| |
| The syntax of a simple conditional with no @code{else} is as follows: |
| |
| @example |
| @var{conditional-directive} |
| @var{text-if-true} |
| endif |
| @end example |
| |
| @noindent |
| The @var{text-if-true} may be any lines of text, to be considered as part |
| of the makefile if the condition is true. If the condition is false, no |
| text is used instead. |
| |
| The syntax of a complex conditional is as follows: |
| |
| @example |
| @var{conditional-directive} |
| @var{text-if-true} |
| else |
| @var{text-if-false} |
| endif |
| @end example |
| |
| @noindent |
| If the condition is true, @var{text-if-true} is used; otherwise, |
| @var{text-if-false} is used instead. The @var{text-if-false} can be any |
| number of lines of text. |
| |
| Conditionals work at the textual level. The lines of the |
| @var{text-if-true} are read as part of the makefile if the condition is |
| true; if the condition is false, those lines are ignored completely. It |
| follows that syntactic units of the makefile, such as rules, may safely be |
| split across the beginning or the end of the conditional.@refill |
| |
| You may use an @code{include} directive within a conditional, but you may |
| not start a conditional in one file and end it in another. |
| |
| The syntax of the @var{conditional-directive} is the same whether the |
| conditional is simple or complex. There are four different directives that |
| test different conditions. Here is a table of them: |
| |
| @table @code |
| @item ifeq (@var{arg1}, @var{arg2}) |
| Expand all variable references in @var{arg1} and @var{arg2} and |
| compare them. If they are identical, the @var{text-if-true} is |
| effective; otherwise, the @var{text-if-false}, if any, is effective. |
| |
| @item ifneq (@var{arg1}, @var{arg2}) |
| Expand all variable references in @var{arg1} and @var{arg2} and |
| compare them. If they are different, the @var{text-if-true} is |
| effective; otherwise, the @var{text-if-false}, if any, is effective. |
| |
| @item ifdef @var{variable-name} |
| If the variable @var{variable-name} has a non-empty value, the |
| @var{text-if-true} is effective; otherwise, the @var{text-if-false}, |
| if any, is effective. Variables that have never been defined have an |
| empty value. |
| |
| @item ifndef @var{variable-name} |
| If the variable @var{variable-name} has an empty value, the |
| @var{text-if-true} is effective; otherwise, the @var{text-if-false}, |
| if any, is effective. |
| @end table |
| |
| Extra spaces are allowed and ignored at the beginning of the conditional |
| directive line, but a tab is not allowed. (If the line begins with a tab, |
| it will be considered a command for a rule.) Aside from this, extra spaces |
| or tabs may be inserted with no effect anywhere except within the directive |
| name or within an argument. A comment starting with @samp{#} may appear at |
| the end of the line. |
| |
| The other two directives that play a part in a conditional are @code{else} |
| and @code{endif}. Each of these directives is written as one word, with no |
| arguments. Extra spaces are allowed and ignored at the beginning of the |
| line, and spaces or tabs at the end. A comment starting with @samp{#} may |
| appear at the end of the line. |
| |
| @node Testing Flags,, Conditional Syntax, Conditionals |
| @section Conditionals that Test Flags |
| |
| You can write a conditional that tests @code{make} command flags such as |
| @samp{-t} by using the variable @code{MAKEFLAGS} together with the |
| @code{findstring} function. This is useful when @code{touch} is not |
| enough to make a file appear up to date. |
| |
| The @code{findstring} function determines whether one string appears as a |
| substring of another. If you want to test for the @samp{-t} flag, |
| use @samp{t} as the first string and the value of @code{MAKEFLAGS} as |
| the other. |
| |
| For example, here is how to arrange to use @samp{ranlib -t} to finish |
| marking an archive file up to date: |
| |
| @example |
| archive.a: @dots{} |
| ifneq (,$(findstring t,$(MAKEFLAGS))) |
| @@echo $(MAKE) > /dev/null |
| touch archive.a |
| ranlib -t archive.a |
| else |
| ranlib archive.a |
| endif |
| @end example |
| |
| @noindent |
| The @code{echo} command does nothing when executed; but its presence, with |
| a reference to the variable @code{MAKE}, marks the rule as ``recursive'' so |
| that its commands will be executed despite use of the @samp{-t} flag. |
| @xref{Recursion}. |
| |
| @node Functions, Running, Conditionals, Top |
| @chapter Functions for Transforming Text |
| @cindex function |
| |
| @dfn{Functions} allow you to do text processing in the makefile to compute |
| the files to operate on or the commands to use. You use a function in a |
| @dfn{function call}, where you give the name of the function and some text |
| (the @dfn{arguments}) for the function to operate on. The result of the |
| function's processing is substituted into the makefile at the point of the |
| call, just as a variable might be substituted. |
| |
| @menu |
| * Syntax: Function Syntax. Syntax of function calls in general. |
| * Text Functions:: Text manipulation functions. |
| * Foreach Function:: The @code{foreach} function. |
| * Filename Functions:: Functions for manipulating file names. |
| @end menu |
| |
| @node Function Syntax, Text Functions, Functions, Functions |
| @section Function Call Syntax |
| @cindex $ (function call) |
| @cindex arguments |
| |
| A function call resembles a variable reference. It looks like this: |
| |
| @example |
| $(@var{function} @var{arguments}) |
| @end example |
| |
| @noindent |
| or like this: |
| |
| @example |
| $@{@var{function} @var{arguments}@} |
| @end example |
| |
| Here @var{function} is a function name; one of a short list of names that |
| are part of @code{make}. There is no provision for defining new functions. |
| |
| The @var{arguments} are the arguments of the function. They are separated |
| from the function name by one or more spaces and/or tabs, and if there is |
| more than one argument they are separated by commas. Such whitespace and |
| commas are not part of any argument's value. Parentheses or braces, |
| whichever you use to surround the function call, can appear in an argument |
| only in matching pairs; the ones that were not used to surround the |
| function call can appear freely. If the arguments contain other function |
| calls or variable references, it is wisest to surround them with the same |
| delimiters used for the containing function call. |
| |
| The text written for each argument is processed by substitution of |
| variables and function calls in order to produce the argument value, which |
| is the text on which the function acts. |
| |
| Commas and unmatched parentheses or braces cannot appear in the text of an |
| argument as written; leading spaces cannot appear in the text of the first |
| argument as written. These characters can be put into the argument value |
| by variable substitution. First define variables @code{comma} and |
| @code{space} whose values are isolated comma and space characters, then |
| substitute those variables where such characters are wanted, like this: |
| |
| @example |
| comma:= , |
| space:= $(empty) $(empty) |
| foo:= a b c |
| bar:= $(subst $(space),$(comma),$(foo)) |
| # @r{bar is now `a,b,c'.} |
| @end example |
| |
| @noindent |
| Here the @code{subst} function replaces each space with a comma, through |
| the value of @code{foo}, and substitutes the result. |
| |
| @node Text Functions, Foreach Function, Function Syntax, Functions |
| @section Functions for String Substitution and Analysis |
| |
| Here are some functions that operate on substrings of a string: |
| |
| @table @code |
| @item $(subst @var{from},@var{to},@var{text}) |
| @findex subst |
| Performs a textual replacement on the text @var{text}: each occurrence |
| of @var{from} is replaced by @var{to}. The result is substituted for |
| the function call. For example, |
| |
| @example |
| $(subst ee,EE,feet on the street) |
| @end example |
| |
| substitutes the string @samp{fEEt on the strEEt}. |
| |
| @item $(patsubst @var{pattern},@var{replacement},@var{text}) |
| @findex patsubst |
| Finds whitespace-separated words in @var{text} that match |
| @var{pattern} and replaces them with @var{replacement}. Here |
| @var{pattern} may contain a @samp{%} which acts as a wildcard, |
| matching any number of any characters within a word. If |
| @var{replacement} also contains a @samp{%}, the @samp{%} is replaced |
| by the text that matched the @samp{%} in @var{pattern}. |
| |
| Whitespace between words is folded into single space characters; |
| leading and trailing whitespace is discarded. |
| |
| @item $(strip @var{string}) |
| @findex strip |
| Removes leading and trailing whitespace from @var{string} and replaces |
| each internal sequence of one or more whitespace characters with a |
| single space. |
| |
| @item $(findstring @var{find},@var{in}) |
| @findex findstring |
| Searches @var{in} for an occurrence of @var{find}. If it occurs, the |
| value is @var{find}; otherwise, the value is empty. You can use this |
| function in a conditional to test for the presence of a specific |
| substring in a given string. @xref{Testing Flags}, for a practical |
| application of @code{findstring}. |
| |
| @item $(filter @var{pattern},@var{text}) |
| @findex filter |
| Removes all whitespace-separated words in @var{text} that do @emph{not} |
| match @var{pattern}, returning only matching words. The pattern is one |
| using @samp{%} as used in the @code{patsubst} function. This can be used |
| to separate out different types of strings (such as filenames) in a variable. |
| For example:@refill |
| |
| @example |
| sources := foo.c bar.c ugh.h |
| foo: $(sources) |
| cc $(filter %.c,$(sources)) -o foo |
| @end example |
| |
| @noindent |
| says that @file{foo} depends of @file{foo.c}, @file{bar.c} and |
| @file{ugh.h} but only @file{foo.c} and @file{bar.c} should be specified |
| in the command to the compiler.@refill |
| |
| @item $(filter-out @var{pattern},@var{text}) |
| @findex filter-out |
| Removes all whitespace-separated words in @var{text} that @emph{do} |
| match @var{pattern}, returning only matching words. This is the exact |
| opposite of the @code{filter} function.@refill |
| |
| @item $(sort @var{list}) |
| @findex sort |
| Sorts the words of @var{list} in lexical order, removing duplicate |
| words. The output is a list of words separated by single spaces. |
| @end table |
| |
| Here is a realistic example of the use of @code{subst}. Suppose that a |
| makefile uses the @code{VPATH} variable to specify a list of directories |
| that @code{make} should search for dependency files. This example shows |
| how to tell the C compiler to search for header files in the same list of |
| directories. |
| |
| The value of @code{VPATH} is a list of directories separated by colons, |
| such as @samp{src:../headers}. First, the @code{subst} function is used to |
| change the colons to spaces: |
| |
| @example |
| $(subst :, ,$(VPATH)) |
| @end example |
| |
| @noindent |
| This produces @samp{src ../headers}. Then another function, |
| @code{addprefix}, can turn each directory name into an @samp{-I} flag. |
| These can be added to the value of the variable @code{CFLAGS}, which is |
| passed automatically to the C compiler, like this: |
| |
| @example |
| override CFLAGS:= $(CFLAGS) $(addprefix -I,$(subst :, ,$(VPATH))) |
| @end example |
| |
| @noindent |
| The effect is to append the text @samp{-Isrc -I../headers} to the |
| previously given value of @code{CFLAGS}. The @code{override} directive is |
| used so that the new value is assigned even if the previous value of |
| @code{CFLAGS} was specified with a command argument (@pxref{Override |
| Directive}). |
| |
| The function @code{strip} can be very useful when used in conjunction |
| with conditionals. When comparing something with the null string |
| @samp{""} using @code{ifeq} or @code{ifneq}, you usually want a string |
| of just whitespace to match the null string. Thus, |
| |
| @example |
| .PHONY: all |
| ifneq "$(needs_made)" "" |
| all: $(needs_made) |
| else |
| all:;@@echo 'Nothing to make!' |
| endif |
| @end example |
| |
| @noindent |
| might fail to have the desired results. Replacing the variable reference |
| @samp{"$(needs_made)"} with the function call @samp{"$(strip |
| $(needs_made))"} in the @code{ifneq} directive would make it more robust. |
| |
| @node Foreach Function, Filename Functions, Text Functions, Functions |
| @section The @code{foreach} Function |
| @findex foreach |
| |
| The @code{foreach} function is very different from other functions. It |
| causes one piece of text to be used repeatedly, each time with a different |
| substitution performed on it. It resembles the @code{for} command in the |
| shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}. |
| |
| The syntax of the @code{foreach} function is: |
| |
| @example |
| $(foreach @var{var},@var{list},@var{text}) |
| @end example |
| |
| @noindent |
| The first two arguments, @var{var} and @var{list}, are expanded before |
| anything else is done; note that the last argument, @var{text}, is |
| @emph{not} expanded at the same time. Then for each word of the expanded |
| value of @var{list}, the variable named by the expanded value of @var{var} |
| is set to that word, and @var{text} is expanded. Presumably @var{text} |
| contains references to that variable, so the expansions will be different |
| each time. |
| |
| The result is that @var{text} is expanded as many times as there are |
| whitespace-separated words in @var{list}. The multiple expansions of |
| @var{text} are concatenated, with spaces between them, to make the result |
| of @code{foreach}. |
| |
| This simple example sets the variable @samp{files} to the list of all files |
| in the directories in the list @samp{dirs}: |
| |
| @example |
| find_files = $(wildcard $(dir)/*) |
| dirs := a b c d |
| files := $(foreach dir,$(dirs),$(find_files)) |
| @end example |
| |
| For readability, it is a good idea to put the @var{text} part of a |
| @code{foreach} function invokation into a variable. Here we use the |
| variable @code{find_file} this way. We make this a recursively-expanding |
| variable by using @samp{=} to define it. This is necessary so that when |
| its value is substituted by @code{foreach} the value is rescanned for |
| variable references and function calls. This is what causes the |
| @code{wildcard} function actually to be called. |
| |
| This example has the same result (except for setting @samp{find_files}, |
| @samp{dirs} and @samp{dir}) as the following example: |
| |
| @example |
| files := $(wildcard a/* b/* c/* d/*) |
| @end example |
| |
| The value of the variable @var{var} after the @code{foreach} function call |
| is the same as the value beforehand. Other values taken from @var{list} |
| are in effect only temporarily, during the execution of @code{foreach}. |
| The variable @var{var} is a simply-expanded variable during the execution |
| of @code{foreach} but is returned to the same flavor it was before the |
| @code{foreach} when it is done. @xref{Flavors}. |
| |
| If @var{var} was previously undefined, then it is defined as a recursively |
| expanded variable (@samp{=}, not @samp{:=}) during the @code{foreach} and |
| remains so (with a null value) afterward. |
| |
| Because it is expanded before @code{foreach} runs, the @var{var} argument |
| to @code{foreach} need not be a literal variable name. It can instead be a |
| variable expression resulting in the name. Thus, |
| |
| @example |
| dir := a |
| var = $(whatsthevar) |
| foo := dar |
| whatsthevar := $(subst a,i,$(foo)) |
| files := $(foreach $(var),$(dirs),$(find_files)) |
| @end example |
| |
| @noindent |
| is ultimately equivalent to the first example. You must take care when |
| using complex variable expressions that result in variable names because |
| many strange things are legal variable names, and these might not be what |
| you intended. For example, |
| |
| @example |
| files := $(foreach Es escrito en espanol!,b c ch,$(find_files)) |
| @end example |
| |
| @noindent |
| might be useful if @samp{find_files} references the variable @samp{Es |
| escrito en espanol!} (es un nombre bastante largo, no?), but it is more |
| likely to be a mistake. |
| |
| @node Filename Functions,, Foreach Function, Functions |
| @section Functions for File Names |
| |
| Several of the built-in expansion functions relate specifically to |
| taking apart file names or lists of file names. |
| |
| Each of these functions performs a specific transformation on a file name. |
| The argument of the function is regarded as a series of file names, |
| separated by whitespace. (Leading and trailing whitespace is ignored.) |
| Each file name in the series is transformed in the same way and the results |
| are concatenated with single spaces between them. |
| |
| @table @code |
| @item $(dir @var{names}) |
| @findex dir |
| Extracts the directory-part of each file name in @var{names}. The |
| directory-part of the file name is everything up through (and |
| including) the last slash in it. If the file name contains no slash, |
| the directory part is the string @samp{./}. For example, |
| |
| @example |
| $(dir src/foo.c hacks) |
| @end example |
| |
| @noindent |
| produces the result @samp{src/ ./}. |
| |
| @item $(notdir @var{names}) |
| @findex notdir |
| Extracts all but the directory-part of each file name in @var{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 is unfortunate, |
| because it means that the result does not always have the same number |
| of whitespace-separated file names as the argument had; but we do not |
| see any other valid alternative. |
| |
| For example, |
| |
| @example |
| $(notdir src/foo.c hacks) |
| @end example |
| |
| @noindent |
| produces the result @samp{foo.c hacks}. |
| |
| @item $(suffix @var{names}) |
| @findex suffix |
| Extracts the suffix of each file name in @var{names}. If the file name |
| contains a period, the suffix is everything starting with the last |
| period. Otherwise, the suffix is the empty string. This frequently |
| means that the result will be empty when @var{names} is not, and if |
| @var{names} contains multiple file names, the result may contain fewer |
| file names. |
| |
| For example, |
| |
| @example |
| $(suffix src/foo.c hacks) |
| @end example |
| |
| @noindent |
| produces the result @samp{.c}. |
| |
| @item $(basename @var{names}) |
| @findex basename |
| Extracts all but the suffix of each file name in @var{names}. If the |
| file name contains a period, the basename is everything starting up to |
| (and not including) the last period. Otherwise, the basename is the |
| entire file name. For example, |
| |
| @example |
| $(basename src/foo.c hacks) |
| @end example |
| |
| @noindent |
| produces the result @samp{src/foo hacks}. |
| |
| @item $(addsuffix @var{suffix},@var{names}) |
| @findex addsuffix |
| The argument @var{names} is regarded as a series of names, separated |
| by whitespace; @var{suffix} is used as a unit. The value of |
| @var{suffix} is appended to the end of each individual name and the |
| resulting larger names are concatenated with single spaces between |
| them. For example, |
| |
| @example |
| $(addsuffix .c,foo bar) |
| @end example |
| |
| @noindent |
| produces the result @samp{foo.c bar.c}. |
| |
| @item $(addprefix @var{prefix},@var{names}) |
| @findex addprefix |
| The argument @var{names} is regarded as a series of names, separated |
| by whitespace; @var{prefix} is used as a unit. The value of |
| @var{prefix} is appended to the front of each individual name and the |
| resulting larger names are concatenated with single spaces between |
| them. For example, |
| |
| @example |
| $(addprefix src/,foo bar) |
| @end example |
| |
| @noindent |
| produces the result @samp{src/foo src/bar}. |
| |
| @item $(join @var{list1},@var{list2}) |
| @findex join |
| Concatenates the two arguments word by word: the two first words (one |
| from each argument) concatenated form the first word of the result, the |
| two second words form the second word of the result, and so on. So the |
| @var{n}th word of the result comes from the @var{n}th word of each |
| argument. If one argument has more words that the other, the extra |
| words are copied unchanged into the result. |
| |
| For example, @samp{$(join a b,.c .o)} produces @samp{a.c b.o}. |
| |
| Whitespace between the words in the lists is not preserved; it is |
| replaced with a single space. |
| |
| This function can reverse the effect of the @code{dir} and @code{notdir} |
| functions, after other processing has been done on the separated lists |
| of directories and files.@refill |
| |
| @item $(firstword @var{names}) |
| @findex firstword |
| The argument @var{names} is regarded as a series of names, separated |
| by whitespace. The value is the first name in the series. The rest |
| of the names are ignored. For example, |
| |
| @example |
| $(firstword foo bar) |
| @end example |
| |
| @noindent |
| produces the result @samp{foo}. |
| |
| @item $(wildcard @var{pattern}) |
| @findex wildcard |
| The argument @var{pattern} is a file name pattern, typically containing |
| wildcard characters. The result of @code{wildcard} is a space-separated |
| list of the names of existing files that match the pattern. |
| |
| Wildcards are expanded automatically in rules (@pxref{Wildcards}). |
| But they are not normally expanded when a variable is set, or inside the |
| arguments of other functions. Those occasions are when the @code{wildcard} |
| function is useful. |
| @end table |
| |
| @node Running, Implicit, Functions, Top |
| @chapter How to Run @code{make} |
| |
| A makefile that says how to recompile a program can be used in more than |
| one way. The simplest use is to recompile every file that is out of date. |
| This is what @code{make} will do if run with no arguments. |
| |
| But you might want to update only some of the files; you might want to use |
| a different compiler or different compiler options; you might want just to |
| find out which files are out of date without changing them. |
| |
| By specifying arguments when you run @code{make}, you can do any of these |
| things or many others. |
| |
| @menu |
| * Makefile Arguments:: Arguments to specify which makefile to use. |
| |
| * Goals:: Goal arguments specify which parts of the makefile |
| should be used. |
| |
| * Avoid Compilation:: How to avoid recompiling certain files. |
| |
| * Instead of Execution:: Mode flags specify what kind of thing to do |
| with the commands in the makefile |
| other than simply execute them. |
| |
| * Overriding:: Overriding a variable can specify an alternate |
| compiler, or alternate flags for the compiler, |
| or whatever else you program into the makefile. |
| |
| * Testing:: How to proceed past some errors, to test compilation. |
| |
| * Options:: Summary of all options @code{make} accepts. |
| @end menu |
| |
| @node Makefile Arguments, Goals, Running, Running |
| @section Arguments to Specify the Makefile |
| |
| The way to specify the name of the makefile is with the @samp{-f} option. |
| For example, @samp{-f altmake} says to use the file @file{altmake} as |
| the makefile. |
| |
| If you use the @samp{-f} flag several times (each time with a |
| following argument), all the specified files are used jointly as |
| makefiles. |
| |
| If you do not use the @samp{-f} flag, the default is to use |
| @file{./makefile}, or, if that does not exist, @file{./Makefile}. |
| @xref{Makefiles}.@refill |
| |
| @node Goals, Avoid Compilation, Makefile Arguments, Running |
| @section Goals |
| @cindex goal |
| |
| The @dfn{goals} are the targets that @code{make} should strive ultimately |
| to update. Other targets are updated as well if they appear as |
| dependencies of goals, or dependencies of dependencies of goals, etc. |
| |
| By default, the goal is the first target in the makefile (not counting |
| targets that start with a period or that appear in included makefiles). |
| Therefore, makefiles are usually written so that the first target is for |
| compiling the entire program or programs they describe. |
| |
| You can specify a different goal or goal with arguments to @code{make}. |
| Use the name of the goal as an argument. If you specify several goals, |
| @code{make} processes each of them in turn, in the order you name them. |
| |
| Any target in the makefile may be specified as a goal (unless it starts |
| with @samp{-} or contains an @samp{=}). Even targets not in the makefile |
| may be specified, if @code{make} can find implicit rules that say how to |
| make them. |
| |
| One use of specifying a goal is if you want to compile only a part of |
| the program, or only one of several programs. Specify as a goal each |
| file that you wish to remake. For example, consider a directory containing |
| a several programs, with a makefile that starts like this: |
| |
| @example |
| .PHONY: all |
| all: size nm ld ar as |
| @end example |
| |
| If you are working on the program @code{size}, you might want to say |
| @samp{make size} so that only the files of that program are recompiled. |
| |
| Another use of specifying a goal is to make files that aren't normally |
| made. For example, there may be a file of debugging output, or a version |
| of the program that is compiled specially for testing, which has a rule |
| in the makefile but isn't a dependency of the default goal. |
| |
| Another use of specifying a goal is to run the commands associated with a |
| phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty Targets}). |
| Many makefiles contain a phony target named @file{clean} which deletes |
| everything except source files. Naturally, this is done only if you |
| request it explicitly with @samp{make clean}. Here is a list of typical |
| phony and empty target names: |
| |
| @table @file |
| @item all |
| Make all the top-level targets the makefile knows about. |
| |
| @item clean |
| Delete all files that the makefile could remake. |
| |
| @item clobber |
| Delete absolutely everything the makefile could remake (whereas |
| @samp{make clean} often leaves intact some files that might take a |
| long time to remake). |
| |
| @item install |
| Copy the executable file into a directory that users typically search |
| for commands; copy any auxiliary files that the executable uses into |
| the directories where it will look for them. |
| |
| @item print |
| Print listings of the source files that have changed. |
| |
| @item tar |
| Create a tar file of the source files. |
| |
| @item shar |
| Create a shell archive (shar file) of the source files. |
| @end table |
| |
| @node Avoid Compilation, Instead of Execution, Goals, Running |
| @section Avoiding Recompilation of Some Files |
| @cindex -o |
| |
| Sometimes you may have changed a source file but you don't want to |
| recompile all the files that depend on it. For example, suppose you add a |
| macro or a declaration to a header file that many other files depend on. |
| Being conservative, @code{make} assumes that any change in the header file |
| requires recompilation of all dependent files, but you know that they don't |
| need to be recompiled and you would rather not waste the time waiting. |
| |
| If you anticipate the problem before making the change, you can use the |
| @samp{-t} flag. This flag tells @code{make} not to run the commands in the |
| rules, but rather to mark the target up to date by changing its |
| last-modification date. You would follow this procedure: |
| |
| @enumerate |
| @item |
| Use the command @samp{make} to recompile the source files that really |
| need recompilation. |
| |
| @item |
| Make the changes in the header files. |
| |
| @item |
| Use the command @samp{make -t} to mark all the object files as |
| up to date. The next time you run @code{make}, the changes in the |
| header files will not cause any recompilation. |
| @end enumerate |
| |
| If you have already changed the header file at a time when some files do |
| need recompilation, it is too late to do this. Instead, you can use the |
| @samp{-o @var{file}} flag, which marks a specified file as ``old'' |
| (@pxref{Options}). This means that the file itself won't be remade, |
| and nothing else will be remade on its account. Follow this procedure: |
| |
| @enumerate |
| @item |
| Recompile the source files that need compilation for reasons independent |
| of the particular header file, with @samp{make -o @var{headerfile}}. |
| If several header files are involved, use a separate @samp{-o} option |
| for each header file. |
| |
| @item |
| Touch all the object files with @samp{make -t}. |
| @end enumerate |
| |
| @node Instead of Execution, Overriding, Avoid Compilation, Running |
| @section Instead of Executing the Commands |
| @cindex -t |
| @cindex touch |
| @cindex -q |
| @cindex -n |
| |
| The makefile tells @code{make} how to tell whether a target is up to date, |
| and how to update each target. But updating the targets is not always |
| what you want. Certain options specify other activities for @code{make}. |
| |
| @table @samp |
| @item -t |
| ``Touch''. The activity is to mark the targets as up to date without |
| actually changing them. In other words, @code{make} pretends to compile |
| the targets but does not really change their contents. |
| |
| @item -n |
| ``No-op''. The activity is to print what commands would be used to make |
| the targets up to date, but not actually execute them. |
| |
| @item -q |
| ``Question''. The activity is to find out silently whether the targets |
| are up to date already; but execute no commands in either case. In other |
| words, neither compilation nor output will occur. |
| @end table |
| |
| With the @samp{-n} flag, @code{make} prints without execution the commands |
| that it would normally execute. |
| |
| With the @samp{-t} flag, @code{make} ignores the commands in the rules |
| and uses (in effect) the command @code{touch} for each target that needs to |
| be remade. The @code{touch} command is also printed, unless @samp{-s} or |
| @code{.SILENT} is used. For speed, @code{make} does not actually invoke |
| the program @code{touch}. It does the work directly. |
| |
| With the @samp{-q} flag, @code{make} prints nothing and executes no |
| commands, but the exit status code it returns is zero if and only if the |
| targets to be considered are already up to date. |
| |
| It is an error to use more than one of these three flags in the same |
| invocation of @code{make}. |
| |
| If you are not at all interested in what @code{make} @emph{would} do, |
| but rather in some other information about @code{make}, there are two |
| options: the command line @samp{make -p -f /dev/null} will print the |
| information in @code{make}'s database of variables, rules, directories |
| and files and @samp{make -v -f /dev/null} will print information about |
| what version of GNU @code{make} you are using. @xref{Options}.@refill |
| |
| @node Overriding, Testing, Instead of Execution, Running |
| @section Overriding Variables |
| |
| You can override the value of a variable using an argument to @code{make} |
| that contains a @samp{=}. The argument @samp{@var{v}=@var{x}} (or |
| @samp{@var{v}:=@var{x}}; @pxref{Flavors}) sets the value of the variable |
| @var{v} to @var{x}. |
| |
| Values specified this way override all values specified in the makefile |
| itself; once you have set a variable with a command argument, any ordinary |
| attempt in the makefile to change that variable is simply ignored. |
| |
| One way to use this facility is to pass extra flags to compilers. |
| For example, in a properly written makefile, the variable @code{CFLAGS} |
| is included in each command that runs the C compiler, so a file |
| @file{foo.c} would be compiled like this: |
| |
| @example |
| cc -c $(CFLAGS) foo.c |
| @end example |
| |
| Thus, whatever value you set for @code{CFLAGS} affects each compilation |
| that occurs. The makefile probably specifies the usual value for |
| @code{CFLAGS}, like this: |
| |
| @example |
| CFLAGS=-g |
| @end example |
| |
| Each time you run @code{make}, you can override this value and specify a |
| different value. For example, if you say @samp{make CFLAGS='-g -O'}, each |
| C compilation will be done with @samp{cc -c -g -O}. (This illustrates how |
| you can enclose spaces and other special characters in the value of a |
| variable when you override it.) |
| |
| The variable @code{CFLAGS} is only one of many standard variables that |
| exist just so that you can change them this way. |
| @xref{Implicit Variables}, for a complete list. |
| |
| You can also program the makefile to look at additional variables of your |
| own, giving the user ability to control other aspects of how the makefile |
| works by changing the variables. |
| |
| There is one way that the makefile can change a variable that you have |
| overridden. This is to use the @code{override} directive, which is a line |
| that looks like this: @samp{override @var{variable} = @var{value}}. |
| @xref{Override Directive}. |
| |
| @node Testing, Options, Overriding, Running |
| @section Testing the Compilation of a Program |
| |
| Normally, when an error happens in executing a shell command, @code{make} |
| gives up immediately, returning a nonzero status. No further commands are |
| executed for any target. The error implies that the goal cannot be |
| correctly remade, and @code{make} reports this as soon as it knows. |
| |
| When you are compiling a program that you have just changed, this is not |
| what you want. Instead, you would rather that @code{make} try compiling |
| every file that can be tried, to show you all the compilation errors. |
| |
| @cindex -k |
| On these occasions, you should use the @samp{-k} flag. This tells |
| @code{make} to continue to consider the other dependencies 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, |
| @samp{make -k} will continue compiling other object files even though it |
| already knows that linking them will be impossible. In addition to |
| contuing after failing shell commands, @samp{make -k} will continue as much |
| as possible after discovering that it doesn't know how to make a target or |
| dependency file. This will always cause an error message, but without |
| @samp{-k}, it is a fatal error. @xref{Options}. |
| |
| The usual behavior of @code{make} assumes that your purpose is to get the |
| goals up to date; once @code{make} learns that this is impossible, it might |
| as well report the failure immediately. The @samp{-k} flag says that the |
| real purpose is to test as much as possible of the changes made in the |
| program, perhaps to find several independent problems so that you can |
| correct them all before the next attempt to compile. This is why Emacs's |
| @code{compile} command passes the @samp{-k} flag by default. |
| |
| @node Options,, Testing, Running |
| @section Summary of Options |
| @cindex options |
| @cindex flags |
| |
| Here is a table of all the options @code{make} understands: |
| |
| @table @samp |
| @item -b |
| @itemx -m |
| These options are ignored for compatibility with other versions of @code{make}. |
| |
| @item -c @var{dir} |
| Change to directory @var{dir} before executing the rules. If multiple |
| @samp{-c} options are specified, each is interpreted relative to the |
| previous one: @samp{-c / -c etc} is equivalent to @samp{-c /etc}. |
| This is typically used with recursive invocations of @code{make} |
| (@pxref{Recursion}). |
| |
| @item -d |
| Print debugging information in addition to normal processing. The |
| debugging information says which files are being considered for |
| remaking, which file-times are being compared and with what results, |
| which files actually need to be remade, which implicit rules are |
| considered and which are applied---everything interesting about how |
| @code{make} decides what to do. |
| |
| @item -f @var{file} |
| Use file @var{file} as a makefile. @xref{Makefiles}. |
| |
| @item -i |
| Ignore all errors in commands executed to remake files. |
| @xref{Errors}. |
| |
| @item -I @var{dir} |
| Specifies a directory @var{dir} to search for included makefiles. |
| @xref{Include}. If several @samp{-I} options are used to specify |
| several directories, the directories are searched in the order |
| specified. |
| |
| @item -k |
| Continue as much as possible after an error. While the target that |
| failed, and those that depend on it, cannot be remade, the other |
| dependencies of these targets can be processed all the same. |
| @xref{Testing}. |
| |
| @item -n |
| Print the commands that would be executed, but do not execute them. |
| @xref{Instead of Execution}. |
| |
| @item -o @var{file} |
| Do not remake the file @var{file} even if it is older than its |
| dependencies, and do not remake anything on account of changes in |
| @var{file}. Essentially the file is treated as very old and its rules |
| are ignored. @xref{Avoid Compilation}. |
| |
| @item -p |
| Print the data base (rules and variable values) that results from |
| reading the makefiles; then execute as usual or as otherwise |
| specified. This also prints the version information given by |
| the @samp{-v} switch (see below). To print the data base without |
| trying to remake any files, use @samp{make -p -f /dev/null}. |
| |
| @item -q |
| ``Question mode''. Do not run any commands, or print anything; just |
| return an exit status that is zero if the specified targets are |
| already up to date, nonzero otherwise. @xref{Instead of Execution}. |
| |
| @item -r |
| Eliminate use of the built-in implicit rules (@pxref{Implicit}). |
| Also clear out the default list of suffixes for suffix rules |
| (@pxref{Suffix Rules}). |
| |
| @item -s |
| Silent operation; do not print the commands as they are executed. |
| @xref{Echoing}. |
| |
| @item -S |
| Cancel the effect of the @samp{-k} option. This is never necessary |
| except in a recursive @code{make} where @samp{-k} might be inherited |
| from the top-level @code{make} via @code{MAKEFLAGS} (@pxref{Recursion}) |
| or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill |
| |
| @item -t |
| Touch files (mark them up to date without really changing them) |
| instead of running their commands. This is used to pretend (to fool |
| future invocations of @code{make}) that the commands were done. |
| @xref{Instead of Execution}. |
| |
| @item -v |
| Print the version of the @code{make} program plus a copyright, |
| list of authors and notice of (non)warranty (short). |
| After this information is printed, processing continues normally. |
| To get the version information without doing anything else, |
| use @samp{make -v -f /dev/null}. |
| |
| @item -w |
| Print a message containing the working directory both before and after |
| executing the makefile; this is useful for tracking down errors from |
| builds of large directory trees. @xref{Recursion}. |
| @end table |
| |
| @node Implicit, Archives, Running, Top |
| @chapter Using Implicit Rules |
| @cindex implicit rule |
| |
| Certain standard ways of remaking target files are used very often. For |
| example, one customary way to make an object file is from a C source file |
| using the C compiler, @code{cc}. |
| |
| @dfn{Implicit rules} tell @code{make} how to use customary techniques so |
| that you don't have to specify them in detail when you want to use them. |
| For example, there is an implicit rule for C compilation. |
| |
| Implicit rules work based on file names. For example, C compilation typically |
| takes a @file{.c} file and makes a @file{.o} file. So @code{make} applies |
| the implicit rule when it sees this combination of file-name endings. |
| |
| A chain of implicit rules can apply in sequence; for example, @code{make} |
| will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file. |
| @iftex |
| @xref{Chained Rules}. |
| @end iftex |
| |
| The built-in implicit rules use several variables in their commands so |
| that, by changing the values of the variables, you can change the way the |
| implicit rule works. For example, the variable @code{CFLAGS} controls the |
| flags given to the C compiler by the implicit rule for C compilation. |
| @iftex |
| @xref{Implicit Variables}. |
| @end iftex |
| |
| You can define your own implicit rules by writing @dfn{pattern rules}. |
| @iftex |
| @xref{Pattern Rules}. |
| @end iftex |
| |
| @menu |
| * Using Implicit:: How to use an existing implicit rule |
| to get the commands for updating a file. |
| |
| * Catalogue of Rules:: Catalogue of built-in implicit rules. |
| |
| * Implicit Variables:: By changing certain variables, you can |
| change what the predefined implicit rules do. |
| |
| * Chained Rules:: Using a chain of implicit rules. |
| |
| * Pattern Rules:: Defining new implicit rules. |
| |
| * Search Algorithm:: Precise algorithm for applying implicit rules. |
| @end menu |
| |
| @node Using Implicit, Catalogue of Rules, Implicit, Implicit |
| @section Using Implicit Rules |
| |
| To allow @code{make} to find a customary method for updating a target file, |
| all you have to do is refrain from specifying commands yourself. Either |
| write a rule with no command lines, or don't write a rule at all. Then |
| @code{make} will figure out which implicit rule to use based on which |
| kind of source file exists. |
| |
| For example, suppose the makefile looks like this: |
| |
| @example |
| foo : foo.o bar.o |
| cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS) |
| @end example |
| |
| @noindent |
| Because you mention @file{foo.o} but do not give a rule for it, @code{make} |
| will automatically look for an implicit rule that tells how to update it. |
| This happens whether or not the file @file{foo.o} currently exists. |
| |
| If an implicit rule is found, it supplies both commands and a dependency |
| (the source file). You would want to write a rule for @file{foo.o} with no |
| command lines if you need to specify additional dependencies, such as |
| header files, that the implicit rule cannot supply. |
| |
| Each implicit rule has a target pattern and dependency patterns. There may |
| be many implicit rules with the same target pattern. For example, numerous |
| rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler; |
| another, from a @samp{.p} file with the Pascal compiler; and so on. The rule |
| that actually applies is the one whose dependency exists or can be made. |
| |
| So, if you have a file @file{foo.c}, @code{make} will run the C compiler; |
| otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal |
| compiler; and so on. |
| |
| Of course, when you write the makefile, you know which implicit rule you |
| want @code{make} to use, and you know it will choose that one because you |
| know which other files are supposed to exist. @xref{Catalogue of Rules}, |
| for a catalogue of all the predefined implicit rules. |
| |
| Above, we said an implicit rule applies if the required dependency ``exists |
| or can be made''. A file ``can be made'' if it is mentioned explicitly in |
| the makefile as a target or a dependency, or if an implicit rule can be |
| recursively found for how to make it. When the implicit dependency is the |
| result of another implicit rule, we say that @dfn{chaining} is occurring. |
| @xref{Chained Rules}. |
| |
| In general, @code{make} searches for an implicit rule for each target, and |
| for each double-colon rule, that has no commands. A file that is mentioned |
| only as a dependency is considered a target whose rule specifies nothing, |
| so implicit rule search happens for it. @xref{Search Algorithm}, for the |
| details of how the search is done. |
| |
| @node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit |
| @section Catalogue of Implicit Rules |
| |
| Here is a catalogue of predefined implicit rules which are always available |
| unless the makefile explicitly overrides or cancels them. |
| (@xref{Canceling Rules}, for information on canceling or overriding an |
| implicit rule. The @samp{-r} option cancels all predefined rules.) |
| |
| @table @asis |
| @item Compiling C programs |
| @file{@var{n}.o} will be made automatically from @file{@var{n}.c} |
| with the command @samp{$(CC) -c $(CFLAGS)}.@refill |
| |
| @item Compiling Pascal programs |
| @file{@var{n}.o} will be made automatically from @file{@var{n}.p} |
| with the command @samp{$(PC) -c $(PFLAGS)}.@refill |
| |
| @item Compiling Fortran, EFL and Ratfor programs |
| @file{@var{n}.o} will be made automatically from @file{@var{n}.e}, |
| @file{@var{n}.r}, @file{@var{n}.F} or @file{@var{n}.f} by running the |
| Fortran compiler. The precise command used is as follows:@refill |
| |
| @table @code |
| @item .e |
| @samp{$(FC) -c $(EFLAGS)}. |
| @item .f |
| @samp{$(FC) -c $(FFLAGS)}. |
| @item .F |
| @samp{$(FC) -c $(FFLAGS)}. |
| @item .r |
| @samp{$(FC) -c $(RFLAGS)}. |
| @end table |
| |
| @item Preprocessing Fortran, EFL and Ratfor programs |
| @file{@var{n}.f} will be made automatically from @file{@var{n}.e}, |
| @file{@var{n}.r} or @file{@var{n}.F}. This rule runs just the |
| preprocessor to convert a Ratfor, EFL or preprocessable Fortran |
| program into a strict Fortran program. The precise command used is as |
| follows:@refill |
| |
| @table @code |
| @item .e |
| @samp{$(FC) -F $(EFLAGS)}. |
| @item .F |
| @samp{$(FC) -F $(FFLAGS)}. |
| @item .r |
| @samp{$(FC) -F $(RFLAGS)}. |
| @end table |
| |
| @item Assembling assembler programs |
| @file{@var{n}.o} will be made automatically from @file{@var{n}.s} by |
| running the assembler @code{as}. The precise command used is |
| @samp{$(AS) $(ASFLAGS)}.@refill |
| |
| @item Linking a single object file |
| @file{@var{n}} will be made automatically from @file{@var{n}.o} by |
| running the linker @code{ld} via the C compiler. The precise command |
| used is @samp{$(CC) $(LDFLAGS) @dots{} $(LOADLIBES)}.@refill |
| |
| This rule does the right thing for a simple program with only one source |
| file. It will also do the right thing if there are multiple object files |
| (presumably coming from various other source files), the first of which has |
| a name matching that of the executable file. Thus, |
| |
| @example |
| x: y.o z.o |
| @end example |
| |
| @noindent |
| when @file{x.c}, @file{y.c} and @file{z.c} all exist will execute: |
| |
| @example |
| 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 |
| @end example |
| |
| @noindent |
| In more complicated cases, you must write an explicit command for linking. |
| |
| @item Yacc for C programs |
| @file{@var{n}.c} will be made automatically from @file{@var{n}.y} by |
| running Yacc with the command @samp{$(YACC) $(YFLAGS)}. |
| |
| @item Yacc for Ratfor programs |
| @file{@var{n}.r} will be made automatically from @file{@var{n}.yr} by |
| running Yacc with the command @samp{$(YACCR) $(YFLAGS)}. |
| |
| @item Yacc for EFL programs |
| @file{@var{n}.e} will be made automatically from @file{@var{n}.ye} by |
| running Yacc with the command @samp{$(YACCE) $(YFLAGS)}. |
| |
| @item Lex for C programs |
| @file{@var{n}.c} will be made automatically from @file{@var{n}.l} by |
| by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}. |
| |
| @item Lex for Ratfor programs |
| @file{@var{n}.r} will be made automatically from @file{@var{n}.l} by |
| by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}. |
| |
| The traditional custom of using the same suffix @samp{.l} for all Lex |
| files regardless of whether they produce C code or Ratfor code makes |
| it impossible for @code{make} to determine automatically which of the |
| two languages you are using in any particular case. If @code{make} is |
| called upon to remake an object file from a @samp{.l} file, it must |
| guess which compiler to use. It will guess the C compiler, because |
| that is more common. If you are using Ratfor, make sure @code{make} |
| knows this by mentioning @file{@var{n}.r} in the makefile. |
| |
| @item RCS |
| Any file @file{@var{n}} will be extracted if necessary from an RCS |
| file named either @file{@var{n},v} or @file{RCS/@var{n},v}. The |
| precise command used is @samp{$(CO) $(COFLAGS)}. The variable |
| @code{CO} has default value @samp{co}. |
| |
| @item SCCS |
| Any file @file{@var{n}} will be extracted if necessary from an SCCS |
| file named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}. The |
| precise command used is @samp{$(GET) $(GFLAGS)}. |
| |
| We recommend that you avoid the use of SCCS. RCS is widely held to be |
| superior, and is also free. By choosing free software in place of |
| comparable (or lesser) proprietary software, you support the free software |
| movement. |
| @end table |
| |
| @node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit |
| @section Variables Used by Implicit Rules |
| @cindex flags for compilers |
| |
| The commands in built-in implicit rules make liberal use of certain |
| predefined variables. You can redefine these variables, either in the |
| makefile or with arguments to @code{make}, to alter how the implicit rules |
| work without actually redefining them. |
| |
| For example, the command used to compile a C source file actually says |
| @samp{$(CC) -c $(CFLAGS)}. The default values of the variables used |
| are @samp{cc} and nothing, resulting in the command @samp{cc -c}. By |
| redefining @samp{$(CC)} to @samp{ncc}, you could cause @samp{ncc} to |
| be used for all C compilations performed by the implicit rule. By |
| redefining @samp{$(CFLAGS)} to be @samp{-g}, you could pass the |
| @samp{-g} option to each compilation. @emph{All} implicit rules that |
| do C compilation use @samp{$(CC)} to get the program name for the |
| compiler and @emph{all} include @samp{$(CFLAGS)} among the arguments |
| given to the compiler.@refill |
| |
| The variables used in implicit rules fall into two classes: those that are |
| names of programs (like @code{CC}) and those that contain arguments for the |
| programs (like @code{CFLAGS}). (The ``name of a program'' may also contain |
| some command arguments, but it must start with an actual executable program |
| name.) If a variable value contains more than one argument, separate them |
| with spaces. |
| |
| Here is a table of variables used as names of programs: |
| |
| @table @code |
| @item AS |
| @vindex AS |
| Program for doing assembly; default @samp{as}. |
| |
| @item CC |
| @vindex CC |
| Program for compiling C programs; default @samp{cc}. |
| |
| @item CO |
| @vindex CO |
| Program for extracting a file from RCS; default @samp{co}. |
| |
| @item FC |
| @vindex FC |
| Program for compiling or preprocessing Fortran, Ratfor, |
| and EFL programs; default @samp{f77}. |
| |
| @item GET |
| @vindex GET |
| Program for extracting a file from SCCS; default @samp{get}. |
| |
| @item LEX |
| @vindex LEX |
| Program to use to turn Lex grammars into C programs or Ratfor programs; |
| default @samp{lex}. |
| |
| @item PC |
| @vindex PC |
| Program for compiling Pascal programs; default @samp{pc}. |
| |
| @item YACC |
| @vindex YACC |
| Program to use to turn Yacc grammars into C programs; default @samp{yacc}. |
| |
| @item YACCR |
| @vindex YACCR |
| Program to use to turn Yacc grammars into Ratfor |
| programs; default @samp{yacc -r}. |
| |
| @item YACCE |
| @vindex YACCE |
| Program to use to turn Yacc grammars into EFL |
| programs; default @samp{yacc -e}. |
| |
| @item RANLIB |
| @vindex RANLIB |
| Program to use to update the symbol-directory of an archive |
| (the @file{__.SYMDEF} member); default @samp{ranlib}. |
| @end table |
| |
| Here is a table of variables whose values are additional arguments for the |
| programs above. The default values for all of these is the empty string. |
| |
| @table @code |
| @item ASFLAGS |
| @vindex ASFLAGS |
| Extra flags to give to the assembler (when explicitly |
| invoked on a @samp{.s} file). |
| |
| @item CFLAGS |
| @vindex CFLAGS |
| Extra flags to give to the C compiler. |
| |
| @item EFLAGS |
| @vindex EFLAGS |
| Extra flags to give to the Fortran compiler for EFL programs. |
| |
| @item FFLAGS |
| @vindex FFLAGS |
| Extra flags to give to the Fortran compiler. |
| |
| @item LFLAGS |
| @vindex LFLAGS |
| Extra flags to give to Lex. |
| |
| @item LDFLAGS |
| @vindex LDFLAGS |
| Extra flags to give to compilers when they are supposed to invoke the |
| linker, @samp{ld} (actually the value of the variable @code{LD}). |
| |
| @item PFLAGS |
| @vindex PFLAGS |
| Extra flags to give to the Pascal compiler. |
| |
| @item RFLAGS |
| @vindex RFLAGS |
| Extra flags to give to the Fortran compiler for Ratfor programs. |
| |
| @item YFLAGS |
| @vindex YFLAGS |
| Extra flags to give to Yacc. |
| @end table |
| |
| @node Chained Rules, Pattern Rules, Implicit Variables, Implicit |
| @section Chains of Implicit Rules |
| |
| @cindex chains of rules |
| Sometimes a file can be made by a sequence of implicit rules. For example, |
| a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running |
| first Yacc and then @code{cc}. Such a sequence is called a @dfn{chain}. |
| |
| If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no |
| special searching is required: @code{make} finds that the object file can |
| be made by C compilation from @file{@var{n}.c}; later on, when considering |
| how to make @file{@var{n}.c}, the rule for running Yacc will be |
| used. Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are |
| updated.@refill |
| |
| @cindex intermediate file |
| However, even if @file{@var{n}.c} does not exist and is not mentioned, |
| @code{make} knows how to envision it as the missing link between |
| @file{@var{n}.o} and @file{@var{n}.y}! In this case, @file{@var{n}.c} is |
| called an @dfn{intermediate file}. Once @code{make} has decided to use the |
| intermediate file, it is entered in the data base as if it had been |
| mentioned in the makefile, along with the implicit rule that says how to |
| create it.@refill |
| |
| Intermediate files are remade using their rules just like all other |
| files. The difference is that the intermediate file is deleted when |
| @code{make} is finished. Therefore, the intermediate file which did |
| not exist before @code{make} also does not exist after @code{make}. |
| The deletion is reported to you by printing a @samp{rm -f} command |
| that shows what @code{make} is doing. (You can optionally define an |
| implicit rule so as to preserve certain intermediate files. You can also |
| list the target pattern of an implicit rule (such as @samp{%.o}) as a |
| dependency file of the special target @code{.PRECIOUS} to preserve intermediate |
| files whose target patterns match that file's name.)@refill |
| |
| A chain can involve more than two implicit rules. For example, it is |
| possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS, |
| Yacc and @code{cc}. Then both @file{foo.y} and @file{foo.c} are |
| intermediate files that are deleted at the end.@refill |
| |
| No single implicit rule can appear more than once in a chain. This means |
| that @code{make} will not even consider such a ridiculous thing as making |
| @file{foo} from @file{foo.o.o} by running the linker twice. This |
| constraint has the added benefit of preventing any infinite loop in the |
| search for an implicit rule chain. |
| |
| There are some special implicit rules to optimize certain cases that would |
| otherwise by handled by rule chains. For example, making @file{foo} from |
| @file{foo.c} could be handled by compiling and linking with separate rules, |
| using @file{foo.o} as an intermediate file. But what actually happens is |
| that a special rule for this case does the compilation and linking with a |
| single @code{cc} command. The optimized rule is used in preference to the |
| step-by-step chain because it comes earlier in the ordering of rules. |
| |
| @node Pattern Rules, Last Resort, Chained Rules, Implicit |
| @section Defining and Redefining Pattern Rules |
| |
| @cindex pattern rule |
| You define an implicit rule by writing a @dfn{pattern rule}. A pattern |
| rule looks like an ordinary rule, except that its target contains the |
| character @samp{%} (exactly one of them). The target is considered a |
| pattern for matching file names; the @samp{%} can match any substring, |
| while other characters match only themselves. |
| |
| For example, @samp{%.c} as a pattern matches any file name that ends in |
| @samp{.c}. @samp{s.%.c} as a pattern matches any file name that starts |
| with @samp{s.}, ends in @samp{.c} and is at least five characters long. |
| (There must be at least one character to match the @samp{%}.) The substring |
| that the @samp{%} matches is called the @dfn{stem}.@refill |
| |
| A pattern rule must have at least one dependency that uses @samp{%}. |
| @samp{%} in a dependency of a pattern rule stands for the same stem |
| that was matched by the @samp{%} in the target. In order for |
| the pattern rule to apply, its target pattern must match the file name |
| under consideration, and its dependency patterns must name files that |
| exist or can be made. These files become dependencies of the target. |
| |
| There may also be dependencies that do not use @samp{%}; such a dependency |
| attaches to every file made by this pattern rule. These unvarying |
| dependencies are rarely useful. |
| |
| The order in which pattern rules appear in the makefile is important |
| because the rules are considered in that order. Of equally applicable |
| rules, the first one found is used. The rules you write take precedence |
| over those that are built in. Note, however, that a rule whose |
| dependencies actually exist or are mentioned always takes priority over a |
| rule with dependencies that must be made by chaining other implicit rules. |
| |
| @menu |
| * Examples: Pattern Examples. Real examples of pattern rule definitions. |
| |
| * Vars: Automatic. The automatic variables enable the commands |
| in pattern rules to act on the right files. |
| |
| * Matching: Pattern Match. Details of how patterns match. |
| |
| * Match-Anything Rules:: Precautions in defining a rules that can |
| match any target file whatever. |
| |
| * Canceling Rules:: Overriding or canceling built-in rules. |
| |
| * Last Resort:: How to define a last-resort rule |
| that applies to any target that no other |
| rule applies to. |
| |
| * Suffix Rules:: The old-fashioned way to define implicit rules. |
| @end menu |
| |
| @node Pattern Examples, Automatic, Pattern Rules, Pattern Rules |
| @subsection Pattern Rule Examples |
| |
| Here are some examples of pattern rules actually predefined in |
| @code{make}. First, the rule that compiles @samp{.c} files into @samp{.o} |
| files:@refill |
| |
| @example |
| %.o : %.c |
| $(CC) -c $(CFLAGS) $< -o $@@ |
| @end example |
| |
| @noindent |
| defines a rule that can make any file @file{@var{x}.o} from |
| @file{@var{x}.c}. The command uses the automatic variables @samp{$@@} and |
| @samp{$<} to substitute the names of the target file and the source file |
| as they are in each case where the rule apply (@pxref{Automatic}).@refill |
| |
| Here is a second built-in rule: |
| |
| @example |
| % :: RCS/%,v |
| $(CO) $(COFLAGS) $< |
| @end example |
| |
| @noindent |
| defines a rule that can make any file @file{@var{x}} whatever from a |
| corresponding file @file{@var{x},v} in the subdirectory @file{RCS}. Since |
| the target is @samp{%}, this rule will apply to any file whatever, provided |
| the appropriate dependency file exists. The double colon makes the rule |
| @dfn{terminal}, which means that its dependency may not be an intermediate |
| file (@pxref{Match-Anything Rules}).@refill |
| |
| @node Automatic, Pattern Match, Pattern Examples, Pattern Rules |
| @subsection Automatic Variables |
| @cindex automatic variables |
| |
| Suppose you are writing a pattern rule to compile a @samp{.c} file into a |
| @samp{.o} file: how do you write the @samp{cc} command so that it operates |
| on the right source file name? You can't write the name in the command, |
| because the name is different each time the implicit rule is applied. |
| |
| What you do is use a special feature of @code{make}, the @dfn{automatic |
| variables}. These variables have values computed afresh for each rule that |
| is executed, based on the target and dependencies of the rule. In this |
| example, you would use @samp{$@@} for the object file name and @samp{$<} |
| for the source file name. |
| |
| Here is a table of automatic variables: |
| |
| @table @code |
| @item $@@ |
| The file name of the target of the rule. If the target is an archive |
| member, then @samp{$@@} is the name of the archive file. |
| |
| @item $% |
| The target member name, when the target is an archive member. For |
| example, if the target is @file{foo.a(bar.o)} then @samp{$%} is |
| @file{bar.o} and @samp{$@@} is @file{foo.a}. @samp{$%} is empty |
| when the target is not an archive member. |
| |
| @item $< |
| The name of the first dependency. |
| |
| @item $? |
| The names of all the dependencies that are newer than the target, with |
| spaces between them. |
| |
| @item $^ |
| The names of all the dependencies, with spaces between them. |
| |
| @item $* |
| The stem with which an implicit rule matches (@pxref{Pattern Match}). |
| If the target is @file{dir/a.foo.b} and the target pattern is |
| @file{a.%.b} then the stem is @file{dir/foo}. The stem is useful for |
| constructing names of related files.@refill |
| @end table |
| |
| @samp{$?} is useful even in explicit rules when you wish to operate on only |
| the dependencies that have changed. For example, suppose that an archive |
| named @file{lib} is supposed to contain copies of several object files. |
| This rule copies just the changed object files into the archive: |
| |
| @example |
| lib: foo.o bar.o lose.o win.o |
| ar c lib $? |
| @end example |
| |
| Of the variables listed above, four have values that are single file names. |
| These four have variants that get just the file's directory name or just |
| the file name within the directory. The variant variables' names are |
| formed by appending @samp{D} or @samp{F}, respectively. These variants are |
| semi-obsolete in GNU @code{make} since the functions @code{dir} and |
| @code{notdir} can be used to get an equivalent effect (@pxref{Filename |
| Functions}). Here is a table of the variants:@refill |
| |
| @table @samp |
| @item $(@@D) |
| The directory part of the file name of the target. If the value of |
| @samp{$@@} is @file{dir/foo.o} then @samp{$(@@D)} is @file{dir/}. |
| This value is @file{./} if @samp{$@@} does not contain a slash. |
| @samp{$(@@D)} is equivalent to @samp{$(dir $@@)}.@refill |
| |
| @item $(@@F) |
| The file-within-directory part of the file name of the target. If the |
| value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is |
| @file{foo.o}. @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}. |
| |
| @item $($/) |
| The same as @code{$(@@F)}, for compatibility with some other versions |
| of @code{make}. |
| |
| @item $(%D) |
| @itemx $(%F) |
| The directory part and the file-within-directory part of the archive |
| member name. |
| |
| @item $(*D) |
| @itemx $(*F) |
| The directory part and the file-within-directory part of the stem; |
| @file{dir/} in this example. |
| |
| @item $(<D) |
| @itemx $(<F) |
| The directory part and the file-within-directory part of the first |
| implicit dependency. |
| @end table |
| |
| @node Pattern Match, Match-Anything Rules, Automatic, Pattern Rules |
| @subsection How Patterns Match |
| |
| @cindex stem |
| A target pattern is composed of a @samp{%} between a prefix and a suffix, |
| either of which may be empty. The pattern matches a file name only if the |
| file name starts with the prefix and ends with the suffix, without overlap. |
| The text between the prefix and the suffix is called the @dfn{stem}. Thus, |
| when the pattern @samp{%.o} matches the file name @file{test.o}, the stem |
| is @samp{test}. The pattern rule dependencies are turned into actual file |
| names by substituting the stem for the character @samp{%}. Thus, if in the |
| same example one of the dependencies is written as @samp{%.c}, it expands |
| to @samp{test.c}.@refill |
| |
| When the target pattern does not contain a slash (and usually it does not), |
| directory names in the file names are removed from the file name before it |
| is compared with the target prefix and suffix. The directory names, along |
| with the slash that ends them, are added back to the stem. Thus, |
| @samp{e%t} does match the file name @file{src/eat}, with @samp{src/a} as |
| the stem. When dependencies are turned into file names, the directories |
| from the stem are added at the front, while the rest of the stem is |
| substituted for the @samp{%}. The stem @samp{src/a} with a dependency |
| pattern @samp{c%r} gives the file name @file{src/car}.@refill |
| |
| @node Match-Anything Rules, Canceling Rules, Pattern Match, Pattern Rules |
| @subsection Match-Anything Pattern Rules |
| |
| @cindex match-anything rule |
| @cindex terminal rule |
| When a pattern rule's target is just @samp{%}, it matches any filename |
| whatever. We call these rules @dfn{match-anything} rules. They are very |
| useful, but it can take a lot of time for @code{make} to think about them, |
| because it must consider every such rule for each file name listed either |
| as a target or as a dependency. |
| |
| Suppose the makefile mentions @file{foo.c}. For this target, @code{make} |
| would have to consider making it by linking an object file @file{foo.c.o}, |
| or by C compilation-and-linking in one step from @file{foo.c.c}, or by |
| Pascal compilation-and-linking from @file{foo.c.p}, and many other |
| possibilities. We know these possibilities are ridiculous since |
| @file{foo.c} is a C source file, not an executable.@refill |
| |
| If @code{make} did consider these possibilities, it would ultimately reject |
| them, because files such as @file{foo.c.o}, @file{foo.c.p}, etc. would not |
| exist. But these possibilities are so numerous that @code{make} would run |
| very slowly if it had to consider them.@refill |
| |
| To gain speed, we have put various constraints on the way @code{make} |
| considers match-anything rules. There are two different constraints that |
| can be applied, and each time you define a match-anything rule you must |
| choose one or the other for that rule. |
| |
| One choice is to mark the match-anything rule as @dfn{terminal} by defining |
| it with a double colon. When a rule is terminal, it does not apply |
| unless its dependencies actually exist. Dependencies that could be made |
| with other implicit rules are not good enough. |
| |
| For example, the built-in implicit rules for extracting sources from RCS |
| and SCCS files are terminal; as a result, if the file @file{foo.c,v} does |
| not exist, @code{make} will not even consider trying to make it as an |
| intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}. |
| RCS and SCCS files are generally ultimate source files, which should not be |
| remade from any other files; therefore, @code{make} can save time by not |
| looking for ways to remake them.@refill |
| |
| If you do not mark the match-anything rule as terminal, then it is |
| nonterminal. A nonterminal match-anything rule cannot apply to a file name |
| that indicates a specific type of data. A file name indicates a specific |
| type of data if some non-match-anything implicit rule target matches it. |
| |
| For example, the file name @file{foo.c} matches the target for the pattern |
| rule @samp{%.c : %.y} (the rule to run Yacc). Regardless of whether this |
| rule is actually applicable (which happens only if there is a file |
| @file{foo.y}), the fact that its target matches is enough to prevent |
| consideration of any nonterminal match-everything rules for the file |
| @file{foo.c}. Thus, @code{make} will not even consider trying to make |
| @file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c}, |
| @file{foo.c.p}, etc.@refill |
| |
| The motivation for this constraint is that nonterminal match-everything |
| rules are used for making files containing specific types of data (such as |
| executable files) and a file name with a recognized suffix indicates a |
| specific different type of data (such as a C source file). |
| |
| Special built-in dummy pattern rules are provided solely to recognize |
| certain file names so that nonterminal match-everything rules won't be |
| considered. These dummy rules have no dependencies and no commands, and |
| they are ignored for all other purposes. For example, the built-in |
| implicit rule |
| |
| @example |
| %.p : |
| @end example |
| |
| @noindent |
| exists to make sure that Pascal source files such as @file{foo.p} match a |
| specific target pattern and thereby prevent time from being wasted looking |
| for @file{foo.p.o} or @file{foo.p.c}. |
| |
| @node Canceling Rules,, Match-Anything Rules, Pattern Rules |
| @subsection Canceling Implicit Rules |
| |
| You can override a built-in implicit rule by defining a new pattern rule |
| with the same target and dependencies, but different commands. When the |
| new rule is defined, the built-in one is replaced. The new rule's position |
| in the sequence of implicit rules is determined by where you write the new |
| rule. |
| |
| You can cancel a built-in implicit rule by defining a pattern rule with the |
| same target and dependencies, but no commands. For example, the following |
| would cancel the rule that runs the assembler: |
| |
| @example |
| %.o : %.s |
| @end example |
| |
| @node Last Resort, Suffix Rules, Pattern Rules, Implicit |
| @section Defining Last-Resort Default Rules |
| |
| @findex .DEFAULT |
| You can define a last-resort implicit rule by writing a rule for the target |
| @code{.DEFAULT}. Such a rule's commands are used for all targets and |
| dependencies that have no commands of their own and for which no other |
| implicit rule applies. Naturally, there is no @code{.DEFAULT} rule unless |
| you write one. |
| |
| For example, when testing a makefile, you might not care if the source |
| files contain real data, only that they exist. Then you might do this: |
| |
| @example |
| .DEFAULT: |
| touch $@@ |
| @end example |
| |
| @noindent |
| to cause all the source files needed (as dependencies) to be created |
| silently. |
| |
| @node Suffix Rules, Search Algorithm, Last Resort, Implicit |
| @section Old-Fashioned Suffix Rules |
| @cindex suffix rules |
| |
| @dfn{Suffix rules} are the old-fashioned way of defining implicit rules for |
| @code{make}. Suffix rules are obsolete because pattern rules are more |
| general and clearer. They are supported in GNU @code{make} for |
| compatibility with old makefiles. They come in two kinds: |
| @dfn{double-suffix} and @dfn{single-suffix}.@refill |
| |
| A double-suffix rule is defined by a pair of suffixes: the target suffix |
| and the source suffix. It matches any file whose name ends with the target |
| suffix. The corresponding implicit dependency is to the file name made by |
| replacing the target suffix with the source suffix. A two-suffix rule |
| whose target and source suffixes are @samp{.o} and @samp{.c} is equivalent |
| to the pattern rule @samp{%.o : %.c}. |
| |
| A single-suffix rule is defined by a single suffix, which is the source |
| suffix. It matches any file name, and the corresponding implicit |
| dependency name is made by appending the source suffix. A single-suffix |
| rule whose source suffix is @samp{.c} is equivalent to the pattern rule |
| @samp{% : %.c}. |
| |
| Suffix rule definitions are recognized by comparing each rule's target |
| against a defined list of known suffixes. When @code{make} sees a rule |
| whose target is a known suffix, this rule is considered a single-suffix |
| rule. When @code{make} sees a rule whose target is two known suffixes |
| concatenated, this rule is taken as a double-suffix rule. |
| |
| For example, @samp{.c} and @samp{.o} are both on the default list of known |
| suffixes. Therefore, if you define a rule whose target is @samp{.c.o}, |
| @code{make} takes it to be a double-suffix rule with source suffix |
| @samp{.c} and target suffix @samp{.o}. For example, here is the old |
| fashioned way to define the rule for compiling a C source:@refill |
| |
| @example |
| .c.o: |
| $(CC) -c $(CFLAGS) -o $@@ $< |
| @end example |
| |
| @findex .SUFFIXES |
| The known suffixes are simply the names of the dependencies of the special |
| target @code{.SUFFIXES}. You can add your own suffixes by writing a rule |
| for @code{.SUFFIXES} that adds more dependencies, as in |
| |
| @example |
| .SUFFIXES: .hack .win |
| @end example |
| |
| @noindent |
| which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes. |
| |
| If you wish to eliminate the default known suffixes instead of just adding |
| to them, write a rule for @code{.SUFFIXES} with no dependencies. By |
| special dispensation, this eliminates all existing dependencies of |
| @code{.SUFFIXES}. You can then write another rule to add the suffixes you |
| want. For example, |
| |
| @example |
| .SUFFIXES: # @r{Delete the default suffixes} |
| .SUFFIXES: .c .o .h # @r{Define our suffix list} |
| @end example |
| |
| The @samp{-r} flag causes the default list of suffixes to be empty. |
| |
| @node Search Algorithm,, Last Resort, Implicit |
| @section Implicit Rule Search Algorithm |
| |
| Here is the procedure @code{make} uses for searching for an implicit rule |
| for a target @var{t}. This procedure is followed for each double-colon |
| rule with no commands, for each target of ordinary rules none of which have |
| commands, and for each dependency that is not the target of any rule. It |
| is also followed recursively for dependencies that come from implicit |
| rules, in the search for a chain of rules. |
| |
| Suffix rules are not mentioned in this algorithm because suffix rules are |
| converted to equivalent pattern rules after the makefiles have been read |
| in. |
| |
| For an archive member target of the form |
| @samp{@var{archive}(@var{member})}, the following algorithm is run twice, |
| first using @samp{(@var{member})} as the target @var{t}, and second using |
| the entire target if the first run found no rule.@refill |
| |
| @enumerate |
| @item |
| Split @var{t} into a directory part, called @var{d}, and the rest, |
| called @var{n}. For example, if @var{t} is @samp{src/foo.o}, then |
| @var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill |
| |
| @item |
| Make a list of the pattern rules whose target matches @var{t} or |
| @var{n}. If the target pattern contains a slash, it is matched |
| against @var{t}; otherwise, against @var{n}. |
| |
| @item |
| If any rule in that list is @emph{not} a match-anything rule, then |
| remove all nonterminal match-anything rules from the list. |
| |
| @item |
| Remove any rules with no dependencies from the list. |
| |
| @item |
| For each pattern rule in the list: |
| |
| @enumerate |
| @item |
| Find the stem @var{s}: the part of @var{t} or @var{n} that the |
| @samp{%} in the target pattern matches.@refill |
| |
| @item |
| Compute the dependency names by substituting @var{s} for @samp{%}; if |
| the target pattern does not contain a slash, @var{d} is appended to |
| the front of each dependency name. |
| |
| @item |
| Test whether all the dependencies exist or ought to exist. (If a |
| file name mentioned in the makefile as a target or as an explicit |
| dependency then we say it ought to exist.) |
| |
| If all dependencies exist or ought to exist, then this rule applies. |
| @end enumerate |
| |
| @item |
| If no pattern rule has been found so far, try harder. For |
| each pattern rule in the list: |
| |
| @enumerate |
| @item |
| If the rule is a terminal match-anything rule, ignore it and go |
| on to the next rule. |
| |
| @item |
| Compute the dependency names as before. |
| |
| @item |
| Test whether all the dependencies exist or ought to exist. |
| |
| @item |
| For each dependency that does not exist, follow this algorithm |
| recursively to see if the dependency can be made by an implicit |
| rule. |
| |
| @item |
| If all dependencies exist, ought to exist, or can be made by |
| implicit rules, then this rule applies. |
| @end enumerate |
| |
| @item |
| If no rule has been found so far, this target cannot be made by an |
| implicit rule. Return failure. |
| |
| @item |
| If no implicit rule applies, the rule for @code{.DEFAULT}, if any, |
| applies. In that case, give @var{t} the same commands that |
| @code{.DEFAULT} has. Otherwise, there are no commands for @var{t}. |
| @end enumerate |
| |
| When the commands of a pattern rule are executed for @var{t}, the automatic |
| variables @samp{$@@}, @samp{$*} and @samp{$<} are set as follows: |
| |
| @table @samp |
| @item $@@ |
| @var{t} |
| @item $* |
| If the target pattern contains a slash, this is @var{s}; otherwise, it |
| is @var{d}@var{s}. |
| @item $< |
| The name of the first dependency that came via the implicit rule. |
| @end table |
| |
| For @code{.DEFAULT} commands, as for non-implicit commands, @samp{$*} |
| and @samp{$<} are empty. @samp{$@@} is @var{t}, as always. |
| |
| @node Archives, Features, Implicit, Top |
| @chapter Using @code{make} to Update Archive Files |
| @cindex archive |
| |
| @dfn{Archive files} are files containing named subfiles called |
| @dfn{members}; they are maintained with the program @code{ar} and their |
| main use is as subroutine libraries for linking. |
| |
| @menu |
| * Members: Archive Members. How to name an archive member |
| as a target or dependency. |
| * Update: Archive Update. An implicit rule can update |
| most archive member targets just right. |
| * Symbols: Archive Symbols. Another implicit rule runs @code{ranlib} |
| to update the special member @file{__.SYMDEF}. |
| @end menu |
| |
| @node Archive Members, Archive Update, Archives, Archives |
| @section Archive Members as Targets |
| @cindex archive member targets |
| |
| An individual member of an archive file can be used as a target or |
| dependency in @code{make}. The archive file must already exist, but the |
| member need not exist. You specify the member named @var{member} in |
| archive file @var{archive} as follows: |
| |
| @example |
| @var{archive}(@var{member}) |
| @end example |
| |
| @noindent |
| This construct is available only in targets and dependencies, not in |
| commands! Most programs that you might use in commands do not support this |
| syntax and cannot act directly on archive members. Only @code{ar} and |
| other programs specifically designed to operate on archives can do so. |
| Therefore, valid commands to update an archive member target probably must |
| use @code{ar}. For example, this rule says to create a member |
| @file{hack.o} in archive @file{foolib} by copying the file @file{hack.o}: |
| |
| @example |
| foolib(hack.o) : hack.o |
| ar r foolib hack.o |
| @end example |
| |
| In fact, nearly all archive member targets are updated in just this way |
| and there is an implicit rule to do it for you. |
| |
| @node Archive Update, Archive Symbols, Archive Members, Archives |
| @section Implicit Rule for Archive Member Targets |
| |
| Recall that a target that looks like @file{@var{a}(@var{m})} stands for the |
| member named @var{m} in the archive file @var{a}. |
| |
| When @code{make} looks for an implicit rule for such a target, as a special |
| feature it considers implicit rules that match @file{(@var{m})}, as well as |
| those that match the actual target @file{@var{a}(@var{m})}. |
| |
| This causes one special rule whose target is @file{(%)} to match. This |
| rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m} |
| into the archive. For example, it will update the archive member target |
| @file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the |
| archive @file{foo.a} as a member named @file{bar.o}. |
| |
| When this rule is chained with others, the result is very powerful. Thus, |
| @samp{make "foo.a(bar.o)"} in the presence of a file @file{bar.c} is enough |
| to cause the following commands to be run, even without a makefile: |
| |
| @example |
| cc -c bar.c -o bar.o |
| ar r foo.a bar.o |
| rm -f bar.o |
| @end example |
| |
| @noindent |
| Here the file @file{bar.o} has been envisioned as an intermediate file. |
| |
| @node Archive Symbols,, Archive Update, Archives |
| @subsection Updating Archive Symbol Directories |
| @cindex __.SYMDEF |
| |
| An archive file that is used as a library usually contains a special member |
| named @file{__.SYMDEF} that contains a directory of the external symbol |
| names defined by all the other members. After you update any other |
| members, you need to update @file{__.SYMDEF} so that it will summarize the |
| other members properly. This is done by running the @code{ranlib} program: |
| |
| @example |
| ranlib @var{archivefile} |
| @end example |
| |
| Normally you would put this command in the rule for the archive file, |
| and make all the members of the archive file dependents of that rule. |
| For example, |
| |
| @example |
| libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{} |
| ranlib libfoo.a |
| @end example |
| |
| @noindent |
| The effect of this is to update archive members @file{x.o}, @file{y.o}, |
| etc., and then update the symbol directory member @file{__.SYMDEF} by |
| running @code{ranlib}. The rules for updating the members are not shown |
| here; most likely you can omit them and use the implicit rule which copies |
| files into the archive, as described in the preceding section. |
| |
| @node Features, Missing, Archives, Top |
| @chapter Features of GNU @code{make} |
| |
| GNU @code{make} contains many features not in any other @code{make} |
| program. Some of them are taken from other versions of @code{make}, while |
| most are new inventions of the implementors of GNU @code{make}. |
| |
| The standard for comparison among versions of @code{make} in this chapter |
| will be the version found in standard 4.2 BSD Unix systems. Many additions |
| come from the versions of @code{make} found in other Unix systems. This |
| chapter lists the features of GNU @code{make} beyond the 4.2 BSD version. |
| They are presented as a simple list of small items with terse descriptions. |
| All of these features (as well as those found in 4.2 BSD @code{make}) are |
| documented in this manual, so it would be redundant to repeat that |
| documentation here. |
| |
| The @code{VPATH} variable and its special meaning come from the @code{make} |
| in 4.3 BSD Unix. @xref{Directory Search}. |
| |
| Many features come from the version of @code{make} in Sun Unix systems. I |
| believe that these in turn are adopted from the @code{make} in Unix System V. |
| |
| @itemize @bullet |
| @item |
| Included makefiles. @xref{Include}. |
| |
| @item |
| Variables are read in from the environment. |
| All variables are placed into the environment of child processes (running |
| commands). @xref{Environment}. Note also the @samp{-e} option. |
| |
| @item |
| The environment variable @samp{MAKEFLAGS} is scanned for command-line |
| options to @code{make}. The options @samp{-f}, @samp{-p}, @samp{-d} and |
| @samp{-c} are not accepted. The @code{make} variable @samp{MAKEFLAGS} is |
| set to a list of the options @code{make} was invoked with, except those |
| noted above. @xref{Options/Recursion}.@refill |
| |
| @item |
| The automatic variable @code{$%} is set to the member name |
| in an archive reference. @xref{Automatic}. |
| |
| @item |
| The automatic variables @code{$@@}, @code{$*}, @code{$<} and @code{$%} have |
| corresponding forms such as @code{$(@@F)} and @code{$(@@D)} which with only |
| the filename and only the directory. @xref{Automatic}.@refill |
| |
| @item |
| Substitution variable references. @xref{Reference}. |
| |
| @item |
| The command-line options @samp{-b} and @samp{-m} are accepted and ignored. |
| |
| @item |
| Targets whose commands contain a reference to the variable @code{MAKE} have |
| their commands executed even if the @samp{-n}, @samp{-q} or @samp{-t} |
| options are specified. @xref{Recursion}. I'm told that Unix System V |
| @code{make} does this only in the case of @samp{-n}.@refill |
| |
| @item |
| An implicit suffix rule @samp{@var{x}.a:} makes |
| @file{@var{lib}(@var{name}.o)} from @file{@var{name}.@var{x}}. In GNU |
| @code{make}, this is actually implemented by using one pattern rule for |
| making library-archive files and rule-chaining. @xref{Chained Rules}.@refill |
| @end itemize |
| |
| The Sun Unix (and probably System V) version of @code{make} fails to |
| support variable references using braces (@samp{@{} and @samp{@}}) rather |
| than parantheses (@pxref{Reference}), and to set the @code{MFLAGS} variable |
| to the list of options (the same list as in @code{MAKEFLAGS}).@refill |
| |
| The remaining new features are inventions new to GNU @code{make}. |
| |
| @itemize @bullet |
| @item |
| The arrangement of lines and backslash-newline combinations in |
| commands is retained when the commands are printed, so they |
| appear as they do in the makefile, except for the stripping of |
| initial whitespace. |
| This has been implemented in several versions of @code{make}. |
| We're not sure who invented it first, but it's been spread around a bit. |
| The @samp{-v} option prints version and copyright information. |
| Rule chaining and implicit intermediate files. |
| we got this from either of them or thought it up ourselves at the |
| The automatic variable @code{$^} containing a list of all dependencies |
| of the current target. @xref{Automatic}. |
| @end itemize |
| The variable @code{MAKEOVERRIDES} is defined to contain all |
| the variable definitions given on the command line, and is |
| appended to the @code{MAKE} variable which contains the name |
| by which @code{make} was invoked. Thus, sub-makes will always |
| get variable definitions from the command line that cannot |
| come from the environment since environment variable |
| definitions do not override those in makefiles. |
| @itemize @bullet |
| @item |
| The @samp{-c} to change directory. @xref{Options}. |
| |
| @item |
| Simply-expanded variables. @xref{Flavors}. |
| |
| @item |
| Phony targets. @xref{Phony Targets}. |
| @xref{Recursion}. |
| |
| Variable expansion functions. @xref{Functions}. |
| The @samp{-c} command option to change directory. @xref{Options}. |
| |
| The @samp{-o} option makes files seem artificially old. |
| Verbatim variable definitions made with @code{define}. @xref{Defining}. |
| |
| @item |
| Conditional lines. @xref{Conditionals}. |
| A similar feature with a different syntax was implemented by |
| Andrew Hume of AT&T Bell Labs in his @code{mk} program. This |
| Included makefiles never determine the default target. |
| |
| @item |
| There is an include file search path. @xref{Include}. |
| |
| @item |
| @xref{MAKEFILES Variable}. |
| @xref{Avoid Compilation}. |
| |
| @xref{Pattern Rules}. |
| @code{make}; it seems a natural extension derived from the features |
| of the C preprocessor and similar macro languages and is not a |
| The automatic variable @code{$^} contains a list of all |
| dependencies of the current target. @xref{Automatic}. |
| @item |
| Included makefiles never determine the default goal. |
| There is a fully complete default set of implicit rules using |
| file with suffixes @samp{.out}, @samp{.a}, @samp{.o}, |
| @samp{.s}, @samp{.c}, @samp{.f}, @samp{.p}, @samp{.F}, |
| @samp{.e}, @samp{.r}, @samp{.y}, @samp{.ye}, @samp{.yr} and |
| @samp{.l}. @xref{Catalogue of Rules}.@refill |
| |
| @item |
| Leading sequences of @samp{./} are stripped from file names, |
| so that @file{./@var{file}} and @file{@var{file}} are |
| considered to be the same file. |
| @item |
| Stripping leading sequences of @samp{./} from file names, so that |
| Dependencies of the form @samp{-l@var{name}} are searched for |
| as library archives. @xref{Libraries/Search}. |
| same file. |
| |
| Suffixes for suffix rules (@pxref{Suffix Rules}) may contain |
| any characters. In other version of @code{make}, they must |
| begin with @samp{.} and not contain any @samp{/} characters. |
| |
| @item |
| The variable @code{MAKELEVEL} keeps track of the current level |
| of @code{make} recursion. At the top level (@code{MAKELEVEL} |
| is zero), the @code{SHELL} environment variable is not used to |
| execute commands. It is reset to @samp{/bin/sh}.@refill |
| |
| @item |
| Intermediate implicit files. @xref{Chained Rules}. |
| Special search method for library dependencies written in the form |
| @samp{-l@var{name}}. @xref{Libraries/Search}. |
| |
| @samp{.} and not contain any @samp{/} characters. |
| |
| @item |
| The variable @code{MAKELEVEL} which keeps track of the current level |
| of @code{make} recursion. @xref{Recursion}. |
| The @code{make} programs in various other systems support three features |
| @item |
| Static pattern rules. @xref{Static Pattern}. |
| |
| @item |
| Selective @code{vpath} search. @xref{Directory Search}. |
| |
| @item |
| Recursive variable references. @xref{Reference}. |
| @end itemize |
| |
| @node Missing, Concept Index, Features, Top |
| @chapter Missing Features in GNU @code{make} |
| |
| The @code{make} programs in various other systems support a few features |
| that are not implemented in GNU @code{make}. |
| |
| @itemize @bullet |
| @item |
| A target of the form @samp{@var{file}((@var{entry}))} stands for a member |
| of archive file @var{file}. The member is chosen, not by name, but by |
| being an object file which defines the linker symbol @var{entry}.@refill |
| |
| This feature was not put into GNU @code{make} because of the |
| nonmodularity of putting knowledge into @code{make} of the internal |
| format of archive file symbol directories. @xref{Archive Symbols}. |
| |
| @item |
| Suffixes (used in suffix rules) that end with the character @samp{~} |
| have a special meaning; they refer to the SCCS file that corresponds |
| to the file one would get without the @samp{~}. For example, the |
| suffix rule @samp{.c~.o} would make the file @file{@var{n}.o} file from |
| the SCCS file @file{s.@var{n}.c}. For complete coverage, a whole |
| series of such suffix rules is required. @xref{Suffix Rules}.@refill |
| rules. The System V @code{make} rule: |
| In GNU @code{make}, this entire series of cases is handled by two |
| pattern rules for extraction from SCCS, in combination with the |
| general feature of rule chaining. @xref{Chained Rules}. |
| |
| @item |
| In System V @code{make}, the string @samp{$$@@} has the strange meaning |
| that, in the dependencies of a rule with multiple targets, it stands |
| for the particular target that is being processed. |
| |
| This is not defined in GNU @code{make} because @samp{$$} should always |
| stand for an ordinary @samp{$}. |
| @noindent |
| can be replaced with the GNU @code{make} static pattern rule: |
| |
| @example |
| $(targets): %: %.o lib.a |
| @end example |
| |
| @item |
| In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search |
| (@pxref{Directory Search}) have their names changed inside command strings. |
| We feel it is much cleaner to always use automatic variables and thus |
| obviate the need for this feature. We are still debating whether to |
| implement this to be compatible or to leave it out to avoid such ugliness. |
| @end itemize |
| |
| @node Concept Index, Name Index, Missing, Top |
| @unnumbered Index of Concepts |
| |
| @printindex cp |
| |
| @node Name Index,, Concept Index, Top |
| @unnumbered Index of Functions, Directives and Variables |
| |
| @printindex fn |
| |
| @contents |
| @bye |