diff --git a/panda/src/doc/install.txt b/panda/src/doc/install.txt deleted file mode 100644 index 2f58490502..0000000000 --- a/panda/src/doc/install.txt +++ /dev/null @@ -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 -