mirror of
https://github.com/panda3d/panda3d.git
synced 2025-10-04 10:54:24 -04:00
new doc
This commit is contained in:
David Rose
parent
48fbbe3aac
commit
399a36f1f0
404
panda/src/doc/ppremake-variables.txt
Normal file
404
panda/src/doc/ppremake-variables.txt
Normal 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.
|
||||||
Loading…
x
Reference in New Issue
Block a user