diff options
| -rw-r--r-- | make.texinfo | 522 |
1 files changed, 337 insertions, 185 deletions
diff --git a/make.texinfo b/make.texinfo index d223f57..d402fe9 100644 --- a/make.texinfo +++ b/make.texinfo @@ -6,15 +6,17 @@ @smallbook @c %**end of header -@set EDITION 0.37 +@set EDITION 0.38 @set VERSION 3.63 Beta -@set UPDATED 13 November 1992 +@set UPDATED 17 November 1992 @set UPDATE-MONTH November 1992 @c finalout @c Combine the variable and function indices: @synindex vr fn +@c Combine the program and function indices: +@synindex pg fn @ifinfo This file documents the GNU Make utility, which determines @@ -530,14 +532,10 @@ than shown in this template, but all fit the pattern more or less. Here is a straightforward makefile that describes the way an executable file called @code{edit} depends on eight object files which, in turn, depend on eight C source and three header files. -@cindex @code{edit} In this example, all the C files include @file{defs.h}, but only those defining editing commands include @file{command.h}, and only low level files that change the editor buffer include @file{buffer.h}. -@cindex @file{defs.h} -@cindex @file{command.h} -@cindex @file{buffer.h} @example @group @@ -586,9 +584,6 @@ files from the directory, type: make clean @end example -@cindex @file{main.o} -@cindex @file{kbd.o} -@cindex @file{main.c} In the example makefile, the targets include the executable file @samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}. The dependencies are files such as @samp{main.c} and @samp{defs.h}. @@ -622,7 +617,7 @@ but are just actions are called @dfn{phony targets}. @xref{Phony Targets}, for information about this kind of target. @xref{Errors, , Errors in Commands}, to see how to cause @code{make} ignore errors from @code{rm}. -@cindex @samp{clean} target +@cindex @code{clean} target @pindex rm @r{(shell command)} @node How Make Works, Variables Simplify, Simple Makefile, Introduction @@ -686,9 +681,6 @@ Thus, if we change the file @file{insert.c} and run @code{make}, link @file{edit}. If we change the file @file{command.h} and run @code{make}, @code{make} will recompile the object files @file{kbd.o}, @file{command.o} and @file{files.o} and then link the file @file{edit}. -@cindex @file{insert.c} -@cindex @file{insert.o} -@cindex @file{files.o} @node Variables Simplify, make Deduces, How Make Works, Introduction @section Variables Make Makefiles Simpler @@ -862,7 +854,7 @@ for. Makefiles commonly tell how to do a few other things besides compiling a program: for example, how to delete all the object files and executables so that the directory is @samp{clean}. -@cindex @samp{clean} target +@cindex @code{clean} target Here is how we could write a @code{make} rule for cleaning our example editor: @@ -970,7 +962,7 @@ Defining a variable from a verbatim string containing multiple lines @end itemize @cindex comments, in makefile -@cindex @samp{#} (comments), in makefile +@cindex @code{#} (comments), in makefile @item @samp{#} in a line of a makefile starts a @dfn{comment}. It and the rest of the line are ignored, except that a trailing backslash not escaped by @@ -996,7 +988,7 @@ and @file{Makefile}.@refill @pindex GNUmakefile @pindex makefile -@cindex @file{README} +@cindex @code{README} Normally you should call your makefile either @file{makefile} or @file{Makefile}. (We recommend @file{Makefile} because it appears prominently near the beginning of a directory listing, right near other @@ -1088,8 +1080,7 @@ 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}. -@cindex generating dependencies automatically -@cindex dependencies, generating automatically +@cindex dependencies, automatic generation @cindex @code{-I} If the specified name does not start with a slash, and the file is not @@ -1110,7 +1101,7 @@ of the makefile containing the @code{include} continues.@refill @node MAKEFILES Variable, Remaking Makefiles, Include, Makefiles @section The Variable @code{MAKEFILES} @cindex makefiles (@code{MAKEFILES} variable) -@cindex including makefiles (@code{MAKEFILES} variable) +@cindex including (@code{MAKEFILES} variable) @vindex MAKEFILES If the environment variable @code{MAKEFILES} is defined, @code{make} @@ -1240,9 +1231,6 @@ foo: .DEFAULT: @@$(MAKE) -f Makefile $@@ @end example -@cindex @code{foo} -@cindex @code{bar} -@cindex @code{frobnicate} If you say @samp{make foo}, @code{make} will find @file{GNUmakefile}, read it, and see that to make @file{foo}, it needs to run the command @@ -1314,9 +1302,6 @@ foo.o : foo.c defs.h # module for twiddling the frobs cc -c -g foo.c @end example -@cindex @file{foo.o} -@cindex @file{foo.c} -@cindex @file{defs.h} 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. @@ -1378,8 +1363,8 @@ appear on the same line, with a semicolon. Either way, the effect is the same. @xref{Commands, ,Writing the Commands in Rules}. @cindex dollar signs in rules -@cindex @samp{$} in rules -@cindex rules, and @samp{$} +@cindex @code{$} in rules +@cindex rules, and @code{$} Because dollar signs are used to start variable references, if you really want a dollar sign in a rule you must write two of them, @samp{$$} (@pxref{Using Variables, ,How to Use Variables}). @@ -1453,7 +1438,6 @@ specific file whose name consists of @samp{foo}, an asterisk, and Wildcards can be used in the commands of a rule, where they are expanded by the shell. For example, here is a rule to delete all the object files: -@cindex @file{clean} @example @group @@ -1473,7 +1457,7 @@ print: *.c touch print @end example -@cindex @file{print} +@cindex @code{print} target @pindex lpr @r{(shell command)} @pindex touch @r{(shell command)} @noindent @@ -1485,7 +1469,6 @@ Targets, ,Empty Target Files to Record Events}. (The automatic variable Wildcard expansion does not happen when you define a variable. Thus, if you write this: -@cindex @code{objects} @example objects = *.o @end example @@ -1522,8 +1505,6 @@ objects = *.o foo : $(objects) cc -o foo $(CFLAGS) $(objects) @end example -@cindex @file{foo} -@cindex @code{objects} @noindent The value of @code{objects} is the actual string @samp{*.o}. Wildcard @@ -1602,8 +1583,8 @@ there is no need to write explicit rules for compiling the files. @vindex VPATH @findex vpath @cindex vpath -@cindex search path for dependencies (VPATH) -@cindex directory search (VPATH) +@cindex search path for dependencies (@code{VPATH}) +@cindex directory search (@code{VPATH}) For large systems, it is often desirable to put sources in a separate directory from the binaries. The @dfn{directory search} features of @@ -1772,7 +1753,7 @@ 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 @cindex shell commands, and directory search -@cindex directory search (VPATH), and shell commands +@cindex directory search, and shell commands When a dependency is found in another directory through directory search, this cannot change the commands of the rule; they will execute as written. @@ -1809,9 +1790,11 @@ foo.o : foo.c defs.h hack.h @node Implicit/Search, Libraries/Search, Commands/Search, Directory Search @subsection Directory Search and Implicit Rules -@cindex directory search (VPATH) and implicit rules -@cindex search in directories (VPATH) with implicit rules -@cindex implicit rules with directory search (VPATH) +@cindex @code{VPATH}, and implicit rules +@cindex directory search, and implicit rules +@cindex search path, and implicit rules +@cindex implicit rules, and directory search +@cindex implicit rules, and @code{VPATH} The search through the directories specified in @code{VPATH} or with @code{vpath} happens also during consideration of implicit rules @@ -1830,10 +1813,11 @@ directory search with no extra effort. @node Libraries/Search, , Implicit/Search, Directory Search @subsection Directory Search for Link Libraries -@cindex link libraries, directory search (VPATH) -@cindex libraries for linking, directory search (VPATH) -@cindex directory search (VPATH), link libraries -@cindex search in directories (VPATH), link libraries +@cindex link libraries, and directory search +@cindex libraries for linking, directory search +@cindex directory search, and link libraries +@cindex @code{VPATH}, and link libraries +@cindex search path, and link libraries @cindex @code{-l} (library search) Directory search applies in a special way to libraries used with the @@ -1878,7 +1862,6 @@ 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: -@cindex @file{clean} @example @group clean: @@ -1938,7 +1921,7 @@ 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: -@cindex @file{all} +@cindex @code{all} @example all : prog1 prog2 prog3 @@ -1953,14 +1936,6 @@ prog2 : prog2.o prog3 : prog3.o sort.o utils.o cc -o prog3 prog3.o sort.o utils.o @end example -@cindex @file{prog1} -@cindex @file{prog2} -@cindex @file{prog3} -@cindex @file{prog1.o} -@cindex @file{prog2.o} -@cindex @file{prog3.o} -@cindex @file{sort.o} -@cindex @file{utils.o} @noindent Now you can say just @samp{make} to remake all three programs, or specify @@ -1980,16 +1955,13 @@ cleanobj : cleandiff : rm *.diff @end example -@cindex @file{cleanall} -@cindex @file{cleanobj} -@cindex @file{cleandiff} @node Force Targets, Empty Targets, Phony Targets, Rules @section Rules without Commands or Dependencies @cindex force targets @cindex targets, force -@cindex @file{FORCE} -@cindex rules, without commands or dependencies +@cindex @code{FORCE} +@cindex rules, no commands or dependencies If a rule has no dependencies or commands, and the target of the rule is a nonexistent file, then @code{make} imagines this target to have @@ -2044,7 +2016,7 @@ print: foo.c bar.c lpr -p $? touch print @end example -@cindex @file{print} +@cindex @code{print} target @pindex lpr @r{(shell command)} @pindex touch @r{(shell command)} @@ -2163,10 +2135,6 @@ You want just dependencies, no commands. For example: @example kbd.o command.o files.o: command.h @end example -@cindex @file{kbd.o} -@cindex @file{command.o} -@cindex @file{files.o} -@cindex @file{kbd.h} @noindent gives an additional dependency to each of the three object files @@ -2184,10 +2152,6 @@ bigoutput littleoutput : text.g generate text.g -$(subst output,,$@@) > $@@ @end group @end example -@cindex @file{bigoutput} -@cindex @file{littleoutput} -@cindex @file{text.g} -@cindex @code{generate} @findex subst @noindent @@ -2238,12 +2202,6 @@ 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 the following: -@cindex @code{objects} -@cindex @file{config.h} -@cindex @file{foo.o} -@cindex @file{bar.o} -@cindex @file{defs.h} -@cindex @file{test.h} @example objects = foo.o bar.o @@ -2266,7 +2224,6 @@ extradeps= $(objects) : $(extradeps) @end group @end example -@cindex @code{extradeps} @noindent means that the command @samp{make extradeps=foo.h} will consider @@ -2299,7 +2256,7 @@ be @emph{analogous}, but not necessarily @emph{identical}. @node Static Usage, Static versus Implicit, , Static Pattern @subsection Syntax of Static Pattern Rules @cindex static pattern rule, syntax of -@cindex pattern rule, static (not implicit), syntax of +@cindex pattern rules, static, syntax of Here is the syntax of a static pattern rule: @@ -2327,9 +2284,6 @@ the target name; this part is called the @dfn{stem}. The rest of the pattern must match exactly. For example, the target @file{foo.o} matches the pattern @samp{%.o}, with @samp{foo} as the stem. The targets @file{foo.c} and @file{foo.out} do not match that pattern.@refill -@cindex @file{foo.o} -@cindex @file{foo.c} -@cindex @file{foo.out} The dependency names for each target are made by substituting the stem for the @samp{%} in each dependency pattern. For example, if one @@ -2338,10 +2292,10 @@ dependency pattern is @file{%.c}, then substitution of the stem to write a dependency pattern that does not contain @samp{%}; then this dependency is the same for all targets. -@cindex backslash (@samp{\}), to quote @samp{%} -@cindex @samp{\} (backslash), to quote @samp{%} -@cindex quoting @samp{%} with @samp{\} (backslash) -@cindex @samp{%}, quoting with @samp{\} (backslash) +@cindex backslash (@code{\}), to quote @code{%} +@cindex @code{\} (backslash), to quote @code{%} +@cindex quoting @code{%} with @code{\} +@cindex @code{%}, quoting with @code{\} (backslash) @samp{%} characters in pattern rules can be quoted with preceding backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%} characters can be quoted with more backslashes. Backslashes that quote @@ -2364,7 +2318,6 @@ $(objects): %.o: %.c $(CC) -c $(CFLAGS) $< -o $@@ @end group @end example -@cindex @code{objects} @noindent Here @samp{$<} is the automatic variable that holds the name of the @@ -2385,10 +2338,6 @@ $(filter %.elc,$(files)): %.elc: %.el emacs -f batch-byte-compile $< @end example @pindex emacs -@cindex @code{files} -@cindex @file{foo.elc} -@cindex @file{bar.o} -@cindex @file{lose.o} @noindent Here the result of @samp{$(filter %.o,$(files))} is @file{bar.o lose.o}, @@ -2440,9 +2389,9 @@ to precisely the targets specified. @node Double-Colon, , Multiple Rules, Rules @section Double-Colon Rules @cindex double-colon rules -@cindex rules, double-colon (@samp{::}) -@cindex multiple, independent rules for one target -@cindex @samp{::} rules (double-colon) +@cindex rules, double-colon (@code{::}) +@cindex multiple rules for one target (@code{::}) +@cindex @code{::} rules (double-colon) @dfn{Double-colon} rules are rules written with @samp{::} instead of @samp{:} after the target names. They are handled differently from @@ -2489,7 +2438,7 @@ otherwise. @xref{Execution, ,Command Execution}. @cindex comments, in commands @cindex commands, comments in -@cindex @samp{#} (comments), in commands +@cindex @code{#} (comments), in commands The shell that is in use determines whether comments can be written on command lines, and what syntax they use. When the shell is @file{/bin/sh}, a @samp{#} starts a comment that extends to the end of @@ -2511,7 +2460,7 @@ Text on a line before a @samp{#} is not part of the comment. @section Command Echoing @cindex echoing of commands @cindex silent operation -@cindex @samp{@@} (in commands) +@cindex @code{@@} (in commands) @cindex command echoing @cindex printing of commands @@ -2572,15 +2521,11 @@ example: foo : bar/lose cd bar; gobble lose > ../foo @end example -@cindex @file{foo} -@cindex @file{bar} -@cindex @file{lose} -@cindex @code{gobble} -@cindex commands, backslash (@samp{\}) in +@cindex commands, backslash (@code{\}) in @cindex commands, quoting newlines in -@cindex backslash (@samp{\}), in commands -@cindex @samp{\} (backslash), in commands +@cindex backslash (@code{\}), in commands +@cindex @code{\} (backslash), in commands @cindex quoting newlines in commands 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. @@ -2714,7 +2659,7 @@ For example, you may use the @code{mkdir} command to ensure 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 @samp{-} (in commands) +@cindex @code{-} (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. @@ -2727,7 +2672,6 @@ clean: -rm -f *.o @end group @end example -@cindex @file{clean} @pindex rm @r{(shell command)} @noindent @@ -2824,8 +2768,6 @@ subdirectory. You can do it by writing this: subsystem: cd subdir; $(MAKE) @end example -@cindex @file{subsystem} -@cindex @file{subdir} @noindent or, equivalently, this (@pxref{Options Summary, ,Summary of Options}): @@ -2862,8 +2804,6 @@ subsystem: cd subdir; $(MAKE) @end group @end example -@cindex @file{subsystem} -@cindex @file{subdir} 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 @@ -2892,7 +2832,7 @@ create a file named @file{subsystem} and do nothing else. What you really want it to do is run @samp{@w{cd subdir;} @w{make -t}}; but that would require executing the command, and @samp{-t} says not to execute commands.@refill -@cindex @code{-t} (vs. recursion) +@cindex @code{-t}, and recursion @cindex recursion, and @code{-t} The special feature makes this do what you want: whenever a command @@ -3014,7 +2954,7 @@ on this behavior and you want to be compatible with old versions of @code{.EXPORT_ALL_VARIABLES} instead of using the @code{export} directive. This will be ignored by old @code{make}s, while the @code{export} directive will cause a syntax error.@refill -@cindex compatibility (@code{.EXPORT_ALL_VARIABLES}) +@cindex compatibility in exporting Likewise, you can use @code{unexport} by itself to tell @code{make} @emph{not} to export variables by default. Since this is the default @@ -3050,7 +2990,7 @@ Variable @code{MAKEFILES}}.@refill @node Options/Recursion, -w Option, Variables/Recursion, Recursion @subsection Communicating Options to a Sub-@code{make} -@cindex options and recursion +@cindex options, and recursion @cindex recursion, and options @vindex MAKEFLAGS @@ -3195,9 +3135,7 @@ yacc $(firstword $^) mv y.tab.c $@@ endef @end example -@cindex @code{run-yacc} @pindex yacc -@cindex @file{y.tab.c} @noindent Here @code{run-yacc} is the name of the variable being defined; @@ -3225,8 +3163,6 @@ are expanded now. For example: foo.c : foo.y $(run-yacc) @end example -@cindex @file{foo.c} -@cindex @file{foo.y} @noindent @samp{foo.y} will be substituted for the variable @samp{$^} when it occurs in @@ -3316,10 +3252,12 @@ command options (@pxref{Overriding, ,Overriding Variables}). * Environment:: Variable values can come from the environment. @end menu -@c !!! I have added index entries up thru here as of 11-16-92. -rm - @node Reference, Flavors, , Using Variables @section Basics of Variable References +@cindex variables, how to reference +@cindex reference to variables +@cindex @code{$} (variables) +@cindex dollar sign (@code{$}), and variables 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 @@ -3353,7 +3291,7 @@ prog.o : prog.c @end example @noindent -could be used to compile a C program @file{prog.c}. Since spaces around +could be used to compile a C program @file{prog.c}. Since spaces before the variable value are ignored in variable assignments, the value of @code{foo} is precisely @samp{c}. (Don't actually write your makefiles this way!) @@ -3368,12 +3306,15 @@ the case of the automatic variables (@pxref{Automatic, ,Automatic Variables}). @section The Two Flavors of Variables @cindex flavors of variables @cindex recursive variable expansion -@cindex variable flavors +@cindex variables, flavors +@cindex recursively expanded variables +@cindex variables, recursively expanded There are two ways that a variable in GNU @code{make} can have a value; we call them the two @dfn{flavors} of variables. The two flavors are distinguished in how they are defined and in what they do when expanded. +@cindex = The first flavor of variable is a @dfn{recursively expanded} variable. Variables of this sort are defined by lines using @samp{=} (@pxref{Setting, ,Setting Variables}) or by the @code{define} directive @@ -3418,8 +3359,11 @@ CFLAGS = $(CFLAGS) -O @noindent because it will cause an infinite loop in the variable expansion. (Actually @code{make} detects the infinite loop and reports an error.) +@cindex loops in variable expansion +@cindex variables, loops in expansion -Another disadvantage is that any functions (@pxref{Functions, ,Functions for Transforming Text}) +Another disadvantage is that any functions +(@pxref{Functions, ,Functions for Transforming Text}) 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} and @code{shell} functions to give unpredictable results @@ -3430,6 +3374,8 @@ To avoid all the problems and inconveniences of recursively expanded variables, there is another flavor: simply expanded variables. @cindex simply expanded variables +@cindex variables, simply expanded +@cindex := @dfn{Simply expanded variables} are defined by lines using @samp{:=} (@pxref{Setting, ,Setting Variables}). The value of a simply expanded variable is scanned @@ -3464,6 +3410,8 @@ when it is passed down from level to level. (@xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}, for information about @code{MAKELEVEL}.) +@vindex MAKELEVEL +@vindex MAKE @example @group ifeq (0,$@{MAKELEVEL@}) @@ -3490,8 +3438,11 @@ 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, ,Functions for Transforming Text}). +use the expansion functions much more efficiently +(@pxref{Functions, ,Functions for Transforming Text}). +@cindex spaces, in variable values +@cindex variables, spaces in values 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 @@ -3523,7 +3474,11 @@ variables in more flexible ways. @subsection Substitution References @cindex modified variable reference @cindex substitution variable reference +@cindex variables, modified reference +@cindex variables, substitution reference +@cindex variables, substituting suffix in +@cindex suffix, substituting in variables A @dfn{substitution reference} substitutes the value of a variable with alterations that you specify. It has the form @samp{$(@var{var}:@var{a}=@var{b})} (or @@ -3549,6 +3504,7 @@ A substitution reference is actually an abbreviation for use of the substitution references as well as @code{patsubst} for compatibility with other implementations of @code{make}. +@findex patsubst Another type of substitution reference lets you use the full power of the @code{patsubst} function. It has the same form @samp{$(@var{var}:@var{a}=@var{b})} described above, except that now @@ -3573,7 +3529,11 @@ sets @samp{bar} to @samp{a.c b.c c.c}. @subsection Computed Variable Names @cindex nested variable reference @cindex computed variable name -@cindex variable reference, nested +@cindex variables, computed names +@cindex variables, nested references +@cindex variables, @samp{$} in name +@cindex @code{$} in variable name +@cindex dollar sign (@code{$}) in variable name Computed variable names are a complicated concept needed only for sophisticated makefile programming. For most purposes you need not @@ -3742,6 +3702,8 @@ used together in complex ways when doing makefile programming.@refill @node Values, Setting, Advanced, Using Variables @section How Variables Get Their Values +@cindex variables, how they get their values +@cindex values, how variables get them Variables can get values in several different ways: @@ -3761,7 +3723,8 @@ Variables in the environment become @code{make} variables. @item Several @dfn{automatic} variables are given new values for each rule. -Each of these has a single conventional use. @xref{Automatic, ,Automatic Variables}. +Each of these has a single conventional use. +@xref{Automatic, ,Automatic Variables}. @item Several variables have constant initial values. @@ -3810,6 +3773,7 @@ automatically to a new value for each rule; these are called the @section The @code{override} Directive @findex override @cindex overriding with @code{override} +@cindex variables, overriding If a variable has been set with a command argument (@pxref{Overriding, ,Overriding Variables}), then ordinary assignments in the makefile are ignored. If you want to set @@ -3868,7 +3832,8 @@ See the next section for information about @code{define}. Another way to set the value of a variable is to use the @code{define} directive. This directive has an unusual syntax which allows newline characters to be included in the value, which is convenient for defining -canned sequences of commands (@pxref{Sequences, ,Defining Canned Command Sequences}). +canned sequences of commands +(@pxref{Sequences, ,Defining Canned Command Sequences}). The @code{define} directive is followed on the same line by the name of the variable and nothing more. The value to give the variable appears on the @@ -3915,6 +3880,7 @@ endef @node Environment, , Defining, Using Variables @section Variables from the Environment +@cindex variables, environment @cindex environment Variables in @code{make} can come from the environment in which @code{make} is run. Every environment variable that @code{make} sees when @@ -3922,7 +3888,8 @@ 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 Summary, ,Summary of Options}. But this is not recommended practice.) +@xref{Options Summary, ,Summary of Options}. +But this is not recommended practice.) Thus, by setting the variable @code{CFLAGS} in your environment, you can cause all C compilations in most makefiles to use the compiler switches you @@ -3972,12 +3939,12 @@ commands at the time of execution.@refill @node Conditional Example, Conditional Syntax, , Conditionals @section Example of a Conditional -The following example of a 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} changes not only which compiler is used but also which -libraries are linked. +The following example of a 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} changes not only which +compiler is used but also which libraries are linked. @example libs_for_gcc = -lgnu @@ -4180,8 +4147,10 @@ not attempt to terminate the conditional inside the included file. 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. +@code{findstring} function +(@pxref{Text Functions, , Functions for String Substitution and Analysis}). +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, @@ -4228,8 +4197,9 @@ call, just as a variable might be substituted. @node Syntax of Functions, Text Functions, , Functions @section Function Call Syntax -@cindex $ (function call) -@cindex arguments +@cindex @code{$} (function call) +@cindex arguments of functions +@cindex functions, syntax of A function call resembles a variable reference. It looks like this: @@ -4289,6 +4259,7 @@ the value of @code{foo}, and substitutes the result. @node Text Functions, Filename Functions, Syntax of Functions, Functions @section Functions for String Substitution and Analysis +@cindex functions, for text Here are some functions that operate on strings: @@ -4314,8 +4285,10 @@ 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}.@refill -@cindex quoting @samp{%} in @code{patsubst} -@cindex @samp{%}, quoting in @code{patsubst} +@cindex backslash (@code{\}), to quote @samp{%} +@cindex @code{\} (backslash), to quote @samp{%} +@cindex quoting @code{%} in @code{patsubst} +@cindex @code{%}, quoting in @code{patsubst} @samp{%} characters in @code{patsubst} function invocations can be quoted with preceding backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%} characters can be quoted with more backslashes. @@ -4391,6 +4364,9 @@ $(patsubst %.o,%.c,$(objects)) @end example @item $(strip @var{string}) +@cindex stripping whitespace +@cindex whitespace, stripping +@cindex spaces, stripping @findex strip Removes leading and trailing whitespace from @var{string} and replaces each internal sequence of one or more whitespace characters with a @@ -4419,6 +4395,9 @@ directive would make it more robust.@refill @item $(findstring @var{find},@var{in}) @findex findstring +@cindex searching for strings +@cindex finding strings +@cindex strings, searching for 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 @@ -4436,6 +4415,8 @@ respectively. @xref{Testing Flags}, for a practical application of @need 750 @findex filter +@cindex filtering words +@cindex words, filtering @item $(filter @var{pattern}@dots{},@var{text}) Removes all whitespace-separated words in @var{text} that do @emph{not} match any of the @var{pattern} words, returning only @@ -4459,6 +4440,8 @@ compiler.@refill @item $(filter-out @var{pattern}@dots{},@var{text}) @findex filter-out +@cindex filtering out words +@cindex words, filtering out Removes all whitespace-separated words in @var{text} that @emph{do} match the @var{pattern} words, returning only the words that @emph{do not} match. This is the exact opposite of the @code{filter} @@ -4483,6 +4466,7 @@ $(filter-out $(mains),$(objects)) @need 1500 @findex sort +@cindex sorting words @item $(sort @var{list}) Sorts the words of @var{list} in lexical order, removing duplicate words. The output is a list of words separated by single spaces. @@ -4497,6 +4481,7 @@ returns the value @samp{bar foo lose}. @cindex removing duplicate words @cindex duplicate words, removing +@cindex words, removing duplicates Incidentally, since @code{sort} removes duplicate words, you can use it for this purpose even if you don't care about the sort order. @end table @@ -4538,6 +4523,8 @@ Directive, , The @code{override} Directive}). @node Filename Functions, Foreach Function, Text Functions, Functions @section Functions for File Names +@cindex functions, for file names +@cindex file name functions Several of the built-in expansion functions relate specifically to taking apart file names or lists of file names. @@ -4551,6 +4538,8 @@ the results are concatenated with single spaces between them. @table @code @item $(dir @var{names}@dots{}) @findex dir +@cindex directory part +@cindex file name, directory part 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, @@ -4565,6 +4554,8 @@ produces the result @samp{src/ ./}. @item $(notdir @var{names}@dots{}) @findex notdir +@cindex file name, nondirectory part +@cindex nondirectory part 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. @@ -4585,6 +4576,8 @@ produces the result @samp{foo.c hacks}. @item $(suffix @var{names}@dots{}) @findex suffix +@cindex suffix, function to find +@cindex file name 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 @@ -4603,6 +4596,8 @@ produces the result @samp{.c}. @item $(basename @var{names}@dots{}) @findex basename +@cindex basename +@cindex file name, basename of 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 @@ -4618,6 +4613,8 @@ produces the result @samp{src/foo hacks}. @c plural convention with dots (be consistent) @item $(addsuffix @var{suffix},@var{names}@dots{}) @findex addsuffix +@cindex suffix, adding +@cindex file name suffix, adding 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 @@ -4633,6 +4630,8 @@ produces the result @samp{foo.c bar.c}. @item $(addprefix @var{prefix},@var{names}@dots{}) @findex addprefix +@cindex prefix, adding +@cindex file name prefix, adding 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 prepended to the front of each individual name and the @@ -4648,6 +4647,8 @@ produces the result @samp{src/foo src/bar}. @item $(join @var{list1},@var{list2}) @findex join +@cindex joining lists of words +@cindex words, joining lists 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 @@ -4666,6 +4667,8 @@ was given to those two functions.@refill @item $(word @var{n},@var{text}) @findex word +@cindex words, selecting +@cindex selecting words Returns the @var{n}th word of @var{text}. The legitimate values of @var{n} start from 1. If @var{n} is bigger than the number of words in @var{text}, the value is empty. For example, @@ -4680,12 +4683,14 @@ returns @samp{bar}. @c Following item phrased to prevent overfull hbox. --RJC 17 Jul 92 @item $(words @var{text}) @findex words +@cindex words, finding number Returns the number of words in @var{text}. Thus, the last word of @var{text} is @w{@code{$(word $(words @var{text}),@var{text})}}.@refill @item $(firstword @var{names}@dots{}) @findex firstword +@cindex words, extracting first 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. @@ -4703,6 +4708,7 @@ produces the result @samp{foo}. Although @code{$(firstword @item $(wildcard @var{pattern}) @findex wildcard +@cindex wildcards, function The argument @var{pattern} is a file name pattern, typically containing wildcard characters (as in shell file name patterns). The result of @code{wildcard} is a space-separated list of the names of existing files @@ -4713,6 +4719,7 @@ that match the pattern. @node Foreach Function, Origin Function, Filename Functions, Functions @section The @code{foreach} Function @findex foreach +@cindex words, iterating over 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 @@ -4800,6 +4807,8 @@ no?), but it is more likely to be a mistake. @node Origin Function, Shell Function, Foreach Function, Functions @section The @code{origin} Function @findex origin +@cindex variables, origin of +@cindex origin of variable The @code{origin} function is unlike most other functions in that it does not operate on the values of variables; it tells you something @emph{about} @@ -4827,9 +4836,9 @@ if @var{variable} was never defined. @item default if @var{variable} has a default definition, as is usual with @code{CC} -and so on. @xref{Implicit Variables, ,Variables Used by Implicit Rules}. Note that if you have -redefined a default variable, the @code{origin} function will return -the origin of the later definition. +and so on. @xref{Implicit Variables, ,Variables Used by Implicit Rules}. +Note that if you have redefined a default variable, the @code{origin} +function will return the origin of the later definition. @item environment @@ -4909,6 +4918,7 @@ Here the redefinition takes place if @samp{$(origin bletch)} returns either @findex shell @cindex command expansion @cindex backquotes +@cindex shell commands, function for The @code{shell} function is unlike any other function except the @code{wildcard} function @@ -4980,6 +4990,8 @@ things or many others. @node Makefile Arguments, Goals, , Running @section Arguments to Specify the Makefile +@cindex @code{--file} +@cindex @code{--f} The way to specify the name of the makefile is with the @samp{-f} or @samp{--file} option. For example, @samp{-f altmake} says to use the @@ -4996,7 +5008,7 @@ that order, and use the first of these three which exists or can be made @node Goals, Instead of Execution, Makefile Arguments, Running @section Arguments to Specify the Goals -@cindex goal +@cindex goal, how to specify The @dfn{goals} are the targets that @code{make} should strive ultimately to update. Other targets are updated as well if they appear as @@ -5045,20 +5057,26 @@ names:@refill @table @file @item all +@cindex @code{all} @r{(standard target)} Make all the top-level targets the makefile knows about. @item clean +@cindex @code{clean} @r{(standard target)} Delete all files that are normally created by running @code{make}. @item mostlyclean +@cindex @code{mostlyclean} @r{(standard target)} Like @samp{clean}, but may refrain from deleting a few files that people normally don't want to recompile. For example, the @samp{mostlyclean} target for GCC does not delete @file{libgcc.a}, because recompiling it is rarely necessary and takes a lot of time. @item distclean +@cindex @code{distclean} @r{(standard target)} @itemx realclean +@cindex @code{realclean} @r{(standard target)} @itemx clobber +@cindex @code{clobber} @r{(standard target)} Any of these three might be defined to delete everything that would not be part of a standard distribution. For example, this would delete configuration files or links that you would normally create as @@ -5066,34 +5084,44 @@ preparation for compilation, even if the makefile itself cannot create these files. @item install +@cindex @code{install} @r{(standard target)} 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 +@cindex @code{print} @r{(standard target)} Print listings of the source files that have changed. @item tar +@cindex @code{tar} @r{(standard target)} Create a tar file of the source files. @item shar +@cindex @code{shar} @r{(standard target)} Create a shell archive (shar file) of the source files. @item dist +@cindex @code{dist} @r{(standard target)} Create a distribution file of the source files. This might be a tar file, or a shar file, or a compressed version of one of the above, or even more than one of the above. @item TAGS +@cindex @code{TAGS} @r{(standard target)} Update a tags table for this program. @item check +@cindex @code{check} @r{(standard target)} @itemx test +@cindex @code{test} @r{(standard target)} Perform self tests on the program this makefile builds. @end table @node Instead of Execution, Avoiding Compilation, Goals, Running @section Instead of Executing the Commands +@cindex execution, instead of +@cindex commands, instead of executing 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 @@ -5111,6 +5139,7 @@ the targets up to date, but not actually execute them. @itemx --touch @cindex @code{--touch} @cindex touching files +@cindex targets, touching @cindex @code{-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 @@ -5130,6 +5159,7 @@ words, neither compilation nor output will occur. @cindex @code{--what-if} @cindex @code{-W} @cindex what if +@cindex files, assuming new ``What if''. Each @samp{-W} flag is followed by a file name. The given files' modification times are recorded by @code{make} as being the present time, although the actual modification times remain the same. @@ -5182,6 +5212,10 @@ information about @code{make} or about the makefiles in use @node Avoiding Compilation, Overriding, Instead of Execution, Running @section Avoiding Recompilation of Some Files @cindex @code{-o} +@cindex @code{--old-file} +@cindex files, assuming old +@cindex files, avoiding recompilation of +@cindex recompilation, avoiding Sometimes you may have changed a source file but you do not want to recompile all the files that depend on it. For example, suppose you add a @@ -5231,6 +5265,9 @@ Touch all the object files with @samp{make -t}. @node Overriding, Testing, Avoiding Compilation, Running @section Overriding Variables @cindex overriding variables with arguments +@cindex variables, overriding with arguments +@cindex command line variables +@cindex variables, command line An argument that contains @samp{=} specifies the value of a variable: @samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}. @@ -5285,6 +5322,7 @@ that looks like this: @samp{override @var{variable} = @var{value}} @node Testing, Options Summary, Overriding, Running @section Testing the Compilation of a Program @cindex testing compilation +@cindex compilation, testing Normally, when an error happens in executing a shell command, @code{make} gives up immediately, returning a nonzero status. No further commands are @@ -5323,16 +5361,21 @@ correct them all before the next attempt to compile. This is why Emacs's @section Summary of Options @cindex options @cindex flags +@cindex switches Here is a table of all the options @code{make} understands: @table @samp @item -b +@cindex @code{-b} @itemx -m +@cindex @code{-m} These options are ignored for compatibility with other versions of @code{make}. @item -C @var{dir} +@cindex @code{-C} @itemx --directory @var{dir} +@cindex @code{--directory} Change to directory @var{dir} before reading the makefiles. 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}. @@ -5340,7 +5383,9 @@ This is typically used with recursive invocations of @code{make} (@pxref{Recursion, ,Recursive Use of @code{make}}). @item -d +@cindex @code{-d} @itemx --debug +@cindex @code{--debug} 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, @@ -5349,34 +5394,48 @@ considered and which are applied---everything interesting about how @code{make} decides what to do. @item -e +@cindex @code{-e} @item --environment-overrides +@cindex @code{--environment-overrides} Give variables taken from the environment precedence -over variables from makefiles. @xref{Environment, ,Variables from the Environment}. +over variables from makefiles. +@xref{Environment, ,Variables from the Environment}. @item -f @var{file} +@cindex @code{-f} @item --file @var{file} +@cindex @code{--file} @item --makefile @var{file} +@cindex @code{--makefile} Read the file named @var{file} as a makefile. @xref{Makefiles, ,Writing Makefiles}. @item -h +@cindex @code{-h} @itemx --help -Remind you of the options that @code{make} understands and then exits. +@cindex @code{--help} +Remind you of the options that @code{make} understands and then exit. @item -i +@cindex @code{-i} @itemx --ignore-errors +@cindex @code{--ignore-errors} Ignore all errors in commands executed to remake files. @xref{Errors, ,Errors in Commands}. @item -I @var{dir} +@cindex @code{-I} @item --include-dir @var{dir} +@cindex @code{--include-dir} Specifies a directory @var{dir} to search for included makefiles. @xref{Include, ,Including Other Makefiles}. If several @samp{-I} options are used to specify several directories, the directories are searched in the order specified. @item -j [@var{jobs}] +@cindex @code{-j} @itemx --jobs [@var{jobs}] +@cindex @code{--jobs} Specifies the number of jobs (commands) to run simultaneously. With no argument, @code{make} runs as many jobs simultaneously as possible. If there is more than one @samp{-j} option, the last one is effective. @@ -5384,30 +5443,42 @@ there is more than one @samp{-j} option, the last one is effective. for more information on how commands are run. @item -k +@cindex @code{-k} @itemx --keep-going +@cindex @code{--keep-going} 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, ,Testing the Compilation of a Program}. @item -l [@var{load}] +@cindex @code{-l} @itemx --load-average [@var{load}] +@cindex @code{--load-average} @itemx --max-load [@var{load}] +@cindex @code{--max-load} Specifies that no new jobs (commands) should be started if there are others jobs running and the load average is at least @var{load} (a floating-point number). With no argument, removes a previous load limit. @xref{Parallel, ,Parallel Execution}. @item -n +@cindex @code{-n} @itemx --just-print +@cindex @code{--just-print} @itemx --dry-run +@cindex @code{--dry-run} @itemx --recon +@cindex @code{--recon} Print the commands that would be executed, but do not execute them. @xref{Instead of Execution, ,Instead of Executing the Commands}. @item -o @var{file} +@cindex @code{-o} @itemx --old-file @var{file} +@cindex @code{--old-file} @itemx --assume-old @var{file} +@cindex @code{--assume-old} 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 @@ -5415,7 +5486,9 @@ are ignored. @xref{Avoiding Compilation, ,Avoiding Recompilation of Some Files}.@refill @item -p +@cindex @code{-p} @itemx --print-data-base +@cindex @code{--print-data-base} 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 @@ -5423,14 +5496,18 @@ the @samp{-v} switch (see below). To print the data base without trying to remake any files, use @w{@samp{make -p -f /dev/null}}. @item -q +@cindex @code{-q} @itemx --question +@cindex @code{--question} ``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, ,Instead of Executing the Commands}.@refill @item -r +@cindex @code{-r} @itemx --no-builtin-rules +@cindex @code{--no-builtin-rules} Eliminate use of the built-in implicit rules (@pxref{Implicit Rules, ,Using Implicit Rules}). You can still define your own by writing pattern rules (@pxref{Pattern Rules, ,Defining and Redefining Pattern @@ -5440,28 +5517,38 @@ Rules}). But you can still define your own suffixes with a rule for @code{.SUFFIXES}, and then define your own suffix rules. @item -s +@cindex @code{-s} @itemx --silent +@cindex @code{--silent} @itemx --quiet +@cindex @code{--quiet} Silent operation; do not print the commands as they are executed. @xref{Echoing, ,Command Echoing}. @item -S +@cindex @code{-S} @itemx --no-keep-going +@cindex @code{--no-keep-going} @itemx --stop +@cindex @code{--stop} 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, ,Recursive Use of @code{make}}) or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill @item -t +@cindex @code{-t} @itemx --touch +@cindex @code{--touch} Touch files (mark them up to date without really changing them) instead of running their commands. This is used to pretend that the commands were done, in order to fool future invocations of @code{make}. @xref{Instead of Execution, ,Instead of Executing the Commands}. @item -v +@cindex @code{-v} @itemx --version +@cindex @code{--version} Print the version of the @code{make} program plus a copyright, a list of authors, and a notice that there is no warranty. After this information is printed, continue processing normally. To get this @@ -5469,7 +5556,9 @@ information without doing anything else, use @w{@samp{make --version -f /dev/null}}. @item -w +@cindex @code{-w} @itemx --print-directory +@cindex @code{--print-directory} Print a message containing the working directory both before and after executing the makefile. This may be useful for tracking down errors from complicated nests of recursive @code{make} commands. @@ -5478,9 +5567,13 @@ rarely need to specify this option since @samp{make} does it for you; see @ref{-w Option, ,The @samp{--print-directory} Option}.) @item -W @var{file} +@cindex @code{-W} @itemx --what-if @var{file} +@cindex @code{--what-if} @itemx --new @var{file} +@cindex @code{--new} @itemx --assume-new @var{file} +@cindex @code{--assume-new} Pretend that the target @var{file} has just been modified. When used with the @samp{-n} flag, this shows you what would happen if you were to modify that file. Without @samp{-n}, it is almost the same as @@ -5493,6 +5586,7 @@ imagination of @code{make}. @node Implicit Rules, Archives, Running, Top @chapter Using Implicit Rules @cindex implicit rule +@cindex rule, implicit 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 @@ -5548,6 +5642,8 @@ retained for compatibility. @node Using Implicit, Catalogue of Rules, , Implicit Rules @section Using Implicit Rules +@cindex implicit rule, how to use +@cindex rule, implicit, how to use 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 @@ -5585,8 +5681,8 @@ 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 possible dependency files are supposed to exist. -@xref{Catalogue of Rules, ,Catalogue of Implicit Rules}, for a catalogue of all the predefined implicit -rules. +@xref{Catalogue of Rules, ,Catalogue of Implicit Rules}, +for a catalogue of all the predefined implicit rules. Above, we said an implicit rule applies if the required dependencies ``exist or can be made''. A file ``can be made'' if it is mentioned explicitly in @@ -5624,6 +5720,8 @@ commands, you can give that target empty commands by writing a semicolon @node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules @section Catalogue of Implicit Rules +@cindex implicit rule, predefined +@cindex rule, implicit, predefined Here is a catalogue of predefined implicit rules which are always available unless the makefile explicitly overrides or cancels them. @@ -5651,20 +5749,30 @@ for full details on suffix rules. @table @asis @item Compiling C programs +@cindex C, rule to compile +@pindex cc +@pindex gcc @file{@var{n}.o} is made automatically from @file{@var{n}.c} with a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill @item Compiling C++ programs +@cindex C++, rule to compile +@pindex g++ @file{@var{n}.o} is made automatically from @file{@var{n}.cc} or @file{@var{n}.C} with a command of the form @samp{$(C++) -c $(CPPFLAGS) $(C++FLAGS)}. We encourage you to use the suffix @samp{.cc} for C++ source files instead of @samp{.C}.@refill @item Compiling Pascal programs +@cindex Pascal, rule to compile +@pindex pc @file{@var{n}.o} is made automatically from @file{@var{n}.p} with the command @samp{$(PC) -c $(PFLAGS)}.@refill @item Compiling Fortran and Ratfor programs +@cindex Fortran, rule to compile +@cindex Ratfor, rule to compile +@pindex f77 @file{@var{n}.o} is made automatically from @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 @@ -5692,6 +5800,8 @@ program. The precise command used is as follows:@refill @end table @item Compiling Modula-2 programs +@cindex Modula-2, rule to compile +@pindex m2c @file{@var{n}.sym} is made from @file{@var{n}.def} with a command of the form @samp{$(M2C) $(M2FLAGS) $(DEFFLAGS)}. @file{@var{n}.o} is made from @file{@var{n}.mod}; the form is: @@ -5699,6 +5809,8 @@ is made from @file{@var{n}.mod}; the form is: @need 1200 @item Assembling and preprocessing assembler programs +@cindex assembly, rule to compile +@pindex as @file{@var{n}.o} is made automatically from @file{@var{n}.s} by running the assembler, @code{as}. The precise command is @samp{$(AS) $(ASFLAGS)}.@refill @@ -5708,6 +5820,7 @@ running the C preprocessor, @code{cpp}. The precise command used is @w{@samp{$(CPP) $(CPPFLAGS)}}. @item Linking a single object file +@cindex linking, predefined rule for @file{@var{n}} is made automatically from @file{@var{n}.o} by running the linker @code{ld} via the C compiler. The precise command used is @w{@samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES)}}.@refill @@ -5750,10 +5863,14 @@ faster to do the compiling and linking in one step, so that's how it's done.@refill @item Yacc for C programs +@pindex yacc +@cindex Yacc, rule to run @file{@var{n}.c} is made automatically from @file{@var{n}.y} by running Yacc with the command @samp{$(YACC) $(YFLAGS)}. @item Lex for C programs +@pindex lex +@cindex Lex, rule to run @file{@var{n}.c} is made automatically from @file{@var{n}.l} by by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}. @@ -5780,12 +5897,21 @@ the list of implicit rule suffixes with:@refill @end example @item Making Lint Libraries from C, Yacc, or Lex programs +@pindex lint +@cindex @code{lint}, rule to run @file{@var{n}.ln} is made from @file{@var{n}.c} with a command of the form @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}. The same command is used on the C code produced from @file{@var{n}.y} or @file{@var{n}.l}.@refill @item @TeX{} and Web +@cindex @TeX{}, rule to run +@cindex Web, rule to run +@pindex tex +@pindex cweave +@pindex weave +@pindex tangle +@pindex ctangle @file{@var{n}.dvi} is made from @file{@var{n}.tex} with the command @samp{$(TEX)}. @file{@var{n}.tex} is made from @file{@var{n}.web} with @samp{$(WEAVE)}, or from @file{@var{n}.cweb} @@ -5794,12 +5920,18 @@ with @samp{$(CWEAVE)}. @file{@var{n}.p} is made from made from @file{@var{n}.cweb} with @samp{$(CTANGLE)}.@refill @item Texinfo and Info +@cindex Texinfo, rule to format +@cindex Info, rule to format +@pindex texi2dvi +@pindex makeinfo @file{@var{n}.dvi} is made from @file{@var{n}.texinfo} or @file{@var{n}.texi} with the @samp{$(TEXI2DVI)} command. @file{@var{n}.info} is made from @file{@var{n}.texinfo} or @file{@var{n}.texi} with the @samp{$(MAKEINFO)} command .@refill @item RCS +@cindex RCS, rule to extract from +@pindex co Any file @file{@var{n}} is extracted if necessary from an RCS file named either @file{@var{n},v} or @file{RCS/@var{n},v}. The precise command used is @w{@samp{$(CO) $(COFLAGS)}}. @file{@var{n}} will not be @@ -5810,6 +5942,8 @@ so RCS files cannot be generated from another source; they must actually exist.@refill @item SCCS +@cindex SCCS, rule to extract from +@pindex get Any file @file{@var{n}} is extracted if necessary from an SCCS file named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}. The precise command used is @w{@samp{$(GET) $(GFLAGS)}}. The rules for SCCS are @@ -5842,6 +5976,7 @@ Similarly, the rule to produce an executable from a @file{.@var{x}} file uses @code{LINK.@var{x}}; and the rule to preprocess a @file{.@var{x}} file uses @code{PREPROCESS.@var{x}}. +@vindex OUTPUT_OPTION Every rule that produces an object file uses the variable @code{OUTPUT_OPTION}. @code{make} defines this variable either to contain @samp{-o $@@}, or to be empty, depending on a compile-time @@ -5886,22 +6021,27 @@ Here is a table of variables used as names of programs: @item AR @vindex AR Archive-maintaining program; default @samp{ar}. +@pindex ar @item AS @vindex AS Program for doing assembly; default @samp{as}. +@pindex as @item CC @vindex CC Program for compiling C programs; default @samp{cc}. +@pindex cc @item C++ @vindex C++ Program for compiling C++ programs; default @samp{g++}. +@pindex g++ @item CO @vindex CO Program for extracting a file from RCS; default @samp{co}. +@pindex co @item CPP @vindex CPP @@ -5912,23 +6052,28 @@ default @samp{$(CC) -E}. @vindex FC Program for compiling or preprocessing Fortran and Ratfor programs; default @samp{f77}. +@pindex f77 @item GET @vindex GET Program for extracting a file from SCCS; default @samp{get}. +@pindex get @item LEX @vindex LEX Program to use to turn Lex grammars into C programs or Ratfor programs; default @samp{lex}. +@pindex lex @item PC @vindex PC Program for compiling Pascal programs; default @samp{pc}. +@pindex pc @item YACC @vindex YACC Program to use to turn Yacc grammars into C programs; default @samp{yacc}. +@pindex yacc @item YACCR @vindex YACCR @@ -5939,36 +6084,44 @@ programs; default @samp{yacc -r}. @vindex MAKEINFO Program to convert a Texinfo source file into an Info file; default @samp{makeinfo}. +@pindex makeinfo @item TEX @vindex TEX Program to make @TeX{} @sc{dvi} files from @TeX{} source; default @samp{tex}. +@pindex tex @item TEXI2DVI @vindex TEXI2DVI Program to make @TeX{} @sc{dvi} files from Texinfo source; default @samp{texi2dvi}. +@pindex texi2dvi @item WEAVE @vindex WEAVE Program to translate Web into @TeX{}; default @samp{weave}. +@pindex weave @item CWEAVE @vindex CWEAVE Program to translate C Web into @TeX{}; default @samp{cweave}. +@pindex cweave @item TANGLE @vindex TANGLE Program to translate Web into Pascal; default @samp{tangle}. +@pindex tangle @item CTANGLE @vindex CTANGLE Program to translate C Web into C; default @samp{ctangle}. +@pindex ctangle @item RM @vindex RM Command to remove a file; default @samp{rm -f}. +@pindex rm @end table Here is a table of variables whose values are additional arguments for the @@ -6036,6 +6189,7 @@ Extra flags to give to Yacc. @section Chains of Implicit Rules @cindex chains of rules +@cindex rules, implicit, chains of 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}. @@ -6048,6 +6202,7 @@ used. Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are updated.@refill @cindex intermediate file +@cindex files, intermediate 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 @@ -6124,11 +6279,14 @@ Variables}, and @ref{Functions, ,Functions for Transforming Text}. @node Pattern Intro, Pattern Examples, , Pattern Rules @subsection Introduction to Pattern Rules @cindex pattern rule +@cindex rule, pattern A pattern rule contains the character @samp{%} (exactly one of them) in the target; otherwise, it looks exactly like an ordinary rule. The target is a pattern for matching file names; the @samp{%} matches any nonempty substring, while other characters match only themselves. +@cindex target pattern +@cindex @code{%}, in pattern rules 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 @@ -6141,6 +6299,7 @@ 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. +@cindex dependency pattern Thus, a rule of the form @@ -6172,6 +6331,8 @@ than the one that matches the target in need of a rule are incidental: @code{make} worries only about giving commands and dependencies to the file presently in question. However, when this file's commands are run, the other targets are marked as having been updated themselves. +@cindex multiple targets, in pattern rule +@cindex targets, multiple in pattern rule The order in which pattern rules appear in the makefile is important because the rules are considered in that order. Of equally applicable @@ -6179,6 +6340,8 @@ 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. +@cindex pattern rules, order of +@cindex order of pattern rules @node Pattern Examples, Automatic, Pattern Intro, Pattern Rules @subsection Pattern Rule Examples @@ -6240,6 +6403,8 @@ dependencies, and it will execute happily ever after.)@refill @node Automatic, Pattern Match, Pattern Examples, Pattern Rules @subsection Automatic Variables @cindex automatic variables +@cindex variables, automatic +@cindex variables, and implicit rules 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 @@ -6255,42 +6420,53 @@ for the source file name. Here is a table of automatic variables: @table @code -@cindex @code{$@@} +@vindex $@@ +@vindex @@ @r{(automatic variable)} @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. -@cindex @code{$%} +@vindex $% +@vindex % @r{(automatic variable)} @item $% The target member name, when the target is an archive member. @xref{Archives}. 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. -@cindex @code{$<} +@vindex $< +@vindex < @r{(automatic variable)} @item $< The name of the first dependency. If the target got its commands from an implicit rule, this will be the first dependency added by the implicit rule (@pxref{Implicit Rules}). -@cindex @code{$?} +@vindex $? +@vindex ? @r{(automatic variable)} @item $? The names of all the dependencies that are newer than the target, with spaces between them. For dependencies which are archive members, only the member named is used (@pxref{Archives}). +@cindex dependencies, list of changed +@cindex list of changed dependencies -@cindex @code{$^} +@vindex $^ +@vindex ^ @r{(automatic variable)} @item $^ The names of all the dependencies, with spaces between them. For dependencies which are archive members, only the member named is used (@pxref{Archives}). +@cindex dependencies, list of all +@cindex list of all dependencies -@cindex @code{$*} +@vindex $* +@vindex * @r{(automatic variable)} @item $* The stem with which an implicit rule matches (@pxref{Pattern Match, ,How Patterns 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 +@cindex stem, variable for In a static pattern rule, the stem is part of the file name that matched the @samp{%} in the target pattern. @@ -6320,7 +6496,6 @@ lib: foo.o bar.o lose.o win.o @end group @end example - Of the variables listed above, four have values that are single file names, and two have values that are lists of file names. These six have variants that get just the file's directory name or just the file @@ -6333,7 +6508,7 @@ variants:@refill @table @samp @vindex $(@@D) -@vindex @@D +@vindex @@D @r{(automatic variable)} @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/}. @@ -6341,26 +6516,26 @@ This value is @file{./} if @samp{$@@} does not contain a slash. @samp{$(@@D)} is equivalent to @w{@samp{$(dir $@@)}}.@refill @vindex $(@@F) -@vindex @@F +@vindex @@F @r{(automatic variable)} @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 $@@)}. @vindex $(*D) -@vindex *D +@vindex *D @r{(automatic variable)} @item $(*D) @vindex $(*F) -@vindex *F +@vindex *F @r{(automatic variable)} @itemx $(*F) The directory part and the file-within-directory part of the stem; @file{dir/} and @file{foo} in this example. @vindex $(%D) -@vindex %D +@vindex %D @r{(automatic variable)} @item $(%D) @vindex $(%F) -@vindex %F +@vindex %F @r{(automatic variable)} @itemx $(%F) The directory part and the file-within-directory part of the target archive member name. This makes sense only for archive member targets @@ -6369,28 +6544,28 @@ of the form @file{@var{archive}(@var{member})} and is useful only when ,Archive Members as Targets}.) @vindex $(<D) -@vindex <D +@vindex <D @r{(automatic variable)} @item $(<D) @vindex $(<F) -@vindex <F +@vindex <F @r{(automatic variable)} @itemx $(<F) The directory part and the file-within-directory part of the first dependency. @vindex $(^D) -@vindex ^D +@vindex ^D @r{(automatic variable)} @item $(^D) @vindex $(^F) -@vindex ^F +@vindex ^F @r{(automatic variable)} @itemx $(^F) Lists of the directory parts and the file-within-directory parts of all dependencies. @vindex $(?D) -@vindex ?D +@vindex ?D @r{(automatic variable)} @item $(?D) @vindex $(?F) -@vindex ?F +@vindex ?F @r{(automatic variable)} @itemx $(?F) Lists of the directory parts and the file-within-directory parts of all dependencies that are newer than the target. @@ -7439,53 +7614,30 @@ dependencies which are archive members, only the member named is used (@pxref{Archives}). @item $* -The stem with which an implicit rule matches (@pxref{Pattern Match, ,How Patterns Match}). +The stem with which an implicit rule matches +(@pxref{Pattern Match, ,How Patterns Match}). -@vindex $(@@D) -@vindex @@D @item $(@@D) -@vindex $(@@F) -@vindex @@F @itemx $(@@F) The directory part and the file-within-directory part of @code{$@@}. -@vindex $(*D) -@vindex *D @item $(*D) -@vindex $(*F) -@vindex *F @itemx $(*F) The directory part and the file-within-directory part of @code{$*}. -@vindex $(%D) -@vindex %D @item $(%D) -@vindex $(%F) -@vindex %F @itemx $(%F) The directory part and the file-within-directory part of @code{$%}. -@vindex $(<D) -@vindex <D @item $(<D) -@vindex $(<F) -@vindex <F @itemx $(<F) The directory part and the file-within-directory part of @code{$<}. -@vindex $(^D) -@vindex ^D @item $(^D) -@vindex $(^F) -@vindex ^F @itemx $(^F) The directory part and the file-within-directory part of @code{$^}. -@vindex $(?D) -@vindex ?D @item $(?D) -@vindex $(?F) -@vindex ?F @itemx $(?F) The directory part and the file-within-directory part of @code{$?}. @end table |