Provided by: makepp_2.0.98.5-1_all bug

NAME

       makepp_functions -- Functions in makepp

DESCRIPTION

       A: absolute_filename,
         absolute_filename_nolink,
         abspath,
         addprefix,
         addsuffix,
         and,  B: basename,  C: call,  D: dir,
         dir_noslash,  E: error,  F: filesubst,
         filter,
         filter_out,
         filter_out_dirs,
         findfile,
         find_first_upwards,
         find_program,
         findstring,
         find_upwards,
         first_available,
         firstword,
         foreach,  I: if,
         iftrue,
         infer_linker,
         infer_objects,
         info,  J: join,  M: make,
         makemap,
         makeperl,
         map,
         "mktemp",  N: notdir,  O: only_generated,
         only_nontargets,
         only_phony_targets,
         only_stale,
         only_targets,
         or,
         origin,  P: patsubst,
         perl,
         phony,
         prebuild,
         print,  R: realpath,
         relative_filename,
         relative_to,  S: shell,
         sort,
         strip,
         subst,
         suffix,  T: temporary,  W: warning,
         wildcard,
         word,
         wordlist,
         words,  X: xargs

       Any expression of the format "$(name)", where "name" is not the name of a variable, or
       "$(name arg1 arg2 arg3)" is interpreted as a function call.  The name may contain letters,
       underscores, or hyphens; to avoid confusion, you may use hyphens or underscores
       interchangeably, since internally hyphens are converted to underscores.  Evaluating such
       an expression simply invokes a Perl subroutine.  If "name" is preceded by "&" it runs the
       builtin command or script of that name within the makepp process, and returns the standard
       output.  This requires perl to be built for PerlIO.  If the name does not name a function
       it is transformed to an invocation of call.

       As with variables you have a choice of "$(name ...)" or "${name ...}".  If you want to
       embed the same parenthesis, it must be paired, the other doesn't matter: "$(name
       ...(){..." or "${name ...{}(...}".  (However for map and perl the first closing paren ends
       the expression.)  Doubling allows the arguments to span several lines.  The newlines are
       then treated as spaces, except maybe in "define".  There is also the syntax "$[name ...]"
       or $[[name ...]], which gets evaluated while reading the makefile, before grokking rules
       and other constructs.

       Makepp has a number of builtin functions which may be useful.  It supports almost all of
       GNU make's textual functions (see GNU make's documentation for details), and some of its
       own.  You can define Perl subroutines to do whatever you like.  See the "sub" statement
       and the section on extending makepp for more details.

   Conditional Functions
       and condition1[,condition2[,condition3...]]
           The and function provides a "short-circuiting" AND operation. Each argument is
           expanded, in order. If an argument expands to an empty string the processing stops and
           the result of the expansion is the empty string. If all arguments expand to a non-
           empty string then the result of the expansion is the expansion of the last argument.

       if string, result-if-string-not-blank[, result-if-string-blank]
       iftrue string, result-if-string-true[, result-if-string-false]
           An alternative to the "ifeq", etc., statements.  If the string is not blank (i.e., the
           condition is true), the second argument (the "then" clause) is returned (after
           variable expansion); if the string is blank, the third argument (the "else" clause) is
           returned.

           For example,

               CFLAGS := $(if $(filter gcc egcc, $(CC)), -g -Wall, -g)

           defines CFLAGS to be "-g -Wall" if the variable CC is either "gcc" or "egcc", and "-g"
           otherwise.  (This is what the default build rules do.)

           "iftrue" is similar to "if", except that the string 0 is treated as blank.

       or condition1[,condition2[,condition3...]]
           The or function provides a "short-circuiting" OR operation. Each argument is expanded,
           in order. If an argument expands to a non-empty string the processing stops and the
           result of the expansion is that string. If, after all arguments are expanded, all of
           them are false (empty), then the result of the expansion is the empty string.

   File and Filename Functions
       absolute_filename files
       abspath files
           Converts relative filenames into absolutes without . or ...  For example,
           "$(absolute_filename xyz.c)" might return "/usr/src/our_project/subdir/xyz.c".

       absolute_filename_nolink files
       realpath files
           Like absolute_filename, but ensures that symbolic links are resolved.

       basename filenames
           The basename is the entire file name (with the directory), minus the text after and
           including the last period.  E.g., "$(basename myfile/version-1.0-module.c)" is
           "myfile/version-1.0-module"

       dir filenames
           Extracts the directory part of each file in the filename list, including the trailing
           slash.  Returns "./" if there is no directory in the filename.

       dir_noslash filename
           Same as "$(dir )" except that it doesn't return the trailing slash.

       filesubst pattern, substitute, words
           Perform a pattern substitution on file names.      This differs from patsubst in that
           it will perform correctly when alternate names for directories are given (as long as
           they precede the percent sign).  For example,

               $(filesubst ./src/%.c, %.o, $(wildcard src/*.c))

           will work with filesubst but not with patsubst.

       filter_out_dirs filenames
           Returns all filenames that do not refer to directories.

       findfile filename, path
           Finds a file in the specified path, or in the environment variable PATH if nothing is
           specified.  This can be useful for finding binaries or include files.  For example,

               TCL_INCLUDE := -I$(dir_noslash $(findfile tcl.h, \
                   /usr/local/stow/tcl-8.4.5-nothread/include \
                   /usr/include/tcl8.4 /usr/include/tcl \
                   /net/na1/tcl8.4a3/include /net/na1/tcl8.4a3/include))

           This locates the file tcl.h by searching all of the above directories.  The absolute
           path to the file is returned.  Then "$(dir_noslash )" extracts that directory, and it
           is put into the include path.

       find_program name
           Return the first program in the list that can be found in the PATH.  This is useful
           when there are multiple equivalent programs that may be used, and you just want to
           pick one of them.  For example, here is the default definition of several common
           variables that makepp supplies if you do not put one in your makefile:

               CC = $(find_program gcc egcc pgcc c89 cc) # and more, depending on machine
               F77 = $(find_program f77 g77 fort77)
               CXX = $(find_program g++ c++ pg++ cxx CC aCC)

           If none of the programs is found, "$(find_program )" returns the string not-found, and
           logs what was not found.  This usually won't result in a functional makefile, but it
           will tend to make for better error messages.  For example, if you do something like
           this:

               %.o : %.c
                   $(CC) $(inputs) -o $(outputs)

           and makepp can't find a C compiler in the list above, it will substitute not-found.
           Otherwise the shell would attempt to execute the source file and the resulting error
           message might be really strange.

       find_upwards filename
           Searches for a file of the given name in the directory ., .., ../.., ../../.., etc.,
           until the file is found or the root directory is reached or the directory is located
           on a different file system.  (This last requirement is to prevent problems with
           automounters or hung network filesystems.)  If you have a RootMakeppfile, that is also
           a barrier which prevents searching higher.

           For example, if you have a project with many levels of subdirectories, you could
           include this common fragment in all of the makefiles (e.g., by using the "include"
           statement):

               TOP_LEVEL_INCLUDE_DIR := $(find_upwards includes)
                                           # Searches for a directory that contains the
                                           # includes subdirectory.

               %.o : %.c
                   $(CC) $(CFLAGS) -I$(TOP_LEVEL_INCLUDE_DIR) -c $(input) -o $(output)

           Another problem that "find_upwards" can help solve is locating the top-level directory
           of a build.  Often it is useful to define a variable like this:

               TOP := ../../..

           if you have some important information located only in the top-level directory.  But
           this is hard to maintain, because the number of ".." is different for different levels
           of the directory tree.  Instead, you can use "find_upwards" to locate a file which is
           known to be present only in the top level directory.  Suppose, for example, that the
           file "LICENSE" is located only in the top level directory.  Then you could do this:

               TOP := $(dir_noslash $(find_upwards LICENSE))

           "$(find_upwards LICENSE)" returns the full path of the license file;
           "$(dir_noslash ...)" strips off the filename, returning only the directory.

           (Note that the "include" statement automatically searches upwards for files, so there
           is no need to do something like this:

               include $(find_upwards top_level_rules.mk)

           Instead, you can just do

               include top_level_rules.mk

           and it will work just as well.)

           If the file is not found, "find_upwards" will abort the build with an error message.

           If you specify more than one file, find_upwards will search for the first one, then
           the second one, and so on.  In other words,

               $(find_upwards file1 file2)

           is equivalent to

               $(find_upwards file1) $(find_upwards file2)

           If you want to look for any one of the files, then use "find_first_upwards" instead.

       find_first_upwards file1 file2 ...
           This function behaves like "find_upwards" except that it returns the first file of any
           files in the list that it finds.  Specifically, it checks the current directory for
           any of the files in the list, and returns the first file which exists or can be built.
           If none of the files exist or can be built in that directory, it checks .., then
           ../.., etc., until it reaches either the root directory or a directory which is
           located on a different file system.

       first_available file1 file2 ...
           Return the first file in a list that exists or can be built.  This can be useful for
           adapting your makefiles to work on several different machines or networks, where
           important files may be located in different places.  For example, here's a line from
           one of my makefiles:

               TCL_LIB = $(first_available \
                   /usr/local/stow/tcl-8.4.5-nothread/lib/libtcl8.4.so \
                   /usr/lib/libtcl8.4.so /usr/lib/libtcl.so \
                   /net/na1/tcl8.4a3/lib/libtcl8.4.a \
                   /net/na1/tcl8.4a3/lib/libtcl8.4.sl)

           This line will check for the Tcl library in all of the above places, stopping at the
           first one that it finds.  The link command then includes $(TCL_LIB) so we get the
           appropriate Tcl library.

       infer_linker file1 file2 ...
           Given a list of object files first build them if they have not been yet.  Then find
           whether they depend on a Fortran, C++ or a C source and return the corresponding
           compiler (which better knows how to link than "ld").

       infer_objects file1 file2 ..., pattern
               $(infer_objects object1.o object2.o, *.o)

           If you use standard conventions regarding header file names, makepp is capable of
           guessing which ".o" or ".lo" files need to be linked with your program.  I use this to
           pick out files from a library directory which contains modules used in many different
           programs.  Instead of making a library ".a" file and having the linker pick out the
           relevant modules, makepp can pick out the relevant modules for you.  This way, only
           the relevant modules get compiled.

           Makepp's algorithm for inferring object dependencies depends on the convention that
           the implementation of all classes or functions defined in a header file "xyz.h" are
           compiled into an object file called "xyz.o" (or "xyz.lo").  So makepp's algorithm for
           inferring object dependencies starts with one or a few objects that we know have to be
           linked into the program.  It looks at which files were included with "#include" in
           those sources, and tries to find corresponding object files for each of the include
           files.

           "$(infer_objects )" needs to be mentioned in the dependency list of a program, like
           this:

               myprog: $(infer_objects main.o another_object.o, \
                           **/*.o /other/library/dirs/**/*.o)
                   $(CXX) $(inputs) -o $(output) $(LIBS)

           The "$(infer_objects)" function takes two arguments (separated by a comma, as shown).
           The first is one or a few object files that are known to be required (wildcards are
           permissible here).  The second is a list of possible objects (normally you would use a
           wildcard here) that could be linked in if necessary.  The return value from this
           function is a list that contains first all of the objects in the first argument, and
           then after those, all additional objects that were contained in the second argument
           that are required by the objects in the first argument.

           For example, suppose "main.o" comes from "main.cpp", which includes "my_class.h".
           "$(infer_objects)" looks for files with the name "my_class.o".  If exactly one such
           file is found, it is added to the list.  (If two object files "my_class.o" are found
           in different directories, a warning message is printed.)  "infer_objects" also
           examines "my_class.cpp" to see what it includes, and what additional object files are
           implied.

       mktemp
       mktemp prefix
       mktemp prefixXXX
       mktemp /
           Returns an unpredictable temporary filename, which does not currently exist.  No name
           pointing to the same file is returned twice, even with different relative paths,
           within one makepp run (except possibly with traditional recursive make, or if Perl
           code running within a rule action calls "f_mktemp").  At the end of the makepp run all
           files returned by this function are deleted, if they exist (again except for those
           returned by this function in Perl code running within a rule).

           Any number of upper case "X"s at the end of the argument are replaced by that many
           random letters and digits.  The more there are, the less likely this is to collide
           with other processes, so if you give a prefix like "/tmp/abc.", you should have enough
           "X"s.  If there is more than one X, the first character comes from the process id.  If
           there are none, it is as though there were ten, which is supposedly enough (8.4e17
           possibilities or 3.7e15 on Windows).  If there is no argument, the prefix defaults to
           "tmp." in the current directory.

           Note that you don't want to give such a name as rule targets and dependencies.  The
           result would be correct, but it would be recreated every time you run makepp.

           Also, as it is always different, you should use this in a rule action only if you use
           ":build_check ignore_action":

               TMPFILE ;= $(mktemp)        # 1 call; "=" would mean 3 calls: 3 files
               A-count B-count: :build_check ignore_action
                   produce-As-and-Bs >$(TMPFILE)
                   &grep -c /A/ $(TMPFILE) -o A-count
                   &grep -c /B/ $(TMPFILE) -o B-count

           Or you should export it and let the Shell evaluate it:

               export TMPFILE ;= $(mktemp)
               A-count B-count:
                   produce-As-and-Bs >$$TMPFILE # makepp doesn't see the var value
                   fgrep -c A $$TMPFILE >A-count
                   fgrep -c B $$TMPFILE >B-count

           The last form repeats the previous return value, so you can use it in a pattern rule:

               %.x: %.y
                   &grep foo $(input) -o $(mktemp)
                   &sed bar $(mktemp /) -o $(output) # Operate on the output of &grep

       notdir filenames
           Returns the non-directory portion of the filename(s), i.e., everything after the last
           slash if there is one, or the whole filename otherwise.

       only_generated filenames
           Returns only those filenames in the list that were generated by makepp and not since
           modified, according to the build info file.

           This function is useful in clean target rules (though of course "makeppclean" is the
           preferred variant):

               $(phony clean):
                   &rm -f $(only_generated **/*)

       only_nontargets filenames
           Returns only those filenames in the list that are not targets of any rule (either
           explicit or pattern rules).  You may specify a wildcard (see the "$(wildcard )"
           function for more details on makepp's wildcards).  This can be used for generating a
           distribution target, for example:

               .PHONY: distribution

               distribution:
                   &mkdir our_product-$(VERSION)
                   &cp $(filter-out %~, $(only_nontargets *)) our_product-$(VERSION)
                   tar cf - our_product-$(VERSION) | gzip -9c > our_product-$(VERSION).tar.gz

           In this case, the "$(only_nontargets *)" returns every file in the current directory
           that is not a target of some rule.  The "$(filter_out %~, ...)"  removes editor
           backups.

           Similar to "only_targets" (see above), "only_nontargets" only knows about targets that
           have been defined already.  This is only a problem if you use it to define variables
           with the ":=" assignment; if you use it in the dependency list or in the body of a
           rule, all other rules will already have been seen.

       only_stale filenames
           Returns only those filenames in the list that were generated by makepp and not since
           modified, according to the build info file, but are no longer targets of any rule.

           This function is useful for ensuring that there are no dependencies on such files,
           without forcing a clean build of all of the targets:

               $(phony flush):
                   &rm -f $(only_stale **/*)

           Actually, it's probably better instead to write a script that calls makepp to generate
           the list of stale files, and then have that script remove all of the listed files that
           aren't currently under source control, just in case a generated file becomes a source
           file. Makepp doesn't have such a function built in because makepp is (and probably
           ought to remain) agnostic about source control.

       only_targets filenames
           Returns only those filenames in the list that are actually targets of some rule
           (either explicit or pattern rules).  You may specify wildcards (including makepp's
           special wildcard, "**") in the filenames.  (See the "$(wildcard )" function for more
           details.  This can be used for a clean target, for example:

               .PHONY: clean

               clean:
                   &rm -f $(only_targets *)

           Now if you type "makepp clean", it will delete everything it knows how to build.  But
           don't create a clean target, use "makeppclean" instead!

           Another place where it may be useful is to avoid including stale .o files in your
           build.  For example, if you build a library like this:

               mylib.a: *.o
                   &rm -f $(output)
                   $(AR) cr $(output) $(inputs)

           and then you delete some source files but forget to delete the corresponding .o files,
           the .o files will still be around.  This means they will still be incorporated into
           the library despite the fact that they are not useful any more.  If you modify your
           rule like this:

               mylib.a: $(only_targets *.o)
                   &rm -f $(output)
                   $(AR) cr $(output) $(inputs)

           then this problem won't occur.

           Note that this refers only to files that are known to be targets at the time you
           invoke "only-targets".  If "only_targets" appears in the dependencies or actions of a
           rule, then all possible targets will be known because dependencies and actions are not
           evaluated until the rule is executed.  However, if you evaluate try to evaluate it
           earlier in the makefile with a ":=" variable like this:

               ALL_TARGETS := $(only_targets *)

               target1: dependency1
                   actions

               target2: dependency2
                   actions

           then "only_targets" will not know about the subsequent rules.

           Similarly, "only_targets" doesn't know about targets produced in makefiles that are
           loaded with recursive make.  (But you shouldn't be using recursive make anyway; use
           use the "load_makefile" statement, or implicit makefile loading instead.)

       relative_filename file1 file2 file3[, slash]
           Returns the name of those files relative to the current directory (the one the
           makefile is in).  This can also be used to clean unnecessary "./" and other junk from
           the path:

               DIR := .
               SUBDIR := ..
               FNAME := $(DIR)/../otherdir/$(SUBDIR)/files
               X := $(relative_filename $(FNAME))

           If slash is true (usually 1) the returned filenames are guaranteed to contain a slash
           by prepending "./" if necessary, so that you can use it as an executable name without
           worrying about the command search path overriding the directory location.

           If the path goes by the root directory, the parent of either your home directory or
           the "$(ROOT)" of your build system, or on Windows a drive's root (depending on the
           environment, this also happens for /cygdrive/c or /c), an absolute path will be
           returned instead.

       relative_to file1 file2 file3[, directory]
           Returns the name of those files relative to the specified directory.  This is
           typically useful when for whatever reason you have to execute a command from a
           different directory (default current directory):

               source_backup.tar:
                   cd .. && tar cf $(relative_to $(output), ..) $(relative_to ., ..)

       suffix names...
           Extracts the suffix of each file name in 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 names is not,
           and if names contains multiple file names, the result may contain fewer file names.

           For example,

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

           produces the result ".c .c".

       temporary words
           Let makepp know that the specified targets may be removed by the rule that generates
           them.  Similar to "phony", except that makepp expects that a real file of that name
           will may be affected by the rule.  A rule is not executed if only its temporary
           targets are out-of-date.

       wildcard pattern
           Returns the sorted names of all files matching the given pattern which exist, or those
           files which do not yet exist but can be built based on the rules that makepp knows
           about at the point when it evaluates the expression.  In this last point it differs
           from rule input wildcards, which apply even to files created by rules found later.

           Makepp supports all the usual shell wildcards ("*", "?", and "[]").  It also has a
           wildcard "**" which matches any number of intervening directories.  (This idea was
           stolen from zsh.)  For example, "**/*.c" matches all the .c files in the entire source
           tree.  "objects/**/*.o" matches all the .o files contained anywhere in the
           subdirectory objects or any of its subdirectories or any of their subdirectories.  The
           "**" wildcard will not follow soft links to directories at any level, nor will it
           attempt to enter directories which exist but cannot be read.  Also files and
           directories which exist but cannot be read will not be returned by "$(wildcard )".

   String Functions
       addprefix prefix, words
           Prepends the prefix string to each of the words.  This is mostly for GNU make
           compatibility; using rc-style expansion, this can be done in a more readable fashion
           like this:

               MODULES := a b c d
               X_OLD_STYLE := $(addprefix $(OBJDIR)/, $(addsuffix .o, $(MODULES)))
               X_NEW_STYLE := $(OBJDIR)/$(MODULES).o   # Isn't that easier to read?

       addsuffix suffix, words
           Appends the suffix string to each of the words.  This is mostly for GNU make
           compatibility; using rc-style expansion, this can be done in a more readable fashion
           like this:

               X_OLD_STYLE := $(addsuffix .o, $(MODULES))
               X_NEW_STYLE := $(MODULES).o

       call variable[, words]...
           The function "call" is unique in that it can be used to regard variable as a
           parameterized function.  You can assign a complex expression to variable and use
           "call" to expand its contents to different values parametrized by words later on.  In
           other make systems, a variable that is used mainly for the purpose to be expanded via
           "call", is called a macro.

           During expansion of the macro, the temporary variables $1, $2, "..." refer to the
           arguments given to "call" during its invocation.  The variable $0 will be expanded to
           the name of the macro (i.e. variable) that "call" is currently expanding.

           There is no limit, how many arguments a macro may be "call"ed with or how many
           parameters a macro may expect.  If you pass more arguments to "call" as the macro
           need, all exceeding arguments will be discarded.  If you pass less arguments than a
           macro expect, all exceeding parameters collapse into the empty string.

           First a simple example:

               rest = $(wordlist 2, $(words $(1)),$(1))
               list = A B C D E
               butfirst := $(call rest,$(list))

           Here, the variable "$(butfirst)" will contain the list "B C D E".

           And now for a more complex example to show what is possible:

               rest = $(wordlist 2,$(words $(1)),${1})
               mymap = $(if $2,$(call $1,$(firstword $2)) $(call $0,$1,$(call rest,$2)))
               downcase = ${makeperl lc("$1")}

               UCWORDS = ALL THESE WORDS ARE UPCASE
               DCWORDS := $(call mymap,downcase,$(UCWORDS))

           Now "$(DCWORDS)" contains "all these words are upcase".  By the way: it makes no
           difference, whether we access the arguments via $1, "${1}" or "$(1)" within a macro.

           You can directly use the variable as though it were a function, if there is no
           function of that name.  This is internally converted to "call", so these are
           equivalent:

               discussion = The $0 turned into $1 $2.
               direct = $(discussion an,argument)
               called = $(call discussion,an,argument)

           It might seem debatable whether "$[call]" should also expand the macro's "$[]"
           expressions, or whether a function should always do the same thing, no matter how it
           is called.  The latter was chosen, because with normal make syntax it would be
           impossible to get "$[1], $[2]..." into a variable (they'd get replaced by nothing,
           before the assignment even takes place.)  Hence, if you have a macro for defining a
           rule, you want expressions like "$(output)" to be seen when the rule gets parsed, so
           you must protect them from "call":

               define myrule
                   $2: $1
                       mycommand $$(input) -o $$(output)
               endef
               $[myrule myinput,myoutput]

       filter patterns, words
           Returns all words in the list that match the patterns.  Patterns may simply be other
           words, or filename wildcards (i.e., "*", "?", and "[a-z]" are recognized), or they may
           have a "%" character, which means to match any string at that point (same as "*").

       filter_out patterns, words
           Returns all words in the list that do not match the patterns.  Patterns may simply be
           other words, or filename wildcards (i.e., "*", "?", and "[a-z]" are recognized), or
           they may have a "%" character, which means to match any string at that point (same as
           "*").

           For example:

               libproduction.a: $(filter_out test_*, $(wildcard *.o))

           will put all .o files which exist or can be built, except those beginning with test_,
           into libproduction.a.

       findstring find, in
           Return find, if it is a substring of in.

       firstword words
           Return the first word.

       map words, perlcode
       makemap words, perlcode
           Similarly to Perl's map, applies perlcode to each word in turn and returns the
           results.  The first variant is plain Perl code, while the second variant first passes
           the perlcode through Make-style variable expansion.  The words are expanded in both
           cases.

           The words are in $_ and are returned unless you undef $_.  This is intended for
           modifications not easily handled by "patsubst".  Only the first comma is a separator,
           any others are considered part of the perlcode.

               # Switch words.  Double parens, to allow parens in perlcode, or use ${}:
               X = $((map $(VALUES), s/(.+)-(.+)/$2-$1/))
               # You can use make expressions, but then you must use $$ for Perl $:
               Y = $(makemap $(VALUES), tr/$(OLDCHARS)/$(NEWCHARS)/ or $$_ = 'failed')
               # You can eliminate candidates:
               Y = $(map $(VALUES), undef $_ if /no_good/)

       join words1, words2
           Do a pairwise join of the first words and the second words.

       patsubst pattern, substitute, words
           Performs a substitution on each word in the word list.  A "%" character matches any
           string.  This is best illustrated by an example:

               OBJS = $(patsubst %.c, object_dir/%.o, $(C_SOURCES))

           takes every file in C_SOURCES and returns the name of an object file in object_dir.
           Sometimes it is more concise to use a substitution reference, e.g., the above could
           have been written as

               OBJS = $(C_SOURCES:%.c=object_dir/%.o)

       sort word1 word2 word3 ...
           Sorts the words in lexical order and removes duplicates.

       strip string
           Removes leading and trailing whitespace from string and replaces each internal
           sequence of one or more whitespace characters with a single space. Thus, "$(strip  a b
           c )" results in "a b c".

       subst from,to,text
           Performs a textual replacement on the text text: each occurrence of from is replaced
           by to. The result is substituted for the function call. For example,

               $(subst ee,EE,feet on the street)

           substitutes the string "fEEt on the strEEt".

       word n,text
           Returns the nth word of text. The legitimate values of n start from 1 at the beginning
           or backwards from -1 at the end. If n is bigger than the number of words in text, the
           value is empty.

       wordlist indexlist, words
       wordlist firstindex, lastindex, words
           In the first form you supply a list of indices (counting from 1 at the beginning or
           backwards from -1 at the end) to select the words you want.  In the second form you
           specify the range of words you want returned.

       words text
           Returns the number of words in text.

   Miscellaneous Functions
       foreach var,list,text
           The first two arguments, var and list, are expanded before anything else is done; note
           that the last argument, text, is not expanded at the same time. Then for each word of
           the expanded value of list, the variable named by the expanded value of var is set to
           that word, and text is expanded. Presumably text contains references to that variable,
           so its expansion will be different each time.

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

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

           Here text is "$(wildcard $(dir)/*)". The first repetition finds the value "a" for dir,
           so it produces the same result as "$(wildcard a/*)"; the second repetition produces
           the result of "$(wildcard b/*)"; and the third, that of "$(wildcard c/*)".

           This example has the same result (except for setting "dirs") as the following example:

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

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

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

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

           Note: Don't confuse this with the "$(foreach)" special variable.

       info text
       warning text
       error text
           Output text returning the nothing.  The first goes to STDOUT, the second to STDERR,
           the third additionally aborts processing.

       prebuild targets
       make targets
           Returns its argument verbatim, but first builds all the files listed.  This is useful
           when a given file is needed when evaluating a make expression.  This typically happens
           when you have a build where the set of files involved is computed by some shell
           commands.  For example,

               file_list :
                   # shell commands to compute a list of files to put into the program

               my_program : $(&cat $(prebuild file_list))

           If you need the list in more than one rule, it would be more efficient to use an
           expand at most once variable:

               file_list ;= $(&cat $(prebuild file_list))

               my_program1 : a.o $(file_list)

               my_program2 : b.o $(file_list)

           If instead you specified just "$(&cat file_list)", then makepp would not force
           file_list to be up-to-date before it executes the shell command.  Using "$(prebuild )"
           is the best way to solve this problem.  You might be tempted to try other things, like
           this:

               my_program : file_list $(&cat file_list)

           but this won't work because "$(&cat file_list)" is evaluated before makepp attempts to
           build "file_list".

       only_phony_targets names
           Returns only those names in the list that are phony targets of some rule (either
           explicit or pattern rules).  You may specify wildcards (including makepp's special
           wildcard, "**") in the filenames.  (See the "$(wildcard )" function for more details.
           This can be used for grouping targets, for example:

               $(phony tests): $(only_phony_targets */**/tests)

       origin variable
           Given the name of a variable, tells you where its value comes from.

       perl perlcode
       makeperl perlcode
           Evaluates perlcode in a block and returns the result.  The first variant is plain Perl
           code, while the second variant first passes the perlcode through Make-style variable
           expansion.

           Note, that, as with all functions, the function delimiter used may not appear within
           the perlcode outside of single or double quoted strings.  But you can double it as in
           the last example:

               VAR = 1
               VAR1 = ${perl ($VAR + 1) * 3}
               VAR2 = $(perl do { $VAR *= 3; return $VAR + 1 } if $VAR)
               VAR3 = $(makeperl $(VAR1) * 3 + $$VAR) # one Make var and one Perl var
               VAR = $((perl if( ... ) { ... }))

       phony words
           Indicates that the list of words are actually phony targets, and returns the list of
           targets.  It's intended to be used like this:

               $(phony all): my_program

               $(phony clean):
                   &rm -f *.o my_program

           You can also declare one or more targets as phony with a line like this anywhere in
           your makefile:

               .PHONY: all clean

       print text
           Outputs the text and returns it.  This is mostly useful for debugging, when you don't
           understand why variable substitution has the result that it does.  For example,

               XYZ := $(print $(patsubst %.c, %o, $(SOURCE_FILES)))

           will print out the result of the "patsubst" call.

               XYZ := $(patsubst %.c, %o, $(print $(SOURCE_FILES)))

           will print out the last argument to the "patsubst" call.

       shell shell-command
           Returns the output from the given shell command, with newlines replaced by spaces.

           Note, that, as with all functions, the function delimiter used may not appear within
           the shell-command outside of single or double quoted strings.  But you can double it
           as in the second example:

               date = $(shell date)        # better: $(perl scalar localtime)
               VAR = ${{shell f() { echo hello; }; f}}

       xargs command,arguments[,suffix[,length]]
           Returns a newline-separated list of commands that each begin with the specified
           command, and end with as many elements of the list as possible without going over
           length (default 1000) characters.

           The purpose of this is to avoid spilling over the command length limit on your system.
           For example, if there are a lot of generated files, then you would probably want your
           clean target (which you should not have, because "makeppclean" is more efficient) to
           look something like this:

               $(phony clean):
                   $(xargs $(RM), $(only_targets **/*))

           This also has the side-effect that no command whatsoever is generated if the list
           happens to be empty.  But in this case it would be better to use the builtin &rm,
           because the arguments to the builtin commands are only limited by Perl's memory:

               $(phony clean):
                   &rm -f $(only_targets **/*)

           If a third argument is specified, then it is used to postfix each command.  This is
           useful for specifying redirectors, e.g. (though here again &echo would help):

               manifest:
                   &rm -f $@
                   &touch $@
                   $(xargs echo, $(only_nontargets **/*), >> $@)

       Some of this documentation is based on the GNU make documentation.

       Please note that if a function gets called during makefile initialization, e.g. the
       expansion of export variables, error or warning messages will report line number 0.

AUTHOR

       Gary Holt (holt-makepp@gholt.net)