|
|
@@ -0,0 +1,142 @@
|
|
|
+The following steps are executed when ppremake is invoked:
|
|
|
+
|
|
|
+ 1. Look in the current directory for a file called Package.pp. If
|
|
|
+ it is not found, but Sources.pp is present in the current
|
|
|
+ directory, then look for Package.pp in the parent directory.
|
|
|
+ Repeat until Package.pp is located; this is the root of the
|
|
|
+ source directory hierarchy.
|
|
|
+
|
|
|
+ 2. Read and interpret the Package.pp file. This should, in turn,
|
|
|
+ read in (via the #include directive; see below) whatever other
|
|
|
+ configuration scripts are relevant to the current package. The
|
|
|
+ exact behavior of Package.pp is not hardcoded into ppremake, but
|
|
|
+ the Package.pp scripts for each of the Panda directories will
|
|
|
+ ultimately include the following files in order:
|
|
|
+
|
|
|
+ Any Package.pp for a dependent tree (e.g. $PANDA/Package.pp, etc.)
|
|
|
+ $DTOOL/Package.pp
|
|
|
+ $DTOOL/Config.pp
|
|
|
+ $DTOOL/Config.Platform.pp
|
|
|
+ The user's Config.pp file, as specified by $PPREMAKE_CONFIG.
|
|
|
+ $DTOOL/pptempl/System.pp
|
|
|
+
|
|
|
+ The various Package.pp files are designed to cascade down, such
|
|
|
+ that when you invoke ppremake from a high-level tree, such as
|
|
|
+ Direct (for instance), ppremake invokes $DIRECT/Package.pp, which
|
|
|
+ in turn invokes $PANDA/Package.pp, which in turn invokes
|
|
|
+ $DTOOL/Package.pp. At the bottom level, $DTOOL/Package.pp does
|
|
|
+ most of the remaining setup work, in particular including the
|
|
|
+ various Config.pp files, and System.pp.
|
|
|
+
|
|
|
+ The Config.pp files are intended to define the variables the user
|
|
|
+ might customize for a particular build environment; the user's
|
|
|
+ personal Config.pp file is included last, and may override any of
|
|
|
+ the default values defined in the system Config.pp files.
|
|
|
+
|
|
|
+ One particularly critical variable that is defined by Config.pp
|
|
|
+ is $[BUILD_TYPE]. This represents the type of makefile rules
|
|
|
+ that are to be generated, e.g. "unix" to generate standard
|
|
|
+ Unix-style makefile syntax, or "msvc" to generate syntax specific
|
|
|
+ to Microsoft's nmake. The particular string specified here
|
|
|
+ controls the selection of which Template files are to be loaded
|
|
|
+ in a later step to actually generate output files in each source
|
|
|
+ directory.
|
|
|
+
|
|
|
+ The System.pp file is also essential and defines a few more
|
|
|
+ variables that ppremake will be looking for during its execution.
|
|
|
+ This tells ppremake the names of certain critical files that it
|
|
|
+ needs to include. The use of System.pp to define these
|
|
|
+ filenames, instead of hardcoding them into ppremake, is
|
|
|
+ consistent with the ppremake philosophy of letting as much of its
|
|
|
+ behavior as possible to be controlled from within the scripting
|
|
|
+ language itself.
|
|
|
+
|
|
|
+ 3. Once Package.pp has been read, traverse the entire source
|
|
|
+ hierarchy, and read each Sources.pp file. A separate named scope
|
|
|
+ is defined for each Sources.pp file; the name of the scope is
|
|
|
+ taken from the name of the directory containing the file.
|
|
|
+
|
|
|
+ 4. Read in the global variable declarations. This is loaded from a
|
|
|
+ particular file specified by System.pp; this file defines global
|
|
|
+ declarations that will be useful when processing each Template
|
|
|
+ file later. To save time, this file is read once and stored in a
|
|
|
+ global scope, rather than re-read with each Template file. The
|
|
|
+ particular filename is specified by the ppremake variable
|
|
|
+ $[GLOBAL_FILE], which was set by System.pp; normally this is
|
|
|
+ $DTOOL/pptempl/Global.pp.
|
|
|
+
|
|
|
+ $DTOOL/pptempl/Global.pp will, in turn, also read in the file
|
|
|
+ $DTOOL/pptempl/Global.$[BUILD_TYPE].pp if it exists, which may
|
|
|
+ specify further global declarations that are specific to the
|
|
|
+ particular build type in effect. Remember, $[BUILD_TYPE] was
|
|
|
+ specified when Config.pp was read, and controls the particular
|
|
|
+ type of makefiles or build scripts that are to be generated.
|
|
|
+
|
|
|
+ 5. Build the inter-directory dependency chain. This is the chain of
|
|
|
+ relationships between different directories within the source
|
|
|
+ hierarchy. Each directory may depend on code from zero or more
|
|
|
+ other directories within the same package. (That is, a directory
|
|
|
+ may include header files define within another directory, and/or
|
|
|
+ require linking with a library built in that directory.)
|
|
|
+
|
|
|
+ This inter-directory dependency is critical to determine things
|
|
|
+ such as build order. If one directory must be built before
|
|
|
+ another directory, the makefiles must be constructed with this
|
|
|
+ relationship explicit.
|
|
|
+
|
|
|
+ This relationship is determined for each directory by executing
|
|
|
+ the script named by $[DEPENDS_FILE] (this variable was set by
|
|
|
+ System.pp) within each source directory scope. Remember, each
|
|
|
+ Sources.pp file has already been read in, and assigned its own
|
|
|
+ unique named scope. The DEPENDS_FILE script is responsible for
|
|
|
+ defining the variable $[DEPEND_DIRS] to contain the
|
|
|
+ space-separated list of directories (that is, named scopes) that
|
|
|
+ the files in this current directory depend on.
|
|
|
+
|
|
|
+ Normally, System.pp sets $[DEPENDS_FILE] to
|
|
|
+ $DTOOL/pptempl/Depends.pp. This script builds up $[DEPEND_DIRS]
|
|
|
+ based on the $[get_depend_libs] function which is defined in
|
|
|
+ Global.pp, which is in turn based on variables like $[LOCAL_LIBS]
|
|
|
+ defined within the Sources.pp file.
|
|
|
+
|
|
|
+ The inter-directory dependency information can be accessed from
|
|
|
+ within ppremake scripts simply by examining the $[DEPEND_DIRS]
|
|
|
+ variable within the appropriate scope. In addition, the
|
|
|
+ directory relationships are automatically used to sort the
|
|
|
+ variables $[SUBDIR] and $[SUBTREE] in order, such that each
|
|
|
+ directory is listed after the directories it depends on.
|
|
|
+
|
|
|
+ There is one other variable which should be defined by the
|
|
|
+ DEPENDS_FILE script: $[DEPENDABLE_HEADERS] should list the source
|
|
|
+ files within the current directory that may be named as #include
|
|
|
+ files in other files. This is used to build file-level
|
|
|
+ dependencies to support the $[dependencies] built-in function,
|
|
|
+ and is not related to inter-directory dependencies.
|
|
|
+
|
|
|
+ 6. Finally, generate the actual output files in each source
|
|
|
+ directory. This is done by executing the script named by
|
|
|
+ $[TEMPLATE_FILE] (set by System.pp) within each source directory
|
|
|
+ scope.
|
|
|
+
|
|
|
+ Normally, System.pp sets $[TEMPLATE_FILE] to
|
|
|
+ $DTOOL/pptempl/Template.$[BUILD_TYPE].pp. Recall again that
|
|
|
+ $[BUILD_TYPE] was specified when Config.pp was read, and controls
|
|
|
+ the particular type of makefiles or build scripts that are to be
|
|
|
+ generated, so there is a different Template script file for each
|
|
|
+ supported build type.
|
|
|
+
|
|
|
+ The Template file is responsible for generating the actual
|
|
|
+ makefile (or whatever build script is required) as appropriate to
|
|
|
+ each source directory. It now has all the information required:
|
|
|
+ all source directories have been read, so the relationships
|
|
|
+ between different source directories can control the output;
|
|
|
+ also, the inter-directory and inter-file dependencies are
|
|
|
+ available.
|
|
|
+
|
|
|
+ Generally, a Template file will include at least one #output
|
|
|
+ directive to generate the appropriate makefile for this
|
|
|
+ directory. Since there may be different kinds of source
|
|
|
+ directories, each with very different makefile requirements, the
|
|
|
+ Template files usually have one large #if condition based on the
|
|
|
+ value of $[DIR_TYPE], which is set within in each Sources.pp (and
|
|
|
+ is set in System.pp to default to "src").
|
David Rose