In general, variables are referenced within ppremake with the syntax
$[variable-name].  Functions, if defined, are referenced by something
like $[function-name arg1 arg2 ... ].  The ppremake syntax borrows
heavily from that of GNU makefile syntax, with GNU make's parentheses
replaced by square brackets to prevent confusion with actual makefile
syntax.

Note that the dollar sign and square brackets are not actually part of
the variable names, but are simply the syntax used to reference the
variable.  This syntax is included with each variable definition in
this document, because that is how you are most likely to see the
variable references.



The general convention is for variables that are built into ppremake,
or defined by the system ppremake scripts in the $DTOOL root
directory, should be defined with uppercase letters.  User-defined
variables, such as those used by the scripts in the $DTOOL/pptempl
directory to generate the various kinds of makefiles, are defined with
lowercase letters.  However, following the GNU makefile convention,
all built-in function names are lowercase.


The following variables are built into the ppremake executable, and
are always defined:

  $[PPREMAKE] - The name of the ppremake program itself,
    e.g. "ppremake".

  $[PPREMAKE_VERSION] - The current version number for ppremake.

  $[PLATFORM] - The compiled-in platform string; presently, this may
    be one of Linux, Irix, or Win32.

  $[PACKAGE_FILENAME] - The expected name of the file that indicates
    the top of the source hierarchy, e.g. Package.pp.

  $[SOURCE_FILENAME] - The expected name of the file that should be
    present in each subdirectory within the source hierarchy and
    defines the makefiles that should be generated within each
    subdirectory, e.g. Sources.pp.

  $[PPREMAKE_CONFIG] - The full pathname to the initial Config.pp file
    to read.  This may be specified by -c on the ppremake command
    line, or if it is unspecified, it is expected the user will set an
    environment variable of this name to the appropriate pathname.

  $[TAB] - The tab character.  This is primarily useful for generating
    makefiles, which insist on having an actual tab character, without
    having to store an actual tab character in the input files.

  $[PACKAGE_FILE] - The pathname to the Package.pp file at the top of
    the current source hierarchy, relative to the current directory.

  $[TOPDIR] - The directory name containing $[PACKAGE_FILE]; that is,
    the directory name of the top of the current source hierarchy.
    Unlike $[PACKAGE_FILE], this is an absolute pathname, rather than
    a relative pathname.

The following variables are built into the ppremake executable, and
are updated with the current values as each Sources.pp file is
scanned:

  $[DIRNAME] - The name of the source directory currently being
    processed.  This is neither a relative nor an absolute directory
    path, and does not contain slashes; it is simply the name of the
    directory that contains the current Sources.pp file.  By
    convention, all directory names within a particular source
    hierarchy must be unique.

  $[DIRPREFIX] - The relative pathname to the current source
    directory, from $[TOPDIR], with a trailing slash.

  $[SOURCEFILE] - The name of the source file currently being
    processed.  This will be "Sources.pp" (but see also
    $[THISFILENAME], below).  Thus, for example,
    $[TOPDIR]$[DIRPREFIX]$[SOURCEFILE] will be the full pathname to
    the current Sources.pp file.

  $[PATH] - The relative pathname to the current directory, from
    $[TOPDIR], without a trailing slash.

  $[RELDIR] - This is a special variable that is similar to $[PATH] in
    that it contains the relative pathname to the current directory,
    but instead of being relative to $[TOPDIR] it is relative to the
    current *output* directory--the directory in which the current
    #output command in effect is directing its output.  This value of
    this variable is therefore dependant on context.

  $[SUBDIRS] - A space-delimited list of source subdirectories within
    this source directory.  These are simply directory names, without
    slashes; prefix each name with $[DIRPREFIX] to make them relative
    to $[TOPDIR].  These are automatically sorted in dependency order,
    such that a particular directory always appears following all the
    directories it depends on.

  $[SUBTREE] - A space-delimited list of names of all source
    subdirectories, including this one, at this level and below.  The
    subdirectory names are relative to $[TOPDIR].  As above, these are
    sorted into dependency order.

