From a20cb3e18966a37b0d030d509f2b72074d532eb8 Mon Sep 17 00:00:00 2001 From: Roland McGrath Date: Sun, 22 May 1988 12:29:23 +0000 Subject: Static pattern rules section rewritten by RMS. --- make.texinfo | 205 +++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 128 insertions(+), 77 deletions(-) diff --git a/make.texinfo b/make.texinfo index 78a0942..1755299 100644 --- a/make.texinfo +++ b/make.texinfo @@ -6,7 +6,10 @@ $Header$ $Log$ -Revision 1.22 1988/05/20 17:00:49 mcgrath +Revision 1.23 1988/05/22 12:29:23 mcgrath +Static pattern rules section rewritten by RMS. + +Revision 1.22 88/05/20 17:00:49 mcgrath Documented extended static rules. Revision 1.17 88/05/18 16:26:55 mcgrath @@ -184,8 +187,6 @@ be recompiled, or how. @xref{Running}. * Implicit:: Implicit rules take over if the makefile doesn't say how a file is to be remade. -* Static:: Extended static rules provide a compromise between explicit - rules and implicit rule assumptions. * Archives:: How to use @code{make} to update archive files. * Missing:: Features of other @code{make}s not supported by GNU @code{make}. @@ -604,6 +605,9 @@ or all the programs described by the makefile. @xref{Goals}. * 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. @@ -1220,7 +1224,12 @@ both pieces to the suffix list. In practice, suffixes normally begin with @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. This is useful in two cases. +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 @@ -1235,8 +1244,9 @@ gives an additional dependency to each of the three object files mentioned. @item -Identical commands work for all the targets. The automatic variable -@samp{$@@} can be used to substitute the target to be remade into the +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: @example @@ -1260,7 +1270,117 @@ types of output, one if given @samp{-big} and one if given @samp{-little}.@refill @end itemize -@node Multiple Rules, Double-Colon, Multiple Targets, Rules +@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}. + +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 +Here @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{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 + +@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. @@ -3999,76 +4119,7 @@ The name of the first dependency that came via the implicit rule. For @code{.DEFAULT} commands, as for non-implicit commands, @samp{$*} and @samp{$<} are empty. @samp{$@@} is @var{t}, as always. -@node Static, Archives, Implicit, Top -@chapter Extended Static Rules -@cindex extended static rules -@cindex static rules -@cindex explicit rules - -@dfn{Static rules}, or @dfn{explicit rules} are simple rules where you give -the dependencies and commands for the targets. @dfn{Implicit rules} -(@pxref{Implicit}) are rules generated by @code{make} for which you specify -only the target (and perhaps some implicit rules in addition to the -standard set), and the dependencies and commands are figured out for you. -@dfn{Extended static rules} provide a compromise between these two types of -rules. They have the flexibility of implicit rules, but do not depend on -the contents of any directory to determine what is made from what. - -Extended static rules are basically implicit rules that are applied to a -limited set of targets, rather than just any target that has no commands of -its own. The syntax of this type of rule follows directly from this -explanation: - -@example -@var{targets}: @var{target-pattern}: @var{dep} @dots{}; @var{command} - @var{command} - @dots{} -@end example - -The first part of this rule, ``@var{targets}:'' gives the list of targets -that the rule applies to. These targets are filenames, possibly containing -wildcard characters, just like the targets of ordinary explicit rules. -The rest of the rule resembles an implicit pattern rule. It has a target -pattern containing a @samp{%} character and dependency filenames, each of -which may contain a @samp{%} which is replaced by what matched the @samp{%} -in the target pattern. - -In extended static rules, each target 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 @samp{filter} -function to remove nonmatching filenames: - -@example -files := foo.elc bar.o - -$(filter %.o,$(files)): %.o: %.c; cc $< -o $@@ -$(filter %.elc,$(files)): %.elc: %.el; el-compile $< -o $@@ -@end example - -This type of rule is better than implicit rules in some situations -for a few reasons: - -@itemize @bullet -@item -You may wish to have a different pattern rule apply to one set of files -than applies to all others. - -@item -If you cannot be sure of the contents of the directories in which your -targets reside (or those listed in @code{vpath} search paths or the -@code{VPATH} variable; @pxref{Directory Search}), you may want to -circumvent possible unintended actions by @code{make} resulting from the -wrong implicit rule matching. - -@item -You may simply be of the opinion that implicit rules are inherently not -particularly wonderful and would rather tell @code{make} exactly what to do -with what, but without all the trouble of ordinary explicit rules. -(This is included because that appears to be the opinion of the person who -originally suggested the concept of extended static rules.) -@end itemize - -@node Archives, Missing, Static, Top +@node Archives, Missing, Implicit, Top @chapter Using @code{make} to Update Archive Files @cindex archive -- cgit v1.2.3