new doc

panda/src/doc/ppremake-variables.txt

@@ -0,0 +1,404 @@
+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.
+
+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.
+
+  $[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].
+
+  $[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].
+
+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 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).
+
+  $[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.
+
+  $[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.
+
+  $[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 <b> if and only if it is a substring
+    of <a>; 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.
+
+  $[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>.
+
+  $[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.