root/juggler/tags/2.0.4/INSTALL.txt

Building and Installing the Juggler Project (Version 2.0)


The Juggler Team

 $Date$

----------------------------------------------------------------------------
 Table of Contents



  Introduction


        Important Notes for IRIX Users

        Important Note for Windows Users


  Getting the Source Code and the Dependencies


        How to Get the Juggler Suite from Subversion

        Downloading Third-Party Dependencies


  Compiling


        Important Note Regarding Compiling

        Compiling the Juggler Suite of Tools

        Tips for Compiling Individual Tools in the Juggler Suite



Introduction

 You have downloaded the source code for Version 2.0 of the Juggler Project.
 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
 Subversion 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 source (http://www.vrjuggler.org/
 twiki_public/bin/view/Juggler/BuildingFromSvn). It is a supplement to this
 document containing tips and reminders for those users building the SVN
 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 and newer 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 Windows Users

 VR Juggler 1.1 and newer use a lot of C++ features not supported by Visual
 Studio 6.0. Microsoft acknowledges the issues concerning noncompliance to
 the C++ Standard with Visual Studio 6.0, and it appears that they have no
 plans to fix these problems. Therefore, we require the use of Visual Studio
 7.x (.NET 2002 or 2003) or newer to compile the source code.


Getting the Source Code and the Dependencies

 In this section, we explain how to get the Juggler Project source code and
 the dependencies required to build Juggler. There are two ways to get the
 source code: from a pre-packaged source release archive or from the
 Subversion repository on RealityForge. If you got the code from a pre-
 packaged source archive, that code is a complete "snapshot" of the
 Subversion repository at the time of release. It contains all dependencies
 that would otherwise have been acquired using Subversion. It does not
 contain binary dependencies that must be downloaded separately (such as
 NSPR, the Java Developer Kit, a C++ compiler, etc.).

 The current list of required software packages is as follows:


