root/juggler/tags/1.1_dr_3/INSTALL.txt

                  Building and Installing the Juggler Project

  The Juggler Team

   $Date$

     ----------------------------------------------------------------------

   Table of Contents

   Introduction

                Important Notes for IRIX Users

                Important Note for Win32 Users

   Getting the Source Code

                How to get the Juggler Suite and external package
                dependencies

                Using cvs-gather

   Compiling

                Important Note Regarding Compiling

                Compiling the Juggler Suite of Tools

                Compiling individual tools in the Juggler Suite

Introduction

   This document explains how to build the modules of the Juggler Project
   from the source code. We begin by explaining some issues related to
   specific operating systems. We then explain how to get the source code
   from our CVS repository. (Those users who downloaded a pre-packaged source
   release can skip ahead to the section called "Using configure.pl"). We
   conclude with instructions on how to build VR Juggler and its individual
   components.

   Before reading further, we recommend that readers take a look at the Wiki
   page relating to building from CVS
   (http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs).
   It is a supplement to this document containing tips and reminders for
   those users building the CVS version of VR Juggler. It is not a
   replacement for this document, nor can it stand on its own as build
   instructions. You are reading the definitive build instructions; the Wiki
   page merely provides informal, extra information.

  Important Notes for IRIX Users

   Despite our best efforts, there are some issues related to compiling the
   Juggler Project on IRIX. We introduce them in this section and explain how
   to work around them.

    Perl Version

   There are many Perl scripts used as part of getting, configuring, and
   building the Juggler Suite of tools. In particular, two scripts required
   for compiling need Perl 5.005 or newer. The version of Perl that ships
   with IRIX 6.5 is very old (circa 1997) and does not work with many Perl
   scripts we have written. SGI provides a much newer version of Perl (5.6.1)
   with their freeware tools (http://freeware.sgi.com/). It will be necessary
   to install that version for our scripts to work. This version is typically
   installed as /usr/freeware/bin/perl.

   Once you have a modern Perl installed, you can run various Perl scripts as
   follows:

 /usr/freeware/bin/perl <script-name>

   The above will be required any time a Perl script fails with an error
   similar to the following:

 Perl 5.005 required--this is only version 5.00404, stopped at ./configure.pl line 35.
 BEGIN failed--compilation aborted at ./configure.pl line 35.

   Furthermore, it is highly recommended that the --with-perl argument be
   passed to configure.pl. This argument gives all the Autoconf-based
   configure scripts a hint about where the preferred version of Perl lives.
   If using /usr/freeware/bin/perl to run configure.pl, we recommend that the
   configure.pl command line appear similar to the following:

 /usr/freeware/bin/perl configure.pl --with-perl=/usr/freeware/bin

   Note that the value given to --with-perl is the directory where the perl
   executable can be found. The configure scripts will add this directory to
   the front of the search path when trying to find a suitable perl
   executable. Once it is found, all the Perl scripts used for configuration,
   compilation, and installation will use that executable.

   To simplify command execution somewhat, it can help to have
   /usr/freeware/bin (or whatever path is appropriate) in your path before
   /bin or /usr/bin or any of the other myriad directories where Perl might
   exist on IRIX. In such a situation, none of the above extra steps should
   be necessary. The correct version of Perl will be found simply by virtue
   of it being early in your path.

    MIPSpro Compiler Version

   Reports have been made on the VR Juggler mailing list regarding compile
   failures (including segmentation faults within the compiler) occur when
   using the MIPSpro Compilers Version 7.3.1.1m. We have found upgrading to
   Version 7.3.1.3m (or newer) fixes the problems.

   A new feature of VR Juggler 1.1 is support for GCC on IRIX. Users who do
   not have MIPSpro or cannot upgrade can compile and run VR Juggler (without
   OpenGL Performer support) using the version of GCC distributed by SGI. It
   can be downloaded from http://freeware.sgi.com/index-by-alpha.html for
   free. When configuring the source with configure.pl (described later), use
   the option --with-gcc.

  Important Note for Win32 Users

   VR Juggler 1.1 uses a lot of C++ templates. Some components of the system
   will not compile with MS Visual Studio 6.0, and as a result, we currently
   require the use of Visual Studio 7 (.NET) to compile the source code. We
   understand that this is an inconvenience, and we are interested in methods
   for compiling the code with Visual Studio 6. However, due to VC6's poor
   support for templates and the C++ standard in general, users need to be
   aware that it may not be possible.

Getting the Source Code

   This section is for those users who want to get the Juggler Project source
   code from the CVS repository on SourceForge. Those users who have
   downloaded a pre-packaged version of the source can skip ahead to the
   section called "Using configure.pl".

   Getting the source code takes a few steps. You have to first download or
   check out the Juggler Project source code and some external packages such
   as GMTL, CppDOM, Boost, and possibly NSPR. The steps are listed in the
   following subsections. The current list of required software packages is
   as follows:

     o GMTL (http://ggt.sf.net/): A generic math library that makes use of
       C++ templates and STL paradigms

     o CppDOM (http://www.sf.net/projects/xml-cppdom/): A lightweight,
       easy-to-use XML parser written in C++

     o Boost (http://www.boost.org/): A C++ library providing many powerful
       tools

     o Doozer++ (http://www.sf.net/projects/doozer/): A foundation the
       development of complex build systems using Autoconf and GNU make. This
       is the basis for the entire VR Juggler build system.

     o Doozer (http://www.sf.net/projects/doozer/): A foundation for rapid
       makefile development based on GNU make. This is needed for building
       the sample VR Juggler applications.

   The following lists semi-optional packages:

     o NSPR (http://www.mozilla.org/projects/nspr/): The Netscape Portable
       Runtime, which can be used by VPR for threading and sockets (required
       on Win32)

     o JDOM (http://www.jdom.org/): An XML parser for Java (required only for
       VjControl, the GUI for editing VR Juggler configuration files)

   The following describes how to get all of the above except JDOM and NSPR.
   These must be downloaded separately.

  How to get the Juggler Suite and external package dependencies

   You can optionally get the Juggler Project as a source code tarball from
   the website (http://www.vrjuggler.org/) or you can follow these steps to
   get the code from our CVS repository.

   1. Check out the 'juggler' module using CVS.

 cvs -d :pserver:anonymous@cvs.vrjuggler.sourceforge.net:/cvsroot/vrjuggler login
 cvs -z3 -d :pserver:anonymous@cvs.vrjuggler.sourceforge.net:/cvsroot/vrjuggler co juggler

   2. Get external packages that Juggler depends on. Typically you will run
       cvs-gather.pl, found in the top-level juggler directory. For most
       users, the follow command will do the job:

 ./cvs-gather.pl --verbose

       Ideally, users can just let the command run, but sometimes a password
       must be entered. The CVS password prompt will appear at such times.
       Each of the projects downloaded using cvs-gather come from
       SourceForge, and for anonymous CVS access there is no password. Hence,
       simply pressing the ENTER key will allow the download to continue.

       You can use the cvs-gather tool, or you can read the file Gatherrc and
       get the packages manually. If you choose not to use cvs-gather, you
       must be familiar with CVS and with the use of CVS tags to check out
       code. For more details about cvs-gather, see the section called "Using
       cvs-gather". If you choose to follow this step as shown above, you may
       skip ahead to the section called "Compiling".

  Using cvs-gather

   cvs-gather is a utility we include in the base juggler source directory to
   help you collect third-party (external) source code that the Juggler
   Project needs in order to build. To get help on using this tool, use one
   of the following (the second version gives much more detailed output):

 ./cvs-gather.pl --help
 ./cvs-gather.pl --manual

    Standard use of cvs-gather

   In most cases, cvs-gather can be used as follows:

 ./cvs-gather.pl

   All the output will be written to the file gather.log. If you would like
   to see the progress of CVS as it checks out files, run the command this
   way:

 ./cvs-gather.pl --verbose

    Advanced use of cvs-gather

   Use of cvs-gather is not required. You can limit what packages are
   downloaded. You can even skip cvs-gather altogether if you already have
   all the necessary packages in your system or if you feel like getting
   these packages manually. For a list of the package dependencies, refer to
   the file juggler/Gatherrc. For more information about the file format,
   refer to the cvs-gather manual.

   To limit which packages get downloaded through cvs-gather, use the
   --target option, as shown below:

 ./cvs-gather --target Boost,Doozer++

   or

 ./cvs-gather --target Boost --target Doozer++

   The names given as arguments to --target are the module names listed in
   juggler/Gatherrc. Any number of target module names may be listed.

   For cvs-gather to work, it uses a "gather rc" file. This file specifies
   the external project CVS locations. cvs-gather reads these CVS locations
   and then checks each one out locally for use in building the Juggler
   Project. There are three possible default names for a "gather rc" file:

   1. Gatherrc (in the working directory)

   2. .gatherrc (in the working directory)

   3. $HOME/.gatherrc

   cvs-gather searches for these three files by default in the order shown
   above. Alternatively, a user-defined file (deps.gatherrc, for example) can
   be named on the command line as follows:

 ./cvs-gather.pl --cfg=deps.gatherrc

   To simplify shared use of a single configuration file, the contents of the
   file may be overridden on the command line or through the use of an
   "overrides" file. The following shows such a file that overrides the
   CVSROOT settings in juggler/Gatherrc:

       #JugglerBaseStuff.CVSROOT=patrickh@cvs.vrjuggler.sourceforge.net:/cvsroot/vrjuggler
       Doozer.CVSROOT = patrickh@cvs.doozer.sourceforge.net:/cvsroot/doozer
       Doozer++.CVSROOT = patrickh@cvs.doozer.sourceforge.net:/cvsroot/doozer
       GMTL.CVSROOT = patrickh@cvs.ggt.sourceforge.net:/cvsroot/ggt                 

   The current Gatherrc only allows anonymous CVS access. To override that,
   we suggest making per-user override files. To use the override file, just
   add the argument --override=<filename> when running cvs-gather.

   The following shows how to run cvs-gather with your own overrides file
   (called my_gatheroverride):

 cvs-gather.pl --override=my_gatheroverride

   If all goes well, you'll get everything you need to compile.

Compiling

   In this section, we describe how to compile the Juggler Project. We focus
   on VR Juggler as a whole, but information about some of the individual
   components is provided later.

  Important Note Regarding Compiling

   You have downloaded developmental code. It may not be stable, and it may
   not even compile. Compiling VR Juggler itself can be a little complicated
   for anyone who does not have some background in Autoconf, C++, and make.

  Compiling the Juggler Suite of Tools

   This section explains how to get, configure, and compile all of the tools
   that make up VR Juggler. Each tool compiles to its own library and can be
   installed individually. (Refer to the README file in this directory for
   more information about the specific modules.)

    Configuring VR Juggler

   Every time you update the source code acquired from CVS and cvs-gather, it
   is recommended that you run autogen.sh. This script is found in the
   top-level juggler directory, and it is run as follows:

 ./autogen.sh

  Note

   On Win32, recent versions of Cygwin install Autoconf 2.13 and Autoconf
   2.5x. Similarly, Automake 1.4 and Automake 1.5 are installed. The former
   versions (2.13 and 1.4) are considered "stable" while the latter are
   "developmental". While the VR Juggler build system does work with either
   set on UNIX-based systems, the build system does not work with Automake
   1.5 on Win32. At this time, it is unclear why it does not work, but the
   following provides a workaround for running autogen.sh on Win32 using the
   default BASH environment:

 ACLOCAL=/usr/autotool/stable/bin/aclocal ./autogen.sh

   If you are using tcsh, use the following command instead:

 env ACLOCAL=/usr/autotool/stable/bin/aclocal ./autogen.sh

      Using configure.pl

   In the base juggler source directory, we have a "global" configure script
   written in Perl called configure.pl. To get the command-line options for
   this script, use one of the following (the second being much more
   detailed):

 ./configure.pl --help
 ./configure.pl --manual

   To configure your system, you will need to see what options all the
   Autoconf-based configure scripts in VR Juggler need. To get this text,
   enter:

 ./configure.pl --all-help

   configure.pl can run in a different "build" directory or in the directory
   where it resides. Here is how we (the Juggler Team) have been using it:

   1. Make a directory for compiling. There are many good reasons to do this
       away from the main source tree (though they will not be listed here).

 mkdir build.linux.posix

       This example using an ad hoc naming convention based on operating
       system and threading subsystem. Other examples could be
       build.irix.sproc, build.solaris.nspr, etc.

   2. Enter the new build directory.

 cd build.linux.posix

   3. Configure all the modules making up VR Juggler. This is when you must
       tell the module configure scripts where all the package dependencies
       are found. For this description, we will use the term <JDOMPATH> to
       refer to the JDOM installation. Assume that this is an absolute path
       (e.g., <JDOMPATH> = /home/user1/pkgs/jdom).

 ../configure.pl --prefix=$HOME/vrjuggler-2.0 --with-jdom="<JDOMPATH>/build/jdom.jar:<JDOMPATH>/lib/xerces.jar"

       On Win32, remember that the path is given as the full DOS drive path,
       but / should be used instead of \ as the path separator.

   By default, the configuration process will configure VR Juggler and all of
   its dependencies. This includes Sonix, which is an interesting special
   case. Sonix can make use of OpenAL or AudioWorks to provide spatialized
   sound in VR Juggler applications. If neither of those packages is found,
   Sonix will "stub out" its sound APIs. This means that Sonix and the VR
   Juggler Sound Manager can still be used in applications, but no audio will
   be heard at run time. See the section called "Sonix (individual)" for more
   information about how to configure Sonix to use OpenAL or AudioWorks.

   For example uses of configure.pl, take a look at the Wiki page relating to
   building from CVS
   (http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs).
   It is not a replacement for this document, but it shows how some members
   of the Juggler team configure VR Juggler. It also has information on more
   advanced uses of configure.pl that are beyond the scope of this document.

      Using locally installed software

   As noted in the section called "Getting the Source Code", VR Juggler
   depends on several external software packages. The cvs-gather tool
   collects the source code for those packages into the directory
   juggler/external, but some users may already have one or more of these
   installed locally. For those users, they have the option of referring to
   the local installation(s) and limiting the work done by cvs-gather (see
   the section called "Advanced use of cvs-gather" for more details).

   As an example, consider the case where the Boost C++ library is installed
   in /usr/local with the headers in /usr/local/include. To use this instead
   of the version downloaded into juggler/external, run configure.pl as
   follows:

 ../configure.pl --with-boostroot=/usr/local

   This option could of course be mixed in with those shown in the previous
   section. In this situation, all paths for the Boost headers will reference
   /usr/local/include; everything in juggler/external/boost will be ignored.

   There are similar options for GMTL and CppDOM. Other external dependencies
   not downloaded with cvs-gather, such as NSPR and JDOM, require the use of
   such command-line arguments. Refer to the output from running configure.pl
   --all-help for more detailed information.

    Compiling VR Juggler

   Once the configuration process is complete, the code can be compiled.
   Remember that we require the use of GNU make 3.78 or newer.

   1. Compile the source tree using GNU make.

 gmake build

   2. Once this completes, you will have a full build of VR Juggler. For
       those who are not interested in developing VR Juggler or its component
       modules, it is recommended that you install the software and use the
       installed version for application development. Do this as follows:

 gmake install

  Compiling individual tools in the Juggler Suite

   Sometimes you do not want to build everything in the Juggler Suite. Here
   are steps for configuring/building each package individually.

    VPR (individual)

   VPR can be configured a number of ways. Except when building on Win32, no
   external packages are required. For Win32, NSPR (www.mozilla.org) is
   required. To build VPR, do the following from the top-level juggler
   directory:

   1. mkdir build.vpr
 cd build.vpr

   2. ../configure.pl --module=VPR --prefix=$HOME/vpr-inst

   3. gmake debug install-debug

   4. setenv VPR_BASE_DIR $HOME/vpr-inst

   If you want to use NSPR, make sure a binary version is installed. In step
   2, add the arguments --enable-subsystem=NSPR and --with-nspr=<path to
   NSPR>. Once that is done, proceed with steps 3 and 4 as normal.

    Sonix (individual)

   Sonix requires a third-party software package called GMTL (ggt.sf.net).
   Sonix wraps other audio subsystems such as OpenAL (www.openal.org) or
   AudioWorks (multigen.com). One of these subsystems are required in order
   to hear sound. Once you have all the necessary source code and third-party
   package installations, to the following from the top-level juggler
   directory:

   1. mkdir build.sonix
 cd build.sonix

   2. Choose one of the following depending on which subsystem (or both) you
       want to enable in sonix...

 ../configure.pl --module=Sonix --prefix=$HOME/sonix-inst --enable-openal --with-oalroot=/usr/local
 ../configure.pl --module=Sonix --prefix=$HOME/sonix-inst --enable-audioworks

   3. gmake debug install-debug

   4. setenv SNX_BASE_DIR $HOME/sonix-inst

    JCCL (individual)

   JCCL requires VPR, CppDOM (http://www.sf.net/projects/xml-cppdom/), and
   JDOM B7 or newer (http://www.jdom.org/). To build JCCL, do the following
   from the top-level juggler directory:

   1. mkdir build.jccl
 cd build.jccl

   2. ../configure.pl --module=JCCL --prefix=$HOME/jccl-inst --with-jdom="<JDOMPATH>/build/jdom.jar:<JDOMPATH>/lib/xerces.jar"

   3. gmake debug install-debug

   4. setenv JCCL_BASE_DIR $HOME/jccl-inst

    Gadgeteer (individual)

   Gadgeteer depends on JCCL and on VPR. It also needs the third-party math
   library GMTL (http://ggt.sf.net/). Assuming you have all the source code,
   do the following from the top-level juggler directory:

   1. mkdir build.gadgeteer
 cd build.gadgeteer

   2. ../configure.pl --module=Gadgeteer --prefix=$HOME/gadgeteer-inst --with-jdom="<JDOMPATH>/build/jdom.jar:<JDOMPATH>/lib/xerces.jar"

   3. gmake debug install-debug

   4. setenv GADGET_BASE_DIR $HOME/gadgeteer-inst

    Tweek (individual)

   Tweek depends on VPR. It needs JDK 1.3.1, JDOM B7 or newer, and the
   third-party CORBA implementations omniORB 3.0.4 or newer (C++) and OpenORB
   1.2.0 or newer (Java). These packages can be downloaded from the following
   websites:

     o JDOM: http://www.jdom.org/

     o omniORB: http://www.omniorb.org/ or http://omniorb.sourceforge.net/

     o OpenORB: http://openorb.exolab.org/ or http://openorb.sourceforge.net/

   For the following steps, assume that you have omniORB installed in
   <OMNIORBPATH>, OpenORB is installed in <OPENORBPATH>, and JDOM is
   installed in <JDOMPATH>.

   IRIX users must configure Tweek (and its VPR dependency) to use the POSIX
   subsystem or the NSPR subsystem. omniORB will not work with SPROC threads.
   To configure VPR to use either POSIX threads or NSPR threads, pass either
   --enable-subsystem=POSIX or --enable-subsystem=NSPR to configure.pl
   respectively.

   Assuming you have the external packages installed, do the following from
   the top-level juggler directory:

   1. mkdir build.tweek
 cd build.tweek

   2. ../configure.pl --module=Tweek --prefix=$HOME/tweek-inst --with-jdom=<JDOMPATH>/jdom.jar:<JDOMPATH>/xerces.jar --with-cxx-orb=omniORB3 --with-cxx-orb-root=<OMNIORBPATH> --with-java-orb=OpenORB --with-java-orb-jar=<OPENORBPATH>/lib/openorb-1.2.0.jar

   3. gmake debug install-debug

   4. setenv TWEEK_BASE_DIR $HOME/tweek-inst

   If JDK 1.4.0 is used, you do not need OpenORB (or any other third-party
   CORBA implementation for Java). In that case, pass --with-java-orb=JDK to
   configure.pl.

   Depending on your omniORB installation, you may have to pass extra
   arguments to configure.pl so that the configuration process can find the
   omniidl binary and the omniORB libraries. For example, on RedHat Linux
   7.2, the following arguments must be specified in addition to the above:

 --with-cxx-orb-bin=<OMNIORBPATH>/bin/i586_linux_2.0_glibc --with-cxx-orb-lib=<OMNIORBPATH>/lib/i586_linux_2.0_glibc