From 35dac69d04f98b50569bc8269fbf466b64e406bb Mon Sep 17 00:00:00 2001 From: David Rose Date: Wed, 13 Oct 2004 23:27:54 +0000 Subject: [PATCH] forgot to add this long ago --- panda/src/doc/howto.use_ppremake.txt | 66 ++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 panda/src/doc/howto.use_ppremake.txt diff --git a/panda/src/doc/howto.use_ppremake.txt b/panda/src/doc/howto.use_ppremake.txt new file mode 100644 index 0000000000..35bcb9f8ba --- /dev/null +++ b/panda/src/doc/howto.use_ppremake.txt @@ -0,0 +1,66 @@ +This document tries to describe how the various Sources.pp files +should be set up within the Panda tree (or a related tree like Direct +or Pandatool), to add new directories, for instance, or modify the +build rules for an existing directory. For a general treatise on the +full syntax and semantics of the ppremake scripting language, see the +ppremake-*.txt files in this directory. + + + + + +TARGET specifies the name of the output file that will be generated, +not a directory name. The target may be a dll, lib, or executable +depending on the type of target (lib_target, static_lib_target, or +bin_target). For instance, in vrpn/Sources.pp, the target name is +pvrpn; this means that "make" within the directory will in principle +generate a file called libpvrpn.dll. + +The TARGET name is particularly confusing for people who only see the +Windows build, however, because on Windows we don't actually generate +a libpvrpn.dll file, or for that matter any other dll file that's +named in the COMPONENT_LIBS of some metalib, like +panda/metalibs/panda/Sources.pp. This is because of our limitation +with STL and DLL's (and also because the per-DLL overhead is fairly +high in Windows). + +The build design is that each subdirectory under panda/src should +generate its own shared library, a .dll file (or .so file on Unix). +Then the user would reference just the particular dll's that his +client application requires, e.g. libpgraph.dll to use the scene +graph, libdisplay.dll to actually do rendering, and libpvrpn.dll to +interface to VRPN. On Windows, however, we can't actually do that for +various reasons, so instead we provide one big metalib called +libpanda.dll which contains all of those pieces, and clients must link +with all of libpanda.dll even if they just want to use a subset of it. + +The fact that we don't actually generate a physical dll file for each +subdirectory on Windows is unimportant to the rest of the build +scripts, which act as if we do. For instance, the COMPONENT_LIBS line +in the panda/Sources.pp file names "pvrpn", as if there were a +libpvrpn.dll; this means that all of the files that are part of the +"pvrpn" target are added to libpanda.dll. (On Unix platforms, it +means we add libpvrpn.so to the list of libraries that are referenced +by libpanda.so.) + +The original intention of SOURCES is to list all of the source files +within this directory that go into the dll. This generally includes +.h files, .I files, and .cxx files. However, at some point one of our +programmers introduced COMBINED_SOURCES and INCLUDED_SOURCES, and he +removed those source files from the SOURCES list, which I think +confuses the whole thing; and I intend to clean this up at some point. +In the vrpn/Sources.pp directory, however, we only have the SOURCES +list, nice and clean. I don't know what you mean about hierarchy; +these files are all in the same directory, so there's just a linear +list of filenames. By convention, these should be kept in +alphabetical order, although it doesn't really matter that much. + +INSTALL_HEADERS names the header files that should be copied into the +public include directory for third-party packages (or other Panda +trees, like Direct) to reference. This makes a C++ public interface. + +IGATESCAN names the source files that are to be scanned by +interrogate. This makes a Python public interface. Most of the time, +we just say "IGATESCAN all" which means to scan all of the source +files in the directory. +