panda3d/doc/INSTALL-MK

///////////////////////////////////////////////////////////////////////
// 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 'makepanda' system.
///////////////////////////////////////////////////////////////////////

Panda3D Install --- using the 'makepanda' system.

MAKE SURE YOU HAVE ALL OF THE SOURCE CODE

The easiest way to download the source for panda is to download the
"source package" from the panda3d website.  If you downloaded a file
labeled "source package", then you have everything you need.  Skip to
the next section.

Alternately, it is possible to download the source in pieces. There
are three pieces:

    1. Source code from Sourceforge.
    2. Third-party tools.
    3. Sample programs.

You will need all three to use makepanda.  You can download all three
pieces from the panda website.  Look for the files labeled "Panda3D
source, piecewise, X of 3".  You can also obtain the first piece
directly from the sourceforge CVS server:

    CVSROOT=:pserver:[email protected]:/cvsroot/panda3d

Make sure you have all three pieces.  If you do, then your panda
directory will contain the following subdirectories:

    direct	- piece 1, source code from sourceforge
    dmodels	- piece 1, source code from sourceforge
    doc         - piece 1, source code from sourceforge
    dtool	- piece 1, source code from sourceforge
    Makefile	- piece 1, source code from sourceforge
    makepanda	- piece 1, source code from sourceforge
    models	- piece 1, source code from sourceforge
    panda	- piece 1, source code from sourceforge
    pandatool	- piece 1, source code from sourceforge
    ppremake	- piece 1, source code from sourceforge
    contrib     - piece 1, source code from sourceforge
    thirdparty  - piece 2, third party tools
    samples	- piece 3, sample programs

If you have all of these, you're ready to go.  If not, then you
must have missed a piece.

INVOKING MAKEPANDA

Makepanda is a script that builds panda, all the way through. To
invoke it under windows, change directory to the root of the panda
source tree and type this:

	makepanda\makepanda.bat

To invoke it under Linux or OSX, change directory to the root of
the panda source tree and type this:

	makepanda/makepanda.py

From this point forward, I will not be including the directory name or
the extension in my examples.  I will simply assume that you know to
add the correct extension as demanded by your operating system.


BUILDING PANDA: QUICK START

The easy way to build panda is to type:

	makepanda --everything

This will compile panda with all the features.  It can take several
hours, depending on the speed of your machine.

The resulting copy of panda will be found in a subdirectory 'built'
inside the source tree.


TESTING THE COMPILED PANDA

After building panda, you should test it before installing it.

The first step is to add the built/bin directory to your PATH.  This
is not strictly necessary, you can run the panda programs by typing
their paths explicitly, but it is much more convenient to set the
PATH.

Second, add the built/lib directory to your LD_LIBRARY_PATH.  This is
only necessary under Linux - Windows takes care of this automatically.
It is also possible to use the system ld.so.conf configuration file to
achieve the same effect, but LD_LIBRARY_PATH is more convenient for
quick-and-dirty testing.

Finally, change directory to one of the sample programs, and run the
sample program using 'ppython'.  For example,

  cd samples/Feature-Tutorials--Actors
  ppython Tut-Actors.py

If this doesn't work, something is wrong, and there's no reason
to continue with the installation process.


INSTALLING PANDA

If you are using Windows, OSX or Linux distribution that supports DEB or
RPM packages, the recommended way to install Panda3D is to run makepanda
with the --installer option and then install the resulting .exe, .deb, .rpm
or .dmg package. This is a safe solution that makes sure all the files are
installed in the correct places and all the paths are configured correctly.
More information can be found below.

If you want to install Panda3D manually, however, the first step is to
copy 'samples' into the built subdirectory, and 'direct/src' into
'built/direct/src'.  Then, move the built directory anywhere you like
on your system.  For example, Linux users might want to do this:

  cp --recursive samples built/samples
  cp --recursive direct/src built/direct/src
  mv built /usr/local/panda3d

Windows users might want to do this:

  xcopy /IE samples built\samples
  xcopy /IE direct\src built\direct\src
  move built c:\Panda3D

Then, add the panda bin directory to your PATH.  Under Linux, it is
also necessary to add the panda lib directory to the system library
path.  It is usually possible to do so by editing the
file /etc/ld.so.conf.


INSTALLATION AND THE UNIX STANDARD FILESYSTEM LAYOUT

The installation instructions above will produce a fully-functional
installation of panda with a minimum number of steps.  However, the
installation will not conform to the Unix standards for filesystem
layout.

If you want a conformant installation, the most sensible approach is
to build a redhat RPM, debian DEB or MacOSX DMG, and then install
the package. The installation process will distribute the files
properly. Instructions for building a package can be found below.


MAKEPANDA COMMAND-LINE OPTIONS

The default invocation of makepanda is a good way to test panda on
your machine.  However, it compiles several features that you probably
don't need.  To disable the extra features, you need to specify
command-line options to makepanda.  If you invoke:

	makepanda --help

