From 399a36f1f0ef8db6a3f9f2cb93f238603803df12 Mon Sep 17 00:00:00 2001 From: David Rose Date: Wed, 6 Feb 2002 01:58:27 +0000 Subject: [PATCH] new doc --- panda/src/doc/ppremake-variables.txt | 404 +++++++++++++++++++++++++++ 1 file changed, 404 insertions(+) create mode 100644 panda/src/doc/ppremake-variables.txt diff --git a/panda/src/doc/ppremake-variables.txt b/panda/src/doc/ppremake-variables.txt new file mode 100644 index 0000000000..40b3cc5031 --- /dev/null +++ b/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 ] - returns true if 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 ] - 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 ] - 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 ] - 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 ] - similar to $[unixfilename], but as above, + duplicates the 'cygpath -p -u' shell command. + + $[wildcard ...] - 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 ] - 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 ] - 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 ,] - checks to see if a library file by + the given name exists in any of the named directories. Here + 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 ] - 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 ] - 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 ] - convert the indicated filename to + standard form by removing consecutive repeated slashes and + collapsing /../ where possible. + + $[length ] - returns the length of the indicated argument + in characters, not counting leading or trailing spaces. + + $[substr ,,] - returns the substring of + beginning at character (1-based) and continuing to character + , inclusive. + + $[dir ] - 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 ] - 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 ] - returns the filename extension of each + argument, including the leading dot, if any. If there is no + extension, it returns the empty string. + + $[basename ] - returns the basename part of each + argument: everything except for the extension and its dot, but + including the directory, if any. + + $[word ,] - returns the nth word, 1-based, of the + space-separated list of words in the second parameter. + + $[wordlist ,,] - returns the range of words, 1-based, + of the space-separated list of words in the third parameter. See + also $[substr]. + + $[words ] - returns the number of space-separated words in + the list. + + $[firstword ] - returns the first word in the space-separated + list. This is the same as $[word 1,]. + + $[patsubst ,,] - modifies each of the words in the + list (typically, these will be filenames) according to the + / pattern matching. + + Both the and the 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 + is subsituted in for the percent sign in . + + 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 pattern, but it must appear once. It may not appear + twice within a pattern string (but see the special extension for + space-separated patterns, below). If a filename in the + list does not match the 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 , replacement patterns: + + $[patsubst ,,,,,,...,] + + In this syntax, each word will be tested against each pattern in + sequence, until a match is found. When the first match is + found for a given word, the corresponding string is used to + generate the replacement. If all 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 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 ,,] - as above, but is not split + into multiple words, even it it contains spaces--it is matched, + spaces and all, with the patterns in the and strings. + + $[filter ,] - filters the space-separated list of + to return only those words that match one or more of the + patterns given in the space-separated list of . 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 ,] - the inverse of $[filter], this + returns only the words that do *not* match any of the patterns in + . 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 ,,] - substitutes all occurrences of + appearing in with . Unlike $[patsubst], this pays no + attention to percent signs and does not chop 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 , + pairs, e.g.: + + $[subst ,,,,,,...,] + + $[wordsubst ,,] - like $[subst], except it only + replaces whole words. + + $[findstring ,] - returns if and only if it is a substring + of ; otherwise, returns the empty string. + + $[sort ] - returns the space-separated list of , + 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 ] - 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 ,,,...,] - 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 ,,] - returns if the expression string + is true (that is, nonempty), or if is false + (empty). The false condition may be omitted; if so, empty + string is returned if is false. + + $[foreach ,,] - evaluates once for each + word in the space-separated list . For each such word, a + variable named is assigned the current word, then + 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 ,] - like $[foreach], above, but evaluates + once within each of the scopes named by the space-separated + list. See the discussion on ppremake named scopes in + ppremake-syntax.txt. + + $[eq ,] - returns true (nonempty) if is string + equivalent to , disregarding leading and trailing spaces. + + $[ne ,] - returns true (nonempty) if is *not* string + equivalent to , disregarding leading and trailing spaces. + + $[defined ] - 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. + + $[= ,] - returns true (nonempty) if is numerically + equivalent to . It is an error if either or is + not a number. This may also be written as $[== ,]. + + $[!= ,] + $[< ,] + $[<= ,] + $[> ,] + $[>= ,] + The above all have the obvious semantic meaning, based on a + numerical comparison of and . + + $[not ] - returns true (nonempty) if the expression is empty, + and false (empty) if the expression is nonempty. + + $[or ,,...,] - returns true (nonempty) if any + of the subexpressions are nonempty. + + $[and ,,...,] - returns true (nonempty) if all + of the subexpressions are nonempty. + + $[upcase ] - returns the input text, with all lowercase + letters converted to uppercase. + + $[downcase ] - returns the input text, with all uppercase + letters converted to lowercase. + + $[cdefine ] - 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 ] - 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 ,] - recursively expands the map variable + $[varname] with the expression , until all definitions have + been encountered. See the discussion on ppremake map variables in + ppremake-syntax.txt. + + $[unmapped ,] - returns all the words in the + space-separated list that do not match any of the keys in + the indicated map variable.