*** empty log message ***

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
+