summaryrefslogtreecommitdiff
path: root/make.texinfo
diff options
context:
space:
mode:
Diffstat (limited to 'make.texinfo')
-rw-r--r--make.texinfo100
1 files changed, 96 insertions, 4 deletions
diff --git a/make.texinfo b/make.texinfo
index 1e61183..b77afcf 100644
--- a/make.texinfo
+++ b/make.texinfo
@@ -269,6 +269,7 @@ Functions for Transforming Text
* Text Functions:: General-purpose text manipulation functions.
* File Name Functions:: Functions for manipulating file names.
* Foreach Function:: Repeat some text with controlled variation.
+* Apply Function:: Expand a user-defined function.
* Origin Function:: Find where a variable got its value.
* Shell Function:: Substitute the output of a shell command.
@@ -5199,6 +5200,7 @@ call, just as a variable might be substituted.
* Text Functions:: General-purpose text manipulation functions.
* File Name Functions:: Functions for manipulating file names.
* Foreach Function:: Repeat some text with controlled variation.
+* Apply Function:: Expand a user-defined function.
* Origin Function:: Find where a variable got its value.
* Shell Function:: Substitute the output of a shell command.
* Make Control Functions:: Functions that control how make runs.
@@ -5224,8 +5226,9 @@ or like this:
$@{@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.
+Here @var{function} is a function name; one of a short list of names
+that are part of @code{make}. You can also essentially create your own
+functions by using the @code{apply} builtin function.
The @var{arguments} are the arguments of the function. They are
separated from the function name by one or more spaces or tabs, and if
@@ -5746,7 +5749,7 @@ that match the pattern.
@xref{Wildcards, ,Using Wildcard Characters in File Names}.
@end table
-@node Foreach Function, Origin Function, File Name Functions, Functions
+@node Foreach Function, Apply Function, File Name Functions, Functions
@section The @code{foreach} Function
@findex foreach
@cindex words, iterating over
@@ -5834,7 +5837,96 @@ might be useful if the value of @code{find_files} references the variable
whose name is @samp{Esta escrito en espanol!} (es un nombre bastante largo,
no?), but it is more likely to be a mistake.
-@node Origin Function, Shell Function, Foreach Function, Functions
+@node Apply Function, Origin Function, Foreach Function, Functions
+@section The @code{apply} Function
+@findex apply
+@cindex functions, user defined
+@cindex user defined functions
+
+The @code{apply} function is unique in that it can be used to create new
+parameterized functions. You can write a complex expression as the
+value of a variable, then use @code{apply} to expand it with different
+values.
+
+The syntax of the @code{apply} function is:
+
+@example
+$(apply @var{variable}, @var{param}, @var{param}, @dots{})
+@end example
+
+When @code{make} expands this function, it assigns each @var{param} to
+temporary variables @var{$(1)}, @var{$(2)}, etc. The variable
+@var{$(0)} will contain @var{variable}. There is no maximum number of
+parameter arguments. There is no minimum, either, but it doesn't make
+sense to use @code{apply} with no parameters.
+
+Then @var{variable} is expanded as a @code{make} variable in the context
+of these temporary assignments. Thus, any reference to @var{$(1)} in
+the value of @var{variable} will resolve to the first @var{param} in the
+invocation of @code{apply}.
+
+Note that @var{variable} is the @emph{name} of a variable, not a
+@emph{reference} to that variable. Therefore you would not normally use
+a @samp{$} or parentheses when writing it. (You can, however, use a
+variable reference in the name if you want the name not to be a
+constant.)
+
+If @var{variable} is the name of a builtin function, the builtin function
+is always invoked (even if a @code{make} variable by that name also
+exists).
+
+Some examples may make this clearer.
+
+This macro simply reverses its arguments:
+
+@smallexample
+reverse = $2 $1
+
+foo = a b
+bar = $(apply reverse,$(foo))
+@end smallexample
+
+@noindent
+Here @var{bar} will contain @samp{b a}.
+
+This one is slightly more interesting: it defines a macro to search for
+the first instance of a program in @code{PATH}:
+
+@smallexample
+pathsearch = $(firstword $(wildcard $(addsufix /$1,$(subst :, ,$(PATH)))))
+
+LS := $(apply pathsearch,ls)
+@end smallexample
+
+@noindent
+Now the variable LS contains @code{/bin/ls} or similar.
+
+The @code{apply} function can be nested. Each recursive invocation gets
+its own local values for @var{$(1)}, etc. that mask the values of
+higher-level @code{apply}. For example, here is an implementation of a
+@dfn{map} function:
+
+@smallexample
+map = $(foreach a,$2,$(apply $1,$a))
+@end smallexample
+
+Now you can @var{map} a function that normally takes only one argument,
+such as @code{origin}, to multiple values in one step:
+
+@smallexample
+o = $(apply map,origin,o map MAKE)
+@end smallexample
+
+and end up with @var{o} containing something like @samp{file file default}.
+
+A final caution: be careful when adding whitespace to the arguments to
+@code{apply}. As with other functions, any whitespace contained in the
+second and subsequent arguments is kept; this can cause strange
+effects. It's generally safest to remove all extraneous whitespace when
+defining variables for use with @code{apply}.
+
+
+@node Origin Function, Shell Function, Apply Function, Functions
@section The @code{origin} Function
@findex origin
@cindex variables, origin of