remove install.txt; superceded by panda3d/INSTALL

panda/src/doc/install.txt

@@ -1,391 +0,0 @@
-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
-