The following variables are built into the ppremake executable, and
are updated with the current values as *each* different file is read
in (e.g. via the #include directive):

  $[THISFILENAME] - The current filename being read; often as a
    relative filename from $[TOPDIR], or as a full pathname when the
    file is outside of the current source hierarchy.

  $[THISDIRPREFIX] - The directory containing the current filename
    being read, with a trailing slash; this everything up to and
    including the rightmost slash in $[THISFILENAME].

The following variable is built into the ppremake executable, and is
filled in after all Sources.pp files have been read:

  $[TREE] - a space-delimited list of names of all the directories in
    the current source hierarchy containing a Sources.pp file,
    relative to $[TOPDIR].  Note that this variable is not available
    until after all the Sources.pp files have been read, so it cannot
    itself be referenced within a Sources.pp file.

The following variables are not set by the ppremake executable, but
are required to be set by one of the startup scripts, typically
$DTOOL/pptempl/System.pp:

  $[GLOBAL_FILE] - the full pathname to the file that should be read
    within the global scope after reading each Sources.pp file and
    before reading each Template file.

  $[TEMPLATE_FILE] - the full pathname to the file that should be read
    once for each Sources.pp file to generate the actual output
    makefiles appropriate to each directory.

  $[DEPENDS_FILE] - the full pathname to the file that should be read
    once for each Sources.pp file to determine the inter-directory
    dependencies and inter-file dependencies.

  $[DEPENDENCY_CACHE_FILENAME] - the name of the file (with no
    directory part of the filename) that is used to cache the
    inter-file dependencies for each source file in a given directory
    between sessions.  A file by this name is automatically created in
    each source directory.

  $[DEPEND_DIRS] - the list of directories that the current directory
    depends on.  This is set by the script named by $[DEPENDS_FILE],
    and has a different value within each source directory.

  $[DEPENDABLE_HEADERS] - the list of source filenames within the
    current directory that are considered source header files and that
    might be listed with the #include directory in some other file.
    This is used to determine the set of inter-file dependencies.
    Like $[DEPEND_DIRS], this is set by the $[DEPENDS_FILE] script,
    and has a different value within each source directory.

  $[DEPENDABLE_HEADER_DIRS] - the list of directories outside of the
    current source tree in which additional header files ("dependable
    headers") may be found.  This is used to implement inter-package
    dependencies.  Any files found in the directories named here are
    deemed to be dependable headers, and the $[depdencies] variable
    will include these files.


The following functions are built into the ppremake executable.  In
general, these operate on one word or a group of words separated by
spaces.  Functions that take multiple parameters with different
meanings will use commas to separate out the individual parameters
(and then each parameter may still consist of one word or a group of
words).  The result is always a string, which might be true/false, or
one word or a group of words.  For true/false results, the return
value is either the empty string (false) or a nonempty string (true).

  $[isfullpath <pathname>] - returns true if <pathname> is a full
    pathname, i.e. it begins with a slash.  Remember that ppremake
    always uses Unix-style pathnames internally, even on a Windows
    platform.

  $[osfilename <pathname>] - converts the indicated Unix-style
    pathname to a format appropriate to the platform in use.  For
    instance, on Windows it replaces all of the forward slashes with
    backslashes.  On a Unix platform it does nothing.

  $[unixfilename <pathname>] - converts the indicated native-style
    pathname to a Unix-style pathname for internal operations.  This
    can be used to read a pathname as supplied by the user, which
    might be in Windows style format (i.e. with backslashes instead of
    forward slashes).

  $[unixshortname <pathname>] - converts the indicated native-style
    pathname to a Unix-style pathname for internal operations, using
    the 8.3 Windows "short" name, if possible.  This is often an easy
    way to avoid spaces in long Windows filenames, like c:/Program
    Files/whatever.

  $[cygpath_w <pathname>] - similar to $[osfilename], except it takes
    advantage of the Cygwin library, if available, to do a more
    accurate filename conversion.  This is generally specific to the
    Windows platform.  The result is the same as the output of the
    'cygpath -w' shell command.

  $[cygpath_p <pathname>] - similar to $[unixfilename], but as above,
    duplicates the 'cygpath -p -u' shell command.

  $[wildcard <param1> <param2> ...] - expands the indicated parameters
    as if they were filename wildcards against the current directory.
    For example, $[wildcard *.c] returns a list of all C files in the
    current directory.

  $[isdir <filename>] - returns true if the named file exists and is a
    directory, false otherwise.  This actually expands the
    parameter(s) given, similar to $[wildcard], and tests the first
    file returned.

  $[isfile <filename>] - returns true if the named file exists and is
    a regular file, false otherwise.  This actually expands the
    parameter(s) given, similar to $[wildcard], and tests the first
    file returned.

  $[libtest <dirnames>,<libname>] - checks to see if a library file by
    the given name exists in any of the named directories.  Here
    <dirnames> may be any space-separated list of directory names.
    Returns true if the library is found, false otherwise.

    This function follows the following ppremake convention: if a
    library name is given without an extension, the actual filename to
    search for is constructed by prefixing "lib" and adding whatever
    extension is appropriate for the OS in question.  For instance,
    "nspr" may search for libnspr.a (or libnspr.lib on Windows).
    However, if the library name is given including an extension, that
    is taken to be the filename without modification.

  $[bintest <binname>] - checks to see if an executable program exists
    on the current search path.  The program may or may not include
    the final ".exe" extension (on Windows).  Returns true if it is
    found, false otherwise.

  $[shell <command>] - executes the indicated command in a sub-shell,
    and returns the standard output from the process.  Use of this
    command is somewhat unportable (it doesn't work on a Windows
    machine that doesn't have Cygwin installed).

  $[standardize <filename>] - convert the indicated filename to
    standard form by removing consecutive repeated slashes and
    collapsing /../ where possible.

  $[canonical <filename>] - convert the indicated filename to
    canonical form by replacing the directory part with the
    fully-qualified directory part.  This is done by changing to that
    directory and calling getcwd().  The result is similar to that of
    $[standardize], above, but it is more likely to be consistent
    across different filenames.

    This has the effect of (a) converting relative paths to absolute
    paths, (b) always resolving a given directory name to the same
    string, even if different symbolic links are traversed, and (c)
    changing nice symbolic-link paths like /fit/people/drose to ugly
    NFS automounter names like /hosts/dimbo/usr2/fit/people/drose.
    This can be troubling, but sometimes this is exactly what you
    want.

  $[length <argument>] - returns the length of the indicated argument
    in characters, not counting leading or trailing spaces.

  $[substr <s>,<e>,<string>] - returns the substring of <string>
    beginning at character <s> (1-based) and continuing to character
    <e>, inclusive.

  $[dir <filenames>] - returns the directory part of the filename
    argument(s).  This is the text up to and including the rightmost
    slash of each argument, or "./" if the argument contains no slash.
    For example, $[dir abc/def/t.c abc/foo.bar lib.exe] will return
    the string "abc/def/ abc/ ./".
 
  $[notdir <filenames>] - returns everything except the directory part
    of the filename argument(s).  This the text following the
    rightmost slash of each argument, or the argument itself if there
    is no slash.

  $[suffix <filenames>] - returns the filename extension of each
    argument, including the leading dot, if any.  If there is no
    extension, it returns the empty string.

  $[basename <filenames>] - returns the basename part of each
    argument: everything except for the extension and its dot, but
    including the directory, if any.

  $[makeguid <name>] - returns a GUID (global unique identifier) based
    on an MD5 digest computation of <name>.  The resulting GUID, which
    looks like 398F2CC4-C683-26EB-3251-6FC996738F7F, is suitable for
    identifying Visual Studio .NET projects.

  $[word <n>,<words>] - returns the nth word, 1-based, of the
    space-separated list of words in the second parameter.

  $[wordlist <s>,<e>,<words>] - returns the range of words, 1-based,
    of the space-separated list of words in the third parameter.  See
    also $[substr].

  $[words <words>] - returns the number of space-separated words in
    the list.

  $[firstword <words>] - returns the first word in the space-separated
    list.  This is the same as $[word 1,<words>].

  $[patsubst <from>,<to>,<words>] - modifies each of the words in the
    list (typically, these will be filenames) according to the
    <from>/<to> pattern matching.

    Both the <from> and the <to> pattern should include exactly one
    percent sign (%).  This symbol stands for any sequence of
    characters in the filename, and the rest of the pattern represents
    literal text.  Whatever is matched by the percent sign in <from>
    is subsituted in for the percent sign in <to>.

    For example, $[patsubst %.c,%.o,$[sources]] will replace each
    filename listed in $[sources] that ends in .c with a corresponding
    filename that ends in .o instead.

    The percent sign may appear in the beginning, middle, or end of
    the <from> pattern, but it must appear once.  It may not appear
    twice within a pattern string (but see the special extension for
    space-separated <from> patterns, below).  If a filename in the
    list does not match the <from> pattern, it is left unchanged.  In
    practice, the percent sign is usually used to stand for the first
    part of the filename, and the extension is matched explicitly.

    This function is based on the $(patsubst) function as used in GNU
    makefiles.  As a special extension to GNU syntax, you may also
    insert multiple pairs of <from>,<to> replacement patterns:

    $[patsubst <from1>,<to1>,<from2>,<to2>,<from3>,<to3>,...,<words>]

    In this syntax, each word will be tested against each pattern in
    sequence, until a match is found.  When the first <from> match is
    found for a given word, the corresponding <to> string is used to
    generate the replacement.  If all <from> patterns are exhausted
    and a match has not been found, the word is inserted unchanged.

    For example: the expression $[patsubst %.c,%.h,%.C,%.H,$[files]]
    will convert each .c file to the corresponding .h file, and each
    .C file to the corresponding .H file.

    As a further extension to GNU syntax, each <from> pattern may
    actually be a space-separate sequence of multiple patterns.  In
    this case, if the word matches any of the patterns, it is
    considered to match the whole pattern.  For example, $[patsubst
    %.c %.y %.l,%.o,$[files]] will replace any filename in $[files]
    that ends in .c, .y, or .l with the extension .o.

  $[patsubstw <from>,<to>,<word>] - as above, but <word> is not split
    into multiple words, even it it contains spaces--it is matched,
    spaces and all, with the patterns in the <from> and <to> strings.

  $[filter <patterns>,<words>] - filters the space-separated list of
    <words> to return only those words that match one or more of the
    patterns given in the space-separated list of <patterns>.  For
    instance, $[filter %.c,$[files]] returns only those filenames in
    $[files] that end in .c.  (The same thing can also be achieved
    with $[patsubst %.c,%.c,%,,$[files]]--this replaces each
    occurrence of %.c with itself, and everything else (%) with the
    empty string.)

  $[filter-out <patterns>,<words>] - the inverse of $[filter], this
    returns only the words that do *not* match any of the patterns in
    <patterns>.  For instance, $[filter-out %.c,$[files]] returns only
    those file in $[files] that do *not* end in .c.  (The same thing
    can also be achieved with $[patsubst %.c,,%,%,$[files]].)

  $[subst <from>,<to>,<text>] - substitutes all occurrences of <from>
    appearing in <text> with <to>.  Unlike $[patsubst], this pays no
    attention to percent signs and does not chop <text> up into words;
    it is strictly a byte-for-byte replacement.  For instance, $[subst
    foo,bar,I need food] produces "I need bard".

    As a further extension to GNU, similar to the corresponding
    extension for $[patsubst], you may include multiple <from>,<to>
    pairs, e.g.:

    $[subst <from1>,<to1>,<from2>,<to2>,<from3>,<to3>,...,<text>]

  $[wordsubst <from>,<to>,<text>] - like $[subst], except it only
    replaces whole words.

  $[findstring <a>,<b>] - returns <a> if and only if it is a substring
    of <b>; otherwise, returns the empty string.

  $[sort <words>] - returns the space-separated list of <words>,
    sorted into alphabetical order.  This also removes duplicate
    words; $[sort] is therefore often used solely for its side effect
    of eliminating duplicate words from a list.

  $[unique <words>] - removes duplicate words from the list without
    changing their respective order.  Since this is slightly slower
    than $[sort], it should only be used when the order of the
    original words on the list is important.

  $[join <sep,<words>] - joins the space-separated list of <words>
    into a single string using the separator <sep>.

  $[matrix <param1>,<param2>,<param3>,...,<paramN>] - splits each
    parameter up into a space-separated set of words, and then returns
    a result that represents all the ways to combine the different
    words in each parameter, like the shell {a,b,c} expansion syntax.
    For example, $[matrix a b,c,10 20 30] expands to ac10 ac20 ac30
    bc10 bc20 bc30.

  $[if <expr>,<str1>,<str2>] - returns <str1> if the expression string
    <expr> is true (that is, nonempty), or <str2> if <expr> is false
    (empty).  The false condition <str2> may be omitted; if so, empty
    string is returned if <expr> is false.

  $[foreach <tempvar>,<words>,<expr>] - evaluates <expr> once for each
    word in the space-separated list <words>.  For each such word, a
    variable named <tempvar> is assigned the current word, then <expr>
    is evaluated; the result is the concatenation of all the
    evaluations.  For instance, $[foreach t,dog cat
    mouse,foo/bar/$[t].c] produces "foo/bar/dog.c foo/bar/cat.c
    foo/bar/mouse.c".

  $[forscopes <scopes>,<expr>] - like $[foreach], above, but evaluates
    <expr> once within each of the scopes named by the space-separated
    <scopes> list.  See the discussion on ppremake named scopes in
    ppremake-syntax.txt.

  $[eq <op1>,<op2>] - returns true (nonempty) if <op1> is string
    equivalent to <op2>, disregarding leading and trailing spaces.

  $[ne <op1>,<op2>] - returns true (nonempty) if <op1> is *not* string
    equivalent to <op2>, disregarding leading and trailing spaces.

  $[defined <varname>] - returns true if the named variable has any
    definition, whether it is empty or nonempty, or false if it has
    not yet been defined.  Since the semantic convention of ppremake
    is intended to be that all variables are implicitly defined to the
    empty string if they are not explicitly defined otherwise, the
    meaning of this function is questionable.

  $[= <op1>,<op2>] - returns true (nonempty) if <op1> is numerically
    equivalent to <op2>.  It is an error if either <op1> or <op2> is
    not a number.  This may also be written as $[== <op1>,<op2>].

  $[!= <op1>,<op2>]
  $[< <op1>,<op2>]
  $[<= <op1>,<op2>]
  $[> <op1>,<op2>]
  $[>= <op1>,<op2>]
    The above all have the obvious semantic meaning, based on a
    numerical comparison of <op1> and <op2>.

  $[+ <op1>,<op2>]
  $[- <op1>,<op2>]
  $[- <op1>]
  $[* <op1>,<op2>]
  $[/ <op1>,<op2>]
  $[% <op1>,<op2>]
    The above perform the appropriate arithmetic operation on <op1>
    and <op2> (or on <op1> only, in the case of unary minus).  The
    operation is always integer.

  $[not <expr>] - returns true (nonempty) if the expression is empty,
    and false (empty) if the expression is nonempty.

  $[or <expr1>,<expr2>,...,<exprN>] - returns true (nonempty) if any
    of the subexpressions are nonempty.

  $[and <expr1>,<expr2>,...,<exprN>] - returns true (nonempty) if all
    of the subexpressions are nonempty.

  $[upcase <text>] - returns the input text, with all lowercase
    letters converted to uppercase.

  $[downcase <text>] - returns the input text, with all uppercase
    letters converted to lowercase.

  $[cdefine <varname>] - a convenience function to output a C-style
    #define or #undef statement based on the value of the named
    variable.  If the named string is a variable whose definition is
    nonempty, this returns "#define varname definition".  Otherwise,
    it returns "#undef varname". This is particularly useful for
    building up a config.h file.

  $[dependencies <filename>] - outputs a list of all the other source
    files that the named source file depends on.  The set of
    dependencies for a particular source file is determined by
    ppremake when it scans all the directories; it scans each source
    file for the presence of #include directives and uses this
    information to build a file dependency tree.  This allows ppremake
    to generate makefiles with the proper file dependencies built in,
    even on systems for which makefile autodependencies have not been
    implemented.

  $[closure <varname>,<expr>] - recursively expands the map variable
    $[varname] with the expression <expr>, until all definitions have
    been encountered.  See the discussion on ppremake map variables in
    ppremake-syntax.txt.

  $[unmapped <varname>,<keys>] - returns all the words in the
    space-separated list <keys> that do not match any of the keys in
    the indicated map variable.
