TheCloud/panda3d
1
0
Fork 0
mirror of https://github.com/panda3d/panda3d.git synced 2025-10-04 10:54:24 -04:00
Code Issues Packages Projects Releases Wiki Activity

new doc

Browse Source
This commit is contained in:
David Rose 2002-02-06 01:58:27 +00:00
parent 48fbbe3aac
commit 399a36f1f0
1 changed files with 404 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

404
panda/src/doc/ppremake-variables.txt Normal file
View File

@ -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.