it will show you the available command-line options:

  --help            (print the help message you're reading now)
  --optimize X      (optimization level can be 1,2,3,4)
  --installer       (build an installer)
  --version         (set the panda version number)
  --lzma            (use lzma compression when building installer)
  --threads N       (use the multithreaded build system. see manual)

  --use-maya6       --no-maya6     (enable/disable use of MAYA6)
  --use-maya65      --no-maya65    (enable/disable use of MAYA65)
  --use-maya7       --no-maya7     (enable/disable use of MAYA7)
  --use-maya8       --no-maya8     (enable/disable use of MAYA8)
  --use-maya85      --no-maya85    (enable/disable use of MAYA85)
  --use-maya2008    --no-maya2008  (enable/disable use of MAYA2008)
  --use-max6        --no-max6      (enable/disable use of MAX6)
  --use-max7        --no-max7      (enable/disable use of MAX7)
  --use-max8        --no-max8      (enable/disable use of MAX8)
  --use-max9        --no-max9      (enable/disable use of MAX9)
  --use-max2009     --no-max2009   (enable/disable use of MAX2009)
  --use-dx8         --no-dx8       (enable/disable use of DX8)
  --use-dx9         --no-dx9       (enable/disable use of DX9)
  --use-python      --no-python    (enable/disable use of PYTHON)
  --use-zlib        --no-zlib      (enable/disable use of ZLIB)
  --use-png         --no-png       (enable/disable use of PNG)
  --use-jpeg        --no-jpeg      (enable/disable use of JPEG)
  --use-tiff        --no-tiff      (enable/disable use of TIFF)
  --use-vrpn        --no-vrpn      (enable/disable use of VRPN)
  --use-fmod        --no-fmod      (enable/disable use of FMOD)
  --use-fmodex      --no-fmodex    (enable/disable use of FMODEX)
  --use-openal      --no-openal    (enable/disable use of OPENAL)
  --use-nvidiacg    --no-nvidiacg  (enable/disable use of NVIDIACG)
  --use-openssl     --no-openssl   (enable/disable use of OPENSSL)
  --use-freetype    --no-freetype  (enable/disable use of FREETYPE)
  --use-fftw        --no-fftw      (enable/disable use of FFTW)
  --use-artoolkit   --no-artoolkit (enable/disable use of ARTOOLKIT)
  --use-ode         --no-ode       (enable/disable use of ODE)
  --use-directcam   --no-directcam (enable/disable use of DIRECTCAM)
  --use-opencv      --no-opencv    (enable/disable use of OPENCV)
  --use-ffmpeg      --no-ffmpeg    (enable/disable use of FFMPEG)
  --use-pandatool   --no-pandatool (enable/disable use of PANDATOOL)

  --nothing         (disable every third-party lib)
  --everything      (enable every third-party lib)

Makepanda shows you all the available options, not all of which may be
relevant to your operating system.  For example, makepanda can build a
plugin for 3D Studio Max.  However, there is no 3D Studio Max for
Linux, so the options --use-max# are irrelevant under Linux.


SELECTING PANDA FEATURES

Panda contains a large number of optional features.  For example, if
panda is compiled with PNG support, then panda will be able to load
textures from PNG image files.

Some of these features require the use of bulky third-party libraries.
For example, 'helix' is a streaming video library from real networks.
If you do not plan on using streaming video in your 3D world, then
you may be interested in compiling panda without helix.  This will
shave several megabytes off of the panda libraries.

To select panda features, you need to specify one of two different
command-line options:

    makepanda --everything
    makepanda --nothing

You can follow either of these with a list of specific exceptions.
For example, you can say:

    makepanda --everything --no-helix --no-openssl
    makepanda --nothing --use-zlib --use-png

Note that 'makepanda' is a new tool.  The panda3d team has not had
time to test every combination of options.  It is likely that most
combinations do not work.  The only combination we can vouch for at
this time is '--everything'.  In the next release, we hope to be able
to vouch for a large number of different combinations.


USING YOUR OWN LIBRARIES

Panda3D uses a number of third-party libraries: libpng, libjpeg,
openssl, etc.  If you are using a Unix variant, many of these
libraries come with the operating system.  Panda3D will use these
OS-supplied libraries where possible, so if your OS comes with a copy
of libpng, Panda3D uses that.

For convenience, the panda source distribution includes precompiled
copies of many of the third-party libraries.  You will find these
libraries in a subdirectory labeled 'thirdparty'.  If you are happy
with the versions we have provided, then you don't need to do anything
special.

If you are not satisfied with the versions of the libraries we have
provided, you may supply your own versions.  To do so, duplicate the
'thirdparty' tree, substitute your own libraries, and then use
the --thirdparty option to point makepanda to your libraries.


THE EDIT-COMPILE-DEBUG CYCLE

A small caution: if you invoke 'makepanda' with one set of options,
and then invoke 'makepanda' using the exact same set of options, the
second time will be fast.  It will see that everything has already
been built, and it will do no actual compilation.  As a result,
makepanda can be used as part of an edit-compile-debug cycle.

However, if you invoke makepanda with a *different* set of options,
makepanda may need to recompile and relink a lot of files.  This is
because several of those options change the values of '#define'
headers, so changing the options requires a recompilation.

It is all too easy to accidentally invoke 'makepanda' with the wrong
options, thereby triggering an hour-long recompilation.  To avoid this
situation, we recommend that you write a short script containing the
options you intend to use regularly.  For example, I regularly compile
panda without helix.  I have a very short Windows BAT file called
"mkp.bat" that looks like this:

	@echo off
	makepanda --everything --no-helix

This helps me avoid accidentally typing makepanda with the wrong
options.


BUILDING A WINDOWS INSTALLER

Under Windows, makepanda can create an executable installer.  All you
need to do is pass the --installer option to makepanda.  The makepanda
option --lzma will cause the installer to be compressed with LZMA
compression, which is better, but it takes a long time to do the
compression.


BUILDING A LINUX DEB OR RPM PACKAGE

Under Linux, passing the --installer option to makepanda will
cause makepanda to try to build a deb or rpm package.  For this to
work, you have to be using a Linux distribution that includes either
the dpkg-deb or rpmbuild binary.


BUILDING A MACOSX DMG PACKAGE

Under Mac OSX, you can also use the --installer option, which will
generate a .dmg archive containing the Panda3D installation, which
needs to be placed in your /Applications/ directory.
The .dmg also contains a shell script that automatically sets up the
library and python search paths in your .bash_profile file so you don't
have to do that yourself every time you want to use Panda3D.