/////////////////////////////////////////////////////////////////////// // Caution: there are two separate, independent build systems: // 'makepanda', and 'ppremake'. Use one or the other, do not attempt // to use both. This file is part of the 'ppremake' system. /////////////////////////////////////////////////////////////////////// Panda3D Install --- using the 'ppremake' system. This document describes how to compile and install Panda 3D on a system for the first time. Panda is a complex project and is not trivial to install, although it is not really very difficult. Please do take the time to read this document before starting. Panda is known to build successfully on Linux, SGI Irix, and Windows NT/2000/XP. It should also be easily portable to other Unix-based OpenGL systems with little or no changes (please let us know if you try this). When compiled by Windows NT/2000/XP, it will then run on a Windows 98 system, but we have found that Windows 98 is not itself stable enough to compile the codebase without crashing. Before you begin to compile Panda, there are a number of optional support libraries that you may wish to install. None of these are essential; Panda will build successfully without them, but possibly without some functionality. * Python. Panda is itself a C++ project, but it can generate a seamless Python interface layer to its C++ objects and function calls. Since Python is an interpreted language with a command prompt, this provides an excellent way to get interactive control over the 3-D environment. However, it is not necessary to use the Python interface; Panda is also perfectly useful without Python, as a C++ 3-D library. Other scripting language interfaces are possible, too, in theory. Panda can generate an interface layer for itself that should be accessible by any scripting language that can make C function calls to an external library. We have used this in the past, for instance, to interface Panda with Squeak, an implementation of Smalltalk. At the present, the Python interface is the only one we actively maintain. We use Python 2.2, but almost any version should work; you can get Python at http://www.python.org . * NSPR. This is the Netscape Portable Runtime library, an OS compatibility layer written by the folks at Mozilla for support of the Netscape browser on different platforms. Panda takes advantage of NSPR to implement threading and network communications. At the present, if you do not have NSPR available Panda will not be able to fork threads and will not provide a networking interface. Aside from that, the PStats analysis tools (which depend on networking) will not be built without NSPR. We have compiled Panda with NSPR version 3 and 4.0, although other versions should also work. You can download NSPR from http://www.mozilla.org/projects/nspr/ . * VRPN, the "Virtual Reality Peripheral Network," a peripheral interface library designed by UNC. This is particularly useful for interfacing Panda with external devices like trackers and joysticks; without it, Panda can only interface with the keyboard and mouse. You can find out about it at http://www.cs.unc.edu/Research/vrpn . * libjpeg, libtiff, libpng. These free libraries provide support to Panda for reading and writing JPEG, TIFF, and PNG image files, for instance for texture images. Even without these libraries, Panda has built-in support for pbm/pgm/ppm, SGI (rgb), TGA, BMP, and a few other assorted image types like Alias and SoftImage native formats. Most Linux systems come with these libraries already installed, and the version numbers of these libraries is not likely to be important. You can download libjpeg from the Independent JPEG group at http://www.ijg.org , libtiff from SGI at ftp://ftp.sgi.com/graphics/tiff , and libpng from http://www.libpng.org . * zlib. This very common free library provides basic compression/decompression routines, and is the basis for the Unix gzip tool (among many other things). If available, Panda uses it to enable storing compressed files within its native multifile format, as well as in a few other places here and there. It's far from essential. If you don't have it already, you can get it at http://www.gzip.org/zlib . * Fmod. This is a free sound library that our friends at CMU have recently integrated into Panda. It provides basic support for playing WAV files, MP3 files, and MIDI files within Panda. Get it at http://www.fmod.org . * Freetype. This free library provides support for loading TTF font files (as well as many other types of font files) directly for rendering text within Panda (using Panda's TextNode interface, as well as the whole suite of DirectGui 2-d widgets in direct). If you do not have this library, you can still render text in Panda, but you are limited to using fonts that have been pre-generated and stored in egg files. There are a handful of provided font files of this nature in the models directory (specifically, cmr12, cmss12, and cmtt12); these were generated from some of the free fonts supplied with TeX. This can be found at http://www.freetype.org ; you will need at least version 2.0. * OpenSSL. This free library provides an interface to secure SSL communications (as well as a normal, unsecured TCP/IP library). It is used to implement the HTTP client code in Panda for communicating with web servers and/or loading files directly from web servers, in both normal http and secure https modes. It also provides some basic encryption services, allowing encrypted files to be stored in metafiles (for instance). If you do not have any need to contact web servers with your Panda client, and you have no interest in encryption, you do not need to install this library. Find it at http://www.openssl.org . We used version 0.9.6 or 0.9.7, but if there is a more recent version it should be fine. * FFTW, the "Fastest Fourier Transform in the West". This free whimsically-named library provides the mathematical support for compressing animation tables into Panda's binary bam format. If enabled, animation tables can be compressed in a lossy form similar to jpeg, which provides approximately a 5:1 compression ratio better than gzip alone even at the most conservative setting. If you don't need to have particularly small animation files, you don't need this library. Get it at http://www.fftw.org . * Gtk--. This is a C++ graphical toolkit library, and is only used for one application, the PStats viewer for graphical analysis of real-time performance, which is part of the pandatool package. Gtk-- only compiles on Unix, and primarily Linux; it is possible to compile it with considerable difficulty on Irix. (On Windows, you don't need this, since you will use the pstats viewer built in the win-stats subdirectory instead.) We have used version 1.2.1. You can find it at http://www.gtkmm.org . PANDA'S BUILD PHILOSOPHY Panda is divided into a number of separate packages, each of which compiles separately, and each of which generally depends on the ones before it. The packages are, in order: dtool - this defines most of the build scripts and local configuration options for Panda. It also includes the program "interrogate," which is used to generate the Python interface, as well as some low-level libraries that are shared both by interrogate and Panda. It is a fairly small package. panda - this is the bulk of the C++ Panda code. It contains the 3-D engine itself, as well as supporting C++ interfaces like networking, audio, and device interfaces. Expect this package to take from 30 to 60 minutes to build from scratch. You must build and install dtool before you can build panda. direct - this is the high-level Python interface to Panda. Although there is some additional C++ interface code here, most of the code in this package is Python; there is no reason to install this package if you are not planning on using the Python interface. DIRECT is an acronym, and has nothing to do with DirectX. You must build and install dtool and panda before you can build direct. pandatool - this is a suite of command-line utilities, written in C++ using the Panda libraries, that provide useful support functionality for Panda as a whole, like model-conversion utilities. You must build and install dtool and panda before you can build pandatool, although it does not depend on direct. pandaapp - this holds a few sample applications that link with panda (and pandatool), but are not generally useful enough to justify putting them in pandatool. Most of these are not actually graphical applications; they just take advantage of the various support libraries (like HTTPClient) that Panda provides. At the moment, most people probably won't find anything useful here, but you're welcome to browse; and we will probably add more applications later. You must build and install dtool, panda, anda pandatool before you can build pandaapp. In graphical form, here are the packages along with a few extras: +------------------------------+ | Your Python Application Here | +------------------------------+ | | +-----------+ | | pandaapp | | +-----------+ | | V V +--------+ +-----------+ +---------------------------+ | direct | | pandatool | | Your C++ Application Here | +--------+ +-----------+ +---------------------------+ | | | +-------------+-------------------/ V +-------+ | panda | +-------+ | V +-------+ | dtool | +-------+ The arrows above show dependency. Usually, these packages will be installed as siblings of each other within the same directory; the build scripts expect this by default, although other installations are possible. In order to support multiplatform builds, we do not include makefiles or project files with the sources. Instead, all the compilation relationships are defined in a series of files distributed throughout the source trees, one per directory, called Sources.pp. A separate program, called ppremake ("Panda pre-make") reads the various Sources.pp files, as well as any local configuration definitions you have provided, and generates the actual makefiles that are appropriate for the current platform and configuration. It is somewhat akin to the idea of GNU autoconf ("configure"), although it is both less automatic and more general, and it supports non-Unix platforms easily. HOW TO CONFIGURE PANDA FOR YOUR ENVIRONMENT When you run ppremake within a Panda source tree, it reads in a number of configuration variable definitions given in the file Config.pp in the root of the dtool package, as well as in a custom Config.pp file that you specify. Many of the variables in dtool/Config.pp will already have definitions that are sensible for you; some will not. You must customize these variables before you run ppremake. Normally, rather than modifying dtool/Config.pp directly, you should create your own, empty Config.pp file. By default, this file should be stored in the root of the Panda install directory, as specified when you built ppremake, but you may put it elsewhere if you prefer by setting the environment variable PPREMAKE_CONFIG to its full filename path (more on this in the platform-specific installation notes, below). The definitions you give in your personal Config.pp file will override those given in the file within dtool. It is also possible simply to modify dtool/Config.pp, but this is not recommended as it makes it difficult to remember which customizations you have made, and makes installing updated versions of Panda problematic. The syntax of the Config.pp file is something like a cross between the C preprocessor and Makefile syntax. The full syntax of ppremake input scripts is described in more detail in another document, but the most common thing you will need to do is set the value of a variable using the #define statement (or the mostly equivalent #defer statement). Look in dtool/Config.pp for numerous examples of this. Some of the variables you may define within the Config.pp file hold a true or a false value by nature. It is important to note that you indicate a variable is true by defining it to some nonempty string (e.g. "yes" or "1"), and false by defining it to nothing. For example: #define HAVE_DX9 1 Indicates you have the DirectX SDK installed, while #define HAVE_DX9 Indicates you do not. Do not be tempted to define HAVE_DX9 to no or 0; since these are both nonempty strings, they are considered to represent true! Also, don't try to use a pair of quotation marks to represent the empty string, since the quotation marks become part of the string (which is thus nonempty). The comments within dtool/Config.pp describe a more complete list of the variables you may define. The ones that you are most likely to find useful are: INSTALL_DIR - this is the prefix of the directory hierarchy into which Panda should be installed. If this is not defined, the default value is compiled into ppremake. A full description on setting this parameter is given below in the section describing how to build ppremake. On Unix systems this is taken from the --prefix parameter to configure (usually /usr/local/panda); for Windows users it is specified in config_msvc.h, and is set to C:\Panda3d unless you modify it. OPTIMIZE - define this to 1, 2, 3, or 4. This is not the same thing as compiler optimization level; our four levels of OPTIMIZE define broad combinations of compiler optimizations and debug symbols: 1 - No compiler optimizations, full debug symbols Windows: debug heap 2 - Full compiler optimizations, debug symbols Windows: debug heap 3 - Full compiler optimizations, Unix: no debug symbols Windows: non-debug heap, debug symbols available in pdb files 4 - Full optimizations, no debug symbols, and asserts removed Windows: non-debug heap Usually OPTIMIZE 3 is the most appropriate choice for development work. We recommend OPTIMIZE 4 only for final QA and/or distribution of a shippable product, never for any development or alpha testing; and we recommend OPTIMIZE levels 1 and 2 only for active development of the C++ code within Panda. PYTHON_IPATH / PYTHON_LPATH / PYTHON_LIBS - the full pathname to Python header files, if Python is installed on your system. As of Python version 2.0, compiling Python interfaces doesn't require linking with any special libraries, so normally PYTHON_LPATH and PYTHON_LIBS are left empty. You definitely need to set PYTHON_IPATH, however, if you wish to compile Panda so that it can be used from Python. NSPR_IPATH / NSPR_LPATH / NSPR_LIBS - the full pathname to NSPR header and library files, and the name of the NSPR library, if NSPR is installed on your system. VRPN_IPATH / VRPN_LPATH / VRPN_LIBS - the full pathname to VRPN header and library files, and the name of the VRPN libraries, if VRPN is installed on your system. DX9_IPATH / DX9_LPATH / DX9_LIBS - the full pathname to the DirectX 9 SDK header and library files, if you have installed this SDK. (You must currently install this SDK in order to build DirectX9 support for Panda.) GL_IPATH / GL_LPATH / GL_LIBS - You get the idea. (Normally, OpenGL is installed in the standard system directories, so you can leave GL_IPATH and GL_LPATH empty. But if they happen to be installed somewhere else on your machine, you can fill in the pathnames here.) Similar *_IPATH / *_LPATH / *_LIBS variables for other optional third-party libraries. HOW TO BUILD PANDA ON A UNIX SYSTEM First, make a subdirectory to hold the Panda sources. This can be anywhere you like; in these examples, we'll assume you build everything within a directory called "panda3d" in your home directory. mkdir ~/panda3d You should also create the directory into which panda should be installed. The default installation directory is /usr/local/panda. You may choose an alternate installation directory by using the --prefix parameter to the ppremake configure script, described below. We recommend giving yourself write permission to this directory, so that you can run 'make install' and similar scripts that will need to write to this installation directory, without having to be root. su root mkdir /usr/local/panda chown /usr/local/panda exit Whatever you choose for your installation directory, you should make sure the bin directory (e.g. /usr/local/panda/bin) is included on your search path, and the lib directory (e.g. /usr/local/panda/lib) is on your LD_LIBRARY_PATH. If you use a C-shell derivative like tcsh, the syntax for this is: set path=(/usr/local/panda/bin $path) setenv LD_LIBRARY_PATH /usr/local/panda/lib:$LD_LIBRARY_PATH If you have a Bourne-shell derivative, e.g. bash, the syntax is: PATH=/usr/local/panda/bin:$PATH LD_LIBRARY_PATH=/usr/local/panda/lib:$LD_LIBRARY_PATH export LD_LIBRARY_PATH You must now compile ppremake before you can begin to compile Panda itself. Generally, you do something like the following: cd ~/panda3d/ppremake ./configure make make install If the configure script does not already exist, read the document BUILD_FROM_CVS.txt in the ppremake source directory. As mentioned above, the default installation directory is /usr/local/panda. Thus, ppremake will install itself into /usr/local/panda/bin. If you prefer, you can install Panda into another directory by doing something like this: ./configure --prefix=/my/install/directory make make install Now you should create your personal Config.pp file, as described above, and customize whatever variables are appropriate. By default, ppremake will look for this file in the root of the install directory, e.g. /usr/local/panda/Config.pp. If you want to put it somewhere else, for instance in your home directory, you must set the PPREMAKE_CONFIG environment variable to point to it: setenv PPREMAKE_CONFIG ~/Config.pp In bash: PPREMAKE_CONFIG=~/Config.pp export PPREMAKE_CONFIG You may find it a good idea to make this and other environment settings in your .cshrc or .bashrc file so that they will remain set for future sessions. Now you can test the configuration settings in your Config.pp file: cd ~/panda3d/dtool ppremake When you run ppremake within the dtool directory, it will generate a file, dtool_config.h (as well as all of the Makefiles). This file will be included by all of the Panda3D sources, and reveals the settings of many of the options you have configured. You should examine this file now to ensure that your settings have been made the way you expect. Note that ppremake will also try to create several subdirectories in the install directory, so you must have write access to the install directory in order for ppremake to run completely successfully. If you did not choose to give yourself write access to the install directory, you may run ppremake as root; in this case we recommend running ppremake first as a normal user in order to compile, and then running ppremake again as root just before running make install as root. Now that you have run ppremake, you can build the Panda3D sources. Begin with dtool (the current directory): make make install Once you have successfully built and installed dtool, you can then build and install panda: cd ~/panda3d/panda ppremake make make install After installing panda, you are almost ready to run the program "pview," which is a basic model viewer program that demonstrates some Panda functionality (see HOW TO RUN PANDA, below). Successfully running pview proves that Panda is installed and configured correctly (at least as a C++ library). If you wish, you may also build direct. You only need to build this if you intend to use the Python interfaces. cd ~/panda3d/direct ppremake make make install And you may build pandatool. You only need to build this if you want to take advantage of model conversion utilities for Panda like maya2egg and egg2bam, or if you want to use other tools like pstats. cd ~/panda3d/pandatool ppremake make make install HOW TO BUILD PANDA ON A WINDOWS SYSTEM, USING CYGWIN Cygwin is a set of third-party libraries and tools that present a very Unix-like environment for Windows systems. If you prefer to use a Unix environment, Cygwin is the way to go. You can download Cygwin for free from http://www.cygwin.com. Panda can build and run within a Cygwin environment, but it does not require it. Note that Cygwin is used strictly as a build environment; the Cygwin compiler is not used, so no dependency on Cygwin will be built into Panda. The Panda DLL's that you will generate within a Cygwin environment will be exactly the same as those you would generate in a non-Cygwin environment; once built, Panda will run correctly on any Win32 machine, with or without Cygwin installed. If you do not wish to install Cygwin for your build environment, see the instructions below. If you wish to use Cygwin, there is one important point to keep in mind. Panda internally uses a Unix-like filename convention; that is, forward slashes (instead of backslashes) separate directory components, and there is no leading drive letter on any filename. These Unix-like filenames are mapped to Windows filenames (with drive letters and backslashes) when system calls are made. Cygwin also uses a Unix-like filename convention, and uses a series of mount commands to control the mapping of Unix filenames to Windows filenames. Panda is not itself a Cygwin program, and does not read the Cygwin mount definitions. That's important enough it's worth repeating. Panda is not aware of the Cygwin mount points. So a Unix-like filename that makes sense to a Cygwin command may not be accessible by the same filename from within Panda. However, you can set things up so that most of the time, Cygwin and Panda agree, which is convenient. To do this, it is important to understand how Panda maps Unix-like filenames to Windows filenames. * Any relative pathname (that is, a pathname that does not begin with a leading slash) is left unchanged, except to reverse the slashes. * Any full pathname whose topmost directory component is *not* a single letter is prepended with the contents of the environment variable PANDA_ROOT. * Any full pathname whose topmost directory component *is* a single letter is turned into a drive letter and colon followed by the remainder of the path. For example, /c/windows/system is turned into C:\windows\system. The expectation is that most of the files you will want to access within Panda will all be within one directory structure, which you identify by setting the PANDA_ROOT variable. Generally, when you are using Cygwin, you will want to set this variable to be the same thing as the root of your Cygwin tree. For instance, typically Cygwin installs itself in C:\Cygwin. This means that when you reference the directory /usr/local/bin within Cygwin, you are actually referring to C:\Cygwin\usr\local\bin. You should therefore set PANDA_ROOT to C:\Cygwin, so that /usr/local/bin within Panda will also refer to C:\Cygwin\usr\local\bin. To sum up: to use Panda within a Cygwin environment, In tcsh: setenv PANDA_ROOT 'C:\Cygwin' or in bash: PANDA_ROOT='C:\Cygwin' export PANDA_ROOT (In fact, you do not actually have to set PANDA_ROOT if Cygwin is installed into C:\Cygwin, since this is Panda's default behavior if C:\Cygwin exists. But it's important to understand what Panda is doing to remap directories, and in particular that there is no relationship to any actual Cygwin mount points.) There is one additional point: you will need to ensure that the Visual Studio command-line utilities (like cl.exe) are available on your path. Set your path appropriately to point to them, if necessary (or run vcvars32.bat to do it for you; see the paragraph below.) Follow the instructions under HOW TO BUILD PANDA FOR A UNIX ENVIRONMENT, above. HOW TO BUILD PANDA ON A WINDOWS SYSTEM, WITHOUT CYGWIN You will have to make sure that you installed the command-line utilities on your system path when you installed Visual Studio, or you can run the batch file vcvars32.bat to put these utilities on your path for the current session (this batch file is in a directory like c:\Program Files\Microsoft Visual Studio .Net\Vc7\bin). Microsoft provides a command-line make utility with Visual Studio called nmake, although it's nowhere near as robust as the GNU make utility provided with Cygwin. But Panda can generate Makefiles that follow the nmake convention, and will do so by default if your ppremake was not built with the Cygwin tools. You will need a directory for holding the installed Panda. This can be anywhere you like; the default is C:\Panda3d. If you choose to specify otherwise you should modify the INSTALL_DIR line in ppremake\config_msvc.h before you build ppremake (below). (Alternatively, you can leave ppremake alone and simply redefine INSTALL_DIR in your Config.pp file, but then you will also need to define the environment variable PPREMAKE_CONFIG to point to your Config.pp.) md C:\Panda3d You will first need to build a copy of ppremake.exe. There is a Microsoft VC7 project file in the ppremake directory that will build this. Once it is built, copy it to the Panda bin directory (which you will have to make yourself). This will be a directory called "bin" below the root of the installed directory you created above; for instance, C:\Panda3d\bin. Make sure the Panda bin and lib directories are on your path, and set a few environment variables for building. We suggest creating a file called PandaEnv.bat to hold these commands; then you may invoke this batch file before every Panda session to set up your environment properly. Alternatively, you may make these definitions in the registry. path C:\Panda3d\bin;C:\Panda3d\lib;%PATH% set PANDA_ROOT=C:\ Setting PANDA_ROOT is optional; it specifies the default drive Panda will search for file references. (Panda internally uses a Unix-like filename convention, which does not use leading drive letters. See the bullet points in the Cygwin section, above, describing the rules Panda uses to map its Unix-like filenames to Windows filenames.) Now make a directory for building Panda. This may be different from the directory, above, that holds the installed Panda files; or it may be the same. In this example we assume you will be building in the same directory, C:\Panda3d. Now set up your personal Config.pp file to control your local configuration settings, as described above. By default, ppremake will look for this file in the root of the install directory, e.g. C:\Panda3d\Config.pp; if you want to put it somewhere else you should define the environment variable PPREMAKE_CONFIG to the full path to your Config.pp. Use your favorite text editor to add the appropriate lines to your Config.pp to define the correct paths to the various third-party packages you have installed on your system. See HOW TO CONFIGURE PANDA FOR YOUR ENVIRONMENT, above. edit C:\Panda3d\Config.pp Now you can test the configuration settings in your Config.pp file: C: cd \Panda3d\dtool ppremake When you run ppremake within the dtool directory, it will generate a file, dtool_config.h (as well as all of the Makefiles). This file will be included by all of the Panda3D sources, and reveals the settings of many of the options you have configured. You should examine this file now to ensure that your settings have been made the way you expect. Now that you have run ppremake, you can build the Panda3D sources. Begin with dtool (the current directory): nmake nmake install Once you have successfully built and installed dtool, you can then build and install panda: cd \Panda3d\panda ppremake nmake nmake install After installing panda, you are almost ready to run the program "pview," which is a basic model viewer program that demonstrates some Panda functionality (see HOW TO RUN PANDA, below). Successfully running pview proves that Panda is now installed and configured correctly (at least as a C++ library). If you wish, you may also build direct. You only need to build this if you intend to use the Python interfaces. cd \Panda3d\direct ppremake nmake nmake install And you may build pandatool. You only need to build this if you want to take advantage of model conversion utilities for Panda like maya2egg and egg2bam, or if you want to use other tools like pstats. cd \Panda3d\pandatool ppremake nmake nmake install HOW TO RUN PANDA Once Panda has been successfully built and installed, you should be able to run pview to test that everything is working (you might need to type rehash first if you use csh): pview If you get an error about some shared library or libraries not being found, check that your LD_LIBRARY_PATH setting (on Unix) or your PATH (on Windows) includes the directory in which all of the Panda libraries have been installed. (This is normally $INSTALL_DIR/lib, or whatever you set INSTALL_DIR to followed by "lib". On Unix, this defaults to /usr/local/panda/lib. If you have redefined INSTALL_LIB_DIR in your Config.pp, for instance to define Panda as a native Python module, you should use that directory instead.) If all goes well, pview should open up a window with a blue triangle. You can use the mouse to move the triangle around. You can also pass on the command line the name of an egg or bam file, if you have one (look in the models directory for some sample egg files), and pview will load up and display the model. There are several files in the $INSTALL_DIR/etc directory with the filename extension .prc; these are Panda Runtime Configuration files. These are different from the Config.pp file, which controls the way Panda is compiled and is only used at build time. The prc files are read in every time Panda is started and control the way Panda behaves at runtime. The system-defined prc files begin with digits, so that they sort to the top of the list and are read first (and so that you may define one or more additional files that are read afterwards and that will therefore override the values specified in these system files). The digits also imply an ordering between the prc files. We recommend that you name your own prc file(s) beginning with letters, unless for some reason you need a file to be loaded before one of the system-defined prc files. We suggest creating a file in $INSTALL_DIR/etc called Config.prc, into which you will put your own custom configuration options. For instance, if you want to run using OpenGL instead of the Windows default of DirectX9, you can add the line: load-display pandagl to your Config.prc file. If you choose not to do this at this time, you can just leave this file empty for now; however, we do recommend creating at least an empty Config.prc file as a placeholder into which you can add your custom configuration options later. The complete list of available configuration options is very large and is not fully documented; but there are other documents that list several particularly useful config variables. These are sometimes referred to as "Configrc" variables because an older Panda convention named this file Configrc instead of Config.prc. If you want to load Config.prc from other than the compiled-in default directory of $INSTALL_DIR/etc, set the environment variable: PRC_DIR=/my/home/directory export PRC_DIR Where /my/home/directory is the name of your home directory (or wherever you put the Config.prc file). Note that if you redefine PRC_DIR, you will no longer automatically load the standard prc files that were installed into $INSTALL_DIR/etc (so you should consider copying these files into the same directory). It is possible to configure Panda to search for prc files in more than one directory, but that's a little more complicated and is outside the scope of this document. HOW TO BUILD THE PYTHON INTERFACES You may stop now if you only intend to use Panda as a C++ library. However, if you wish to use Panda from within Python, you must now generate the Python interfaces. There are two parts to the Python interface for Panda. The first part is a series of wrapper functions that are compiled into the Panda libraries themselves, along with associated *.in files that describe the class hierarchy. If you defined PYTHON_IPATH correctly in your Config.pp file, then Python should have been detected by ppremake, and it would have generated makefiles to build these wrappers automatically. (You would have seen the program "interrogate" running within each directory as panda was building, and you will have a number of *.in files now installed into $INSTALL_DIR/etc.) If, for some reason, the interrogate program did not run, perhaps because you defined an invalid directory in PYTHON_IPATH, you can go back and fix this now, and simply re-run ppremake and make install again in each of dtool, panda, and direct. To make Panda accessible to Python, you will need to add $INSTALL_DIR/lib to your PYTHONPATH variable, e.g.: setenv PYTHONPATH ${PYTHONPATH}:/usr/local/panda/lib Or, on Windows: set PYTHONPATH=%PYTHONPATH%;C:\Panda3d\lib We recommend the PYTHONPATH approach for most users, since it keeps all of the Panda files within one directory and doesn't clutter up the Python distribution. However, if you only intend to use Panda from Python, and especially if you want to make it accessible to multiple users, it may be more attractive to install the Panda libraries as a standard Python module, so that it is not necessary to modify your PYTHONPATH variable; see "Installing Panda as a standard Python module", below. The second part to the Python interface is a series of generated Python wrapper classes, for each C++ class detected by interrogate. These classes must be generated after all of the C++ code has been compiled and installed. Execute the following command (you might need to type rehash first if you use csh): genPyCode This is a script that was installed into $INSTALL_DIR/bin as part of the build of direct. It invokes Python to read the *.in files generated by interrogate, and generates the appropriate wrapper functions, which are then written into $INSTALL_DIR/lib/pandac. (There will be several hundred generated Python modules, which are normally "squeezed" into a single file called PandaModules.pyz using PythonWare's SqueezeTool. This squeeze step gives a significant load-time speedup, especially on Windows; but if it causes problems, you can use the option -n, e.g. 'genPyCode -n', to avoid it.) You will need to re-run this script only if the Panda interface changes, e.g. if a class is added or a method's parameters change. You should certainly re-run it any time you update and install a new version of Panda. Installing Panda as a native Python module Panda can be optionally configured to install its run-time interfaces into the Python installation directory, instead of into the normal $INSTALL_DIR/lib directory. This means you can run Panda from Python without having to set your PYTHONPATH variable, but it does clutter up your Python distribution a bit. To do this, simply add something like the following line to your Config.pp: #define INSTALL_LIB_DIR /usr/lib/python2.2/site-packages Where you give the actual path to the site-packages directory for your particular installation of Python. On Windows, this will probably look something like this: #define INSTALL_LIB_DIR C:\Python22\Lib\site-packages Then go back and re-run ppremake and make install in each of dtool, panda, and direct, and then re-run genPyCode, to install the Panda libraries and Python files directly into the Python site-packages directory. You may also need to set your LD_LIBRARY_PATH (on Unix) or PATH (on Windows) to reference this new directory instead of $INSTALL_DIR/lib, especially if you want to be able to run any of the Panda standalone programs occasionally, like pview or any of the model converters. Unix users should note that you must have write permission to the site-packages directory in order to install files there. You may choose to run these install steps (ppremake, make install, genPyCode) as root to avoid this problem. If you encounter difficulty running genPyCode as root, make sure that you still have LD_LIBRARY_PATH defined appropriately once you have become root. Testing the Python interface Assuming that you have already set up your Config.prc file and tested that pview works, as described above in HOW TO RUN PANDA, you should now be ready to try to run Panda from within Python. Start up a Python shell and type the following command: Python 2.2.2 (#37, Feb 10 2003, 18:00:06) [MSC 32 bit (Intel)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> import direct.directbase.DirectStart You should see a graphics window come up, very similar to the one you saw when you ran pview. To load a particular model file into the scene, try something like this: >>> m = loader.loadModel('/c/Panda3d/models/smiley.egg') >>> m.reparentTo(render) >>> run() Note that Panda expects a forward-slash convention for pathnames, with no leading drive letter, even on a Windows system. See the full description of how Panda maps these pathnames to Windows pathnames in HOW TO BUILD PANDA ON A WINDOWS SYSTEM, USING CYGWIN, above. You can now move the scene around with the mouse, just as in pview (you may need to pull the camera back by dragging upwards while holding down the right mouse button in order to see the model). Congratulations! Panda 3D is now successfully installed. See the online documentation available at http://www.etc.cmu.edu/panda3d/ for more help about where to go next.