From 9eb4e434a89f9900567755b0f26ff73314ad641d Mon Sep 17 00:00:00 2001 From: David Rose Date: Tue, 29 May 2001 05:11:53 +0000 Subject: [PATCH] *** empty log message *** --- panda/src/doc/install.txt | 391 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 391 insertions(+) create mode 100644 panda/src/doc/install.txt diff --git a/panda/src/doc/install.txt b/panda/src/doc/install.txt new file mode 100644 index 0000000000..2f58490502 --- /dev/null +++ b/panda/src/doc/install.txt @@ -0,0 +1,391 @@ +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, Windows NT +and Windows 2000. 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 or 2000, it will +then run on a Windows 95 or 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.0; 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 audio interface (which depends on threads) and the + PStats analysis tools (which depend on networking) will not be built + without NSPR. You can download NSPR from http://www.mozilla.org . + +* 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 and libtiff. These free libraries provide support to Panda + for reading and writing JPEG and TIFF 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 libjpeg and libtiff already installed. You + can download libjpeg from the Independent JPEG group at + http://www.ijg.com , and libtiff from SGI at + ftp://ftp.sgi.com/graphics/tiff . (Actually, at the present libtiff + is included within the Panda source tree, and so isn't needed or + used as a separate library. This will change one day.) + +* 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 may be possible + to compile it with considerable difficulty on Irix. You can get 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 one to two hours 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. + 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. + +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 configure variable definitions given in the file Config.pp in the +root of the dtool package. Many of these variables 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 would +create your own Config.pp file in a safe place (for instance, in your +personal home directory) and redefine the variables you need there. +The definitions you give in your personal Config.pp file will override +those in the source directory. You will need to set an environment +variable PPREMAKE_CONFIG to the full filename path of your personal +Config.pp (more on this in the platform-specific installation notes, +below). It is also possible simply to modify dtool/Config.pp, but +this is not recommended as it makes it difficult to install updated +versions of Panda. + +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. Look in dtool/Config.pp for numerous +examples of this. + +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. By default, this is + /usr/local/panda, a fine convention for Unix machines although a + little questionable for Windows environments. + + 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 + 2 - Full compiler optimizations, full debug symbols + (if the compiler supports this) + 3 - Full compiler optimizations, no debug symbols + 4 - Full optimizations, no debug symbols, and asserts removed + + Usually OPTIMIZE 2 or 3 is the most appropriate choice for + development work. + + 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. + + 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. + + GL_IPATH / GL_LPATH / GL_LIBS - You get the idea. + + + +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 "player" in your home directory. + + mkdir ~/player + +Now download and compile ppremake. You will need the latest ppremake +source tarball, for instance ppremake-1.00.tar.gz. It uses GNU +autoconf to configure itself, an increasingly standard installation +system. Generally, you do something like the following: + + cd ~/player + gunzip < ppremake-1.00.tar.gz | tar xvf - + cd ppremake-1.00 + ./configure + make + make install + +By default, ppremake will install itself in /usr/local/panda/bin, the +same directory that the other Panda binaries will install themselves +to. If you prefer, you can install it in another directory by doing +something like this: + + ./configure --prefix=/my/install/directory + +If you do this, you will also want to redefine INSTALL_DIR in your +Config.pp to be the same directory (see above). Wherever you install +it, you should make sure the bin directory is included on your search +path, and the corresponding lib directory (e.g. /usr/local/panda/lib) +is on your LD_LIBRARY_PATH (the following example assumes you are +using a csh derivative): + + set path=(/usr/local/panda/bin $path) + setenv LD_LIBRARY_PATH /usr/local/panda/lib:$LD_LIBRARY_PATH + +Now you should create your personal Config.pp file, as described +above, and customize whatever variables are appropriate. Be sure to +set the PPREMAKE_CONFIG environment variable to point to it. + + setenv PPREMAKE_CONFIG ~/Config.pp + +You may find it a good idea to make these environment settings in your +.cshrc file so that they will remain set for future sessions. + +Now you can unpack and build the Panda sources. Begin with dtool: + + cd ~/player + gunzip < dtool.tar.gz | tar xvf - + cd dtool + ppremake + make + make install + +Once you have successfully built and installed dtool, you can then +do the same thing for panda: + + cd ~/player + gunzip < panda.tar.gz | tar xvf - + cd panda + ppremake + make + make install + +After installing panda, you are almost ready to run the program +"demo," which is a model viewer (and general sandbox) that +demonstrates some basic Panda functionality. Successfully running +demo proves that Panda is now installed and configured correctly. +However, you must set up a Configrc file to set your runtime +configuration options before you can run Panda and open up a graphics +window. See HOW TO RUN PANDA, below. + + + +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 a free +version from http://www.cygwin.com which will have almost everything +you might need, or you can purchase a CD which has some additional +tools (including csh) that you might find useful. + +Panda can build and run within a Cygwin environment, but it does not +require it. If you do not wish to install Cygwin, see the +instructions below. + +If you wish to use Cygwin, there are 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, + + setenv PANDA_ROOT "C:\Cygwin" + +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 need a directory for holding the installed Panda. This can +be anywhere you like; in this example we'll assume you use a directory +called "pandadir" on the root of the C drive. + + md c:\pandadir + +Download the pre-compiled ppremake executable and the cygwin DLL. +Since ppremake is a Cygwin program (even though the rest of Panda is +not), you will need the DLL in order to run ppremake. Install these +files in pandadir\bin. + + md c:\pandadir\bin + move ppremake.exe c:\pandadir\bin + move cygwin1.dll c:\pandadir\bin + +Also make sure the Panda bin and lib directories are on your path. +You should consider extending your path in the registry so that these +directories will still be on your path in future sessions. + + path c:\pandadir\bin;c:\pandadir\lib;%PATH% + +Now make a directory for building Panda. We suggest pandadir\build. + + md c:\pandadir\build + +Now set up your personal Config.pp file to control your local +configuration settings, as described above. We suggest putting it in +the root of the build directory. + + edit c:\pandadir\build\Config.pp + +Add at least the following line to your Config.pp file. (You may want +to add additional lines, according to your needs. See HOW TO +CONFIGURE PANDA FOR YOUR ENVIRONMENT, above.) + + #define INSTALL_DIR c:\pandadir + +Now set some more environment variables for building: + + set PANDA_ROOT=c:\ + set PPREMAKE_CONFIG=c:\pandadir\build\Config.pp + +Again, you may want to set these up in the registry. Setting +PANDA_ROOT 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 you should be able to unpack and build dtool. + + c: + cd \pandadir\build + unzip dtool.zip + cd dtool + ppremake + nmake + nmake install +