diff --git a/panda/src/doc/ppremake-philosophy.txt b/panda/src/doc/ppremake-philosophy.txt new file mode 100644 index 0000000000..06a6865f42 --- /dev/null +++ b/panda/src/doc/ppremake-philosophy.txt @@ -0,0 +1,191 @@ +The name 'ppremake' stands for Panda Pre-make; ppremake is a +preprocessor that reads a series of source description files and +generates a series of makefiles (or, potentially, other kinds of +package build description files, like VC++ project files). + + +WHY PPREMAKE? + + We needed something like ppremake to meet our complex multi-platform + build requirements. Panda should be built in different ways + according to platform: + + * On Unix systems that support shared libraries (.so files), each + subdirectory becomes a different .so file. This provides the + maximum convenience while developing; local changes remain local + to a particular .so file and don't require relinking of the + whole thing. + + * On Windows systems, the number of shared libraries (.dll files) + must be reduced to minimize overhead, as well as to allow STL to + work properly between different subdirectories within a package. + (In VC6, STL constructs other than vectors do not work between + different DLL's.) Thus, we must define a number of 'metalib' + objects that each represents a set of subdirectories that are to + be linked into one DLL. + + * On systems that do not support shared libraries at all, or for + developers who do not wish to use them, each subdirectory + becomes a static library. + + Also, it should be possible to build Panda natively on each + platform, without having to install Unix tools (e.g. Cygwin). This + means that we cannot depend on common Unix tools and commands (like + install, cp, mv) being present, and makes it difficult to define one + set of makefiles for all platforms. Furthermore, the use of + makefiles themselves is not universal; Windows developers are used + to using VC++ project files to define the build relationships, and + may resist a command-line based build system using makefiles. + + Finally, the relationships between source files should be recorded + only once; it won't do to have to maintain a set of makefiles for + Unix systems and a separate set of VC++ project files for Windows + systems. This invites error and accidental omissions on one side or + the other. + + +SOURCE TREE AND INSTALL TREE HIERARCHY + + The layout of the source tree and of the install tree for Panda are + strongly influenced by the Unix convention for open source projects, + particularly as standardized by GNU. This convention has a long + history and is widely understood by open source developers. + + The complete source hierarchy available on SourceForge consists of a + collection of packages, with names like dtool, panda, pandatool, and + direct; each package is the root of a separate buildable hierarchy + that includes a src and a metalibs directory; within these + directories, the source files themselves are distributed logically + among a number of further subdirectories. The structure looks + something like this: + + panda3d/README + panda3d/dtool/ + panda3d/dtool/Package.pp + panda3d/dtool/Sources.pp + panda3d/dtool/src/ + ... + panda3d/panda/ + panda3d/panda/Package.pp + panda3d/panda/Sources.pp + panda3d/panda/src/ + panda3d/panda/src/Sources.pp + panda3d/panda/src/express/ + panda3d/panda/src/express/Sources.pp + panda3d/panda/src/express/typedObject.cxx + panda3d/panda/src/express/typedObject.h + ... + panda3d/panda/metalibs/ + panda3d/panda/metalibs/Sources.pp + panda3d/panda/metalibs/pandaexpress/ + panda3d/panda/metalibs/pandaexpress/Sources.pp + panda3d/panda/metalibs/pandaexpress/pandaexpress.cxx + ... + + Note that there is a file called Sources.pp in each subdirectory + within the hierarchy, and there is a Package.pp at the root of each + package. These files define the build relationships among all the + source files in the hierarchy, and are the input files read by + ppremake to generate makefiles. + + Once the source tree is unpacked, the user's first step (after + customizing the local configuration requirements by setting up a + local Config.pp file) will be to cd into the root of one of the + packages--typically dtool, which must be built before any of the + others--and run ppremake to generate all of the makefiles for that + package. (This is akin to running ./configure within the root of a + package for most GNU software. Unfortunately, Panda cannot easily + take advantage of GNU's autoconf scripts, because of its difficult + multiplatform requirements.) + + Once the package has been configured, the user can build the entire + package with the command 'make' (or 'nmake' in a non-Cygwin Windows + environment). The source files within the tree are compiled in + place. At this point, nothing has yet been installed publicly. In + most Unix/GNU packages, the user may at this point run any + applications built within the tree prior to installation, but Panda + relies too heavily on shared libraries to make this work reliably. + You must 'make install' before you can execute any of the + applications within the Panda package. + + Installing the package with 'make install' (or 'nmake install') + copies to a public location all of the files that are necessary to + make use of the package, either for running applications or building + new applications. This includes all the executables (.exe files) as + well as shared libraries (.dll or .so files) for runtime, as well as + header files (.h files) and static libraries (.lib or .a files) for + building new applications. + + The location to which these files are installed is specified by the + user in the local Config.pp file; the common Unix convention is to + install these in the directory /usr/local/panda. The executables + will go into /usr/local/panda/bin, the static and dynamic libraries + into /usr/local/panda/lib, and the header files into + /usr/local/panda/include. Note that all packages within the source + hierarchy, including dtool, panda, pandatool, and direct, will be + installed into the *same* public install tree, whether it is called + /usr/local/panda or something else. (On a Windows environment the + directory name /usr/local/panda may be inappropriate. It is up to + the user to specify a suitable directory name. We suggest + C:\panda.) + + Once dtool has been built and installed, the next step is to cd to + the panda package, ppremake, and 'make' followed by 'make install', + and so on with the direct and/or pandatool packages. All of these + packages will be installed into /usr/local/panda (or whichever + directory the user specified as the install tree). + + +AN ALTERNATIVE INSTALL TREE PHILOSOPHY + + Installing all the packages to the same install tree works well for + the outside developer who is primarily interested in taking the + whole body of code as a complete piece, but we have different needs + for our own in-house development. It is convenient to be able to + treat the individual packages separately; our in-house 'attach' + scripts (not included with the distribution) allow us to use one of + several automatically-built trees for development, or upon need, to + switch on-the-fly to using our own personally built tree. + + In order to make this work, the source tree and the install tree + must become the same thing. When we are developing in-house, 'make + install' copies all the relevant files to the bin, lib, and include + subdirectories of the root of the source package, instead of to a + common public install directory. This allows us to easily + mix-and-match the files from packages built at various times. + + +PPREMAKE VARIABLES TO SUPPORT EITHER PHILOSOPHY + + Variables are defined in ppremake either with the appropriate + #define or #defer command in the local Config.pp, or in the absence of + this, they are taken from environment variables. + + In the normal, install-in-one-place philosophy, the user should + define only INSTALL_DIR, which indicates the root directory name all + packages will be installed to. In the alternative philosophy, used + in-house, the environment variables DTOOL, PANDA, DIRECT, + etc. should be defined, which indicate the location of the source + directories for each of the various trees. + + In either case, the various Package.pp scripts will define the + following ppremake variables appropriately: + + DTOOL_INSTALL + PANDA_INSTALL + DIRECT_INSTALL + (etc). + + The above indicate the directories in which files from each tree + should be installed. In the normal philosophy, these will all + contain the same string, the same thing specified by INSTALL_DIR. + + DTOOL_INSTALL_OTHER + PANDA_INSTALL_OTHER + DIRECT_INSTALL_OTHER + (etc). + + These variables have the same meaning as the above, except that they + are intended to be used from a different package. That is, if code + in the Panda source tree needs to reference an installed file from + Dtool, it should expect to find it in $[DTOOL_INSTALL_OTHER].