mirror of
https://github.com/Sneed-Group/Poodletooth-iLand
synced 2024-12-24 12:12:36 -06:00
885 lines
38 KiB
Text
885 lines
38 KiB
Text
|
|
///////////////////////////////////////////////////////////////////////
|
|
// 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.
|