///////////////////////////////////////////////////////////////////////

// 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 <your-user-name> /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.