*  CppDOM (http://www.sf.net/projects/xml-cppdom/): A lightweight, easy-to-
   use XML parser written in C++. CppDOM must be compiled and installed for
   use with VR Juggler.

*  Boost (http://www.boost.org/): A C++ library providing many powerful
   utility classes and libraries. Boost must be compiled and installed for
   use with VR Juggler.

*  GMTL (http://ggt.sf.net/): A generic math library that makes use of C++
   templates and STL paradigms. GMTL must be installed for use with VR
   Juggler.


 The following lists semi-optional packages:


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

*  Java Developer Kit (http://java.sun.com/): The J2SE SDK (or JDK) is used
   to compile all the Java code used in the Juggler Project. Without it,
   none of the Java code can be built. We require version 1.4 or newer. The
   Java Standard Edition (J2SE) can be downloaded from http://java.sun.com/
   j2se/.

*  omniORB (http://omniorb.sourceforge.net/): A C++ implementation of CORBA
   2.3, required for the Tweek C++ API.


 The following are fully optional packages that are primarily of interest
 only to people doing development on the Juggler Suite itself:


*  JUnit (http://www.junit.org/): A unit testing framework for Java.

*  CppUnit (http://cppunit.sourceforge.net/): A unit testing framework for
   C++. The Juggler C++ test suties make use of extensions to CppUnit. An
   extended version of the CppUnit source that includes these extensions can
   be acquired from the Juggler Subversion repository in the module cppunit.
   Refer to the section called "How to Get the Juggler Suite from
   Subversion" for instructions about accessing the Juggler Subversion
   repository.


 The third-party dependencies must be downloaded from the sites listed above
 and installed manually. You may also have to compile one or more of the
 packages if binary distributions are not available. Which packages you
 download depends on what you already have installed. Note carefully which
 packages are needed based on the software you have installed and what
 versions of tools (such as the JDK) that you download.


How to Get the Juggler Suite from Subversion

 You can optionally get the Juggler Project as a source code tarball from
 the website (http://www.vrjuggler.org/) or you can execute the following
 command from a shell to get the code from our Subversion repository:


  svn co https://realityforge.vrsource.org/svn/vrjuggler/juggler/branches/
  2.0 juggler


Downloading Third-Party Dependencies

 In addition to source the dependencies acquired through Subversion, there
 are some third-party dependencies that must be installed separately.
 Remember that no Java code in VR Juggler can be used without the JDK and a
 working Java version of CORBA.


Boost

 The minimum required version of Boost, as of this writing, is 1.31.0. The
 Boost source can be downloaded from http://www.sf.net/projects/boost/. To
 compile and install Boost, refer to its installation documentation (http://
 www.boost.org/more/getting_started.html#Build_Install). Note that you need
 the command bjam (referred to as "boost-jam" on the Boost download page) to
 build Boost.


Important

 Mac OS X users should compile the Boost libraries using the "darwin"
 toolset.


CppDOM

 For XML processing, we use CppDOM 0.3.2 or newer. The source and binary
 distributions for some platforms can be downloaded from http://www.sf.net/
 projects/xml-cppdom/. If a binary version is not available for your
 operating system you must compile and install CppDOM yourself. Note that
 you need SCons (http://scons.sourceforge.net/) to build and install CppDOM.


GMTL

 For high-level mathematical operations, we use GMTL 0.3.2 or newer. The
 source distribution can be downloaded from http://www.sf.net/projects/ggt/.
 Note that you need SCons (http://scons.sourceforge.net/) to build and
 install GMTL.


Netscape Portable Runtime (NSPR)

 Our operating system abstraction, VPR, can make use of NSPR for operating
 system primitives. On some platforms (IRIX, FreeBSD, Linux, Mac OS X), the
 use of NSPR is strictly optional. On others (Win32, HP-UX, and Solaris), it
 is required. Based on your local system, you should decide whether you need
 NSPR. Binary versions of NSPR can be downloaded from ftp://ftp.mozilla.org/
 pub/mozilla.org/nspr/releases. At this time, we recommend the use of
 version 4.2 or newer.


Java Developer Kit (also called the J2SE SDK)

 We make use of the Java programming language in addition to C++. Java is
 used exclusively for GUIs such as Tweek and VRJConfig (which is a JavaBean
 that is loaded into Tweek). To compile the Java code, a JDK is necessary.
 We currently require version 1.4 or newer. The Java Standard Edition can be
 downloaded from http://java.sun.com/j2se/. More information can be found at
 http://java.sun.com/.


omniORB

 omniORB is a C++ implementation of CORBA 2.3. It is required in order to
 compile the Tweek C++ API. At this time, the Tweek C++ API is not required
 for VR Juggler, but this situation will change in the near future. At this
 time, we primarily use omniORB 4.0.x. omniORB can be downloaded from http:/
 /omniorb.sourceforge.net/.

 omniORB 3.0 has strange conventions for how installations are made. Within
 the bin and lib directories, there are platform-specific subdirectories
 that contain the actual binaries (except when installed on FreeBSD via the
 Ports Collection). Because of this, several extra options must be specified
 in order to tell the Tweek configure script where to find everything.
 Please refer to the section called "Tweek" for more details on this.


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 using Subversion, Autoconf,
 C++, and make or Visual Studio.


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.)

 To build VR Juggler on Windows, you must use the Visual Studio solution.
 After getting the dependencies needed to compile VR Juggler (see the next
 section), refer to the README.html file located in the vc7 subdirectory of
 this directory. Do not bother to the rest of this document.


Per-Module Dependencies

 Here, we provide per-module dependency information. Given that the
 dependencies for any single module are met, the modules may be reused
 effectively outside the scope of immersive VR application development.
 Below, we list the minimum required version for each dependency, and where
 appropriate, we note which dependencies are optional.


VPR

 VPR provides a cross-platform, object-oriented operating system
 abstraction. It is the foundation for all other Juggler modules.


*  CppDOM 0.3.2

*  Boost headers and Boost.Filesystem 1.31.0

*  NSPR (Windows, Solaris, and HP-UX only) 4.4



Tweek C++ API

 Tweek implements a distributed model/view/controller system on top of
 CORBA. The Tweek C++ API provides the C++ component of that system. Code
 written on top of the Tweek C++ API normally acts as the model piece of the
 distributed model/view/controller system.


*  VPR

*  omniORB 4.0



Tweek Java API

 Tweek implements a distributed model/view/controller system on top of
 CORBA. The Tweek Java API provides the Java component of that system. The
 main part of the Tweek Java API is the Tweek JavaBean Loader, a GUI
 application that loads Tweek Beans that normally function as the view and
 controller pieces of the distributed module/view/controller system.


*  J2SE SDK 1.4

*  JDOM (included with Juggler source)

*  Ant (included with Juggler source)

*  JacORB IDL-to-Java compiler (included with Juggler source)



Tweek Python API

 Tweek implements a distributed model/view/controller system on top of
 CORBA. The Tweek Python API provides the Python component of that system.
 The main part of the Tweek Java API is the unfinished TweekQt GUI, an
 application that loads Python modules that normally function as the view
 and controller pieces of the distributed module/view/controller system.


*  Python 2.3

*  omniORBpy 2.0



JCCL C++ API

 The JCCL C++ API provides an interface for loading XML-based
 configurations. It includes the run-time reconfiguration feature of
 Juggler.


*  VPR



JCCL Java API

 The JCCL Java API provides a programming interface for editing Juggler
 configuration files and config definition files as well as JavaBeans for
 editing these files using a graphical interface.


*  Tweek Java API

*  TableLayout package (included with Juggler source)



JCCL Remote Run-Time Reconfiguration Plug-in (C++)

 The C++ JCCL Remote Run-Time Reconfiguration Plug-in is an optional
 extension to the JCCL Config Manager for allowing remote manipulation of a
 Juggler configuration at run time based on Tweek.


*  Tweek C++ API



JCCL Remote Run-Time Reconfiguration Plug-in (Java)

 The Java JCCL Remote Run-Time Reconfiguration Plug-in is an optional
 extension that provides the features needed for a Java-based editor to
 communicate with the C++ Remote Run-Time Reconfiguration Plug-in to edit
 Juggler configurations live.


*  Tweek Java API



Sonix

 Sonix is an abstraction layer for positional sound software. Sonix itself
 cannot play audio, but it includes plug-ins based on popular interfaces for
 playing audio. Each plug-in depends on a specific audio software library.


*  VPR

*  GMTL 0.1.9



Sonix OpenAL Plug-in


*  Sonix

*  OpenAL

*  Free ALUT



Sonix Audiere Plug-in


*  Sonix

*  Audiere



Sonix AudioWorks Plug-in


*  Sonix

*  AudioWorks



Gadgeteer

 Gadgeteer handles all input devices that can be used by VR Juggler
 applications.


*  VPR

*  JCCL

*  GMTL 0.1.9

*  X Window System (non-Windows platforms)



Gadgeteer Device Driver Plug-ins

 The device driver plug-ins for Gadgeteer are independent components that
 are discovered and used at run time based on the application configuration.
 Drivers with dependencies are optional.


*  Gadgeteer

*  VRPN 06.06 for the VRPN driver plug-in

*  TrackD API 4 for the TrackD API driver plug-in

*  Microsoft Speech API for the MS Speech API driver plug-in



Gadgeteer Cluster Plug-ins

 The cluster plug-ins extend the functionality of the clustering
 infrastructure built into Gadgeteer.


*  Gadgeteer



VR Juggler

 The VR Juggler module is the unifying piece that pulls all the other
 Juggler modules together. It provides a virtual platform for VR application
 development. Real-time rendering is controlled by Draw Managers. The OpenGL
 Performer Draw Manager is optional.


*  Gadgeteer

*  Sonix

*  OpenGL

*  OpenGL Performer for the optional OpenGL Performer Draw Manager



VR Juggler Run-Time Performance Monitoring Plug-in (C++)

 The C++ VR Juggler Run-Time Performance Monitoring Plug-in provides an
 optional extension to VR Juggler for remote visualization of performance
 metrics that are captured while running a VR Juggler application.
 Communication is performed using the Tweek C++ API on top of CORBA.


*  Tweek C++ API

*  VR Juggler



VR Juggler Run-Time Performance Monitoring Plug-in (Java)

 The Java VR Juggler Run-Time Performance Monitoring Plug-in is an optional
 extension that provides the features needed for Java-based visualization of
 performance data collected while a VR Juggler application is running. This
 is another JavaBean handled by the Tweek JavaBean Loader, and it uses CORBA
 to communicate with the C++ VR Juggler Run-Time Performance Monitoring
 Plug-in.


*  JCCL Java API

*  JFreeChart (included with Juggler source)



VRJConfig

 VRJConfig is the graphical editor for Juggler configurations. It is a
 JavaBean loaded by the Tweek JavaBean Loader, and it makes use of the
 editor Beans provided by the JCCL Java API.


*  JCCL Java API

*  JGraph (included with Juggler source)



Configuring the Juggler Build

 We now explain the process by which the Juggler build is configured. The
 Juggler Suite makes use of the well-known, widely used GNU tools Autoconf
 and GNU Make. We provide a wrapper script written in Perl called
 configure.pl that gets the process started.

 The Juggler build is highly automated. The trickiest part is telling the
 build where to find the third-party dependencies. This part can be
 simplified, however, by installing the third-party dependencies in the
 default location where the search will be performed. In most cases, this is
 /usr/local, but in others it is /usr. The default search location is
 determined by whether the dependency is considered to be a fundamental part
 of the operating system installation (such as OpenGL) or if it is an
 "add-on" package (such as Boost, GMTL, CppDOM, or omniORB).

 The distinction between /usr/local and /usr is complicated by the fact that
 most Linux distributions have everything installed in /usr. While Linux may
 be popular, it should not (yet) be considered a model example of how to do
 things. In traditional UN*X distributions (BSD and System V), /usr is only
 used for the fundamental operating system pieces; /usr/local is used for
 extra bits. The Juggler build is based on these assumptions. Furthermore,
 most open source software packages (e.g., Boost, omniORB, Perl, Python)
 default to installing themselves in /usr/local, which suggests that the
 authors of those tools generally expect their software to be in /usr/local.


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


Important

 In order for this to work, the configure script for each of the Juggler
 modules must be generated. This can be done manually by running autogen.sh
 in the top-level juggler directory. It use is simple:


  ./autogen.sh

 This autogen.sh script must be run from the directory where it exists. Do
 not try to run it from a build directory or any other place in the Juggler
 source tree. The same holds for the individual autogen.sh scripts in the
 various modules, should you need to run one individually.

 configure.pl can run in a unique "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.


       ../configure.pl --prefix=$HOME/vrjuggler-2.0 --with-java-orb=JDK


     Important

      You will probably have to specify the paths to your local CppDOM,
      GMTL, and Boost installations using the options --with-cppdom, --with-
      gmtl, and --with-boost unless they are installed in the default
      location (/usr/local). By default, Boost 1.31 installs its header
      files in a subdirectory of include called boost-1_31. That is, if
      Boost is installed in /home/user1/pkgs/boost, the header files will be
      in /home/user1/pkgs/boost/include/boost-1_31. In this case, you must
      also specify the option --with-boost-includes=/home/user1/pkgs/boost/
      include/boost-1_31 when running configure.pl.


 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 Aaudiere, OpenAL, or AudioWorks to add sound to
 VR Juggler applications. If none 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" for more information about how to
 configure Sonix to use Audiere, OpenAL, or AudioWorks.

 For example uses of configure.pl, take a look at the Wiki page relating to
 building from source (http://www.vrjuggler.org/twiki_public/bin/view/
 Juggler/BuildingFromSvn). 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 and the
 Dependencies", VR Juggler depends on several external software packages. As
 an example, consider the case where the GMTL library is installed in
 /home/user1/pkgs/GMTL with the headers in /home/user1/pkgs/GMTL/include. To
 use this installation, run configure.pl as follows:


  ../configure.pl --with-gmtl=/home/user1/pkgs/GMTL

 The --with-gmtl option could of course be mixed in with those shown in the
 previous section.


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



Tips for Compiling Individual Tools in the Juggler Suite

 In this section, we provide tips for ensuring that individual tools in the
 Juggler Suite are compiled correctly. For the most part, this duplicates
 information that can be found on the Wiki page relating to building from
 source (http://www.vrjuggler.org/twiki_public/bin/view/Juggler/
 BuildingFromSvn).


Sonix

 Sonix wraps other audio subsystems such as OpenAL (www.openal.org), Audiere
 (audiere.sf.net), or AudioWorks (multigen.com). At least one of these
 packages must be installed for use by Sonix in order to hear sounds in VR
 Juggler applications. Once you have all the necessary source code and
 third-party package installations, add one or more of the following options
 to your configure.pl command line to enable the appropriate audio
 subsystem:


*  --enable-openal --with-openal=<OPENAL_PATH>: Enable the use of OpenAL and
   tell the build where OpenAL is installed. The default search path is /
   usr/local.

*  --enable-audiere --with-audiere=<AUDIERE_PATH>: Enable the use of Audiere
   and tell the build where Audiere is installed. The default search path is
   /usr/local.

*  --enable-audioworks --with-audioworks=<AUDIOWORKS_PATH>: Enable the use
   of AudioWorks and tell the build where AudioWorks is installed. The
   default search path is /usr.



Note

 AudioWorks and OpenAL cannot be compiled together. They depend on mutually
 exclusive VPR threading subsystems. Warnings will be printed by the Sonix
 configure script indicating this fact. OpenAL and Audiere can be compiled
 together, however.


Tweek

 Tweek needs JDK 1.4 or newer and a C++ CORBA implementation. Currently, we
 primarily use omniORB 4.0, but omniORB 3.0 can be used. Visit the omniORB
 website to download omniORB.


Note

 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 respectively to
 configure.pl.

 For the following steps, assume that you have omniORB installed in
 <OMNIORB_PATH>. Assuming you have the external packages installed, do the
 following from the top-level juggler directory:


  mkdir build
  cd build
  ../configure.pl --with-cxx-orb=omniORB4 --with-cxx-orb-root=<OMNIORB_PATH>
  --with-java-orb=JDK --module=Tweek
  gmake build install

 If you are using omniORB 3.x, pass --with-cxx-orb=omniORB3 instead.

 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 Red Hat Linux 7.2
 with omniORB 3.0.x, the following arguments must be specified in addition
 to the above:


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