Changeset 18807

Show
Ignore:
Timestamp:
05/08/06 18:02:24 (2 years ago)
Author:
patrick
Message:

Moved the Windows build instructions out of the vc7 subtree and into the
top-level tree so that it is located more centrally—at least with
respect to the vc7 and vc8 subtrees.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • juggler/trunk/INSTALL.html

    r17626 r18807  
    22      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 
    33   <title>Building and Installing the Juggler Project (Version 
    4     2.1/2.2)</title><link rel="stylesheet" href="base_style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="d0e1"></a>Building and Installing the Juggler Project (Version 
    5     2.1/2.2)</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="othername">The Juggler Team</span></h3></div></div></div><div><p class="pubdate">$Date$</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#d0e15">Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e32">Important Notes for IRIX Users</a></span></dt><dt><span class="section"><a href="#d0e116">Important Note for Win32 Users</a></span></dt></dl></dd><dt><span class="section"><a href="#source.code.section">Getting the Source Code and the Dependencies</a></span></dt><dd><dl><dt><span class="section"><a href="#section.cvs.access">How to Get the Juggler Suite from CVS</a></span></dt><dt><span class="section"><a href="#d0e218">Downloading Third-Party Dependencies</a></span></dt></dl></dd><dt><span class="section"><a href="#compile.section">Compiling</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e304">Important Note Regarding Compiling</a></span></dt><dt><span class="section"><a href="#d0e315">Compiling the Juggler Suite of Tools</a></span></dt><dt><span class="section"><a href="#compile.individual.section">Tips for Compiling Individual Tools in the Juggler Suite</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e15"></a>Introduction</h2></div></div></div><p>You have downloaded the source code for Version 2.1 of the Juggler 
    6     Project. This is the code that will become VR Juggler 2.2, and it is the 
    7     code that is used to create the VR juggler 2.2 pre-releases. Please be 
    8     aware that this code represents a work in progress, and if you acquired it 
    9     directly from CVS rather than using a pre-packaged source code snapshot, 
    10     the code may have bugs affecting compilation and execution.</p><p>This document explains how to build the modules of the Juggler 
    11     Project from the source code. We begin by explaining some issues related 
    12     to specific operating systems. We then explain how to get the source code 
    13     from our CVS repository. (Those users who downloaded a pre-packaged source 
    14     release can skip ahead to <a href="#using.configure.pl" title="Using configure.pl">the section called &#8220;Using <span><strong class="command">configure.pl</strong></span>&#8221;</a>). We 
    15     conclude with instructions on how to build VR Juggler and its individual 
    16     components.</p><p>Before reading further, we recommend that readers take a look at the 
    17     Wiki page relating to building from CVS (<a href="http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs" target="_top">http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs</a>). 
    18     It is a <span class="emphasis"><em>supplement</em></span> to this document containing tips 
    19     and reminders for those users building the CVS version of VR Juggler. It 
    20     is not a replacement for this document, nor can it stand on its own as 
    21     build instructions. You are reading the definitive build instructions; the 
    22     Wiki page merely provides informal, extra information.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e32"></a>Important Notes for IRIX Users</h3></div></div></div><p>Despite our best efforts, there are some issues related to 
    23       compiling the Juggler Project on IRIX. We introduce them in this section 
    24       and explain how to work around them.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e37"></a>Perl Version</h4></div></div></div><p>There are many Perl scripts used as part of getting, 
    25         configuring, and building the Juggler Suite of tools. In particular, 
    26         two scripts required for compiling need Perl 5.005 or newer. The 
    27         version of Perl that ships with IRIX 6.5 is very old (circa 1997) and 
    28         does not work with many Perl scripts we have written. SGI provides a 
    29         much newer version of Perl (5.6.1) with their freeware tools (<a href="http://freeware.sgi.com/" target="_top">http://freeware.sgi.com/</a>). It 
    30         will be necessary to install that version for our scripts to work. 
    31         This version is typically installed as 
    32         <code class="filename">/usr/freeware/bin/perl</code>.</p><p>Once you have a modern Perl installed, you can run various Perl 
    33         scripts as follows:</p><pre class="screen">/usr/freeware/bin/perl &lt;script-name&gt;</pre><p>The above will be required any time a Perl script fails with an 
    34         error similar to the following:</p><pre class="screen">Perl 5.005 required--this is only version 5.00404, stopped at ./configure.pl line 35. 
     4      2.1/2.2)</title><link rel="stylesheet" href="base_style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.69.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="d0e1"></a>Building and Installing the Juggler Project (Version 
     5      2.1/2.2)</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="othername">The Juggler Team</span></h3></div></div></div><div><p class="pubdate">$Date$</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#d0e15">Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e32">Important Notes for IRIX Users</a></span></dt><dt><span class="section"><a href="#d0e116">Important Note for Win32 Users</a></span></dt></dl></dd><dt><span class="section"><a href="#source.code.section">Getting the Source Code and the Dependencies</a></span></dt><dd><dl><dt><span class="section"><a href="#section.cvs.access">How to Get the Juggler Suite from CVS</a></span></dt><dt><span class="section"><a href="#d0e218">Downloading Third-Party Dependencies</a></span></dt></dl></dd><dt><span class="section"><a href="#compile.section">Compiling</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e304">Important Note Regarding Compiling</a></span></dt><dt><span class="section"><a href="#d0e315">Compiling the Juggler Suite of Tools</a></span></dt><dt><span class="section"><a href="#compile.individual.section">Tips for Compiling Individual Tools in the Juggler 
     6         Suite</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e15"></a>Introduction</h2></div></div></div><p>You have downloaded the source code for Version 2.1 of the Juggler 
     7      Project. This is the code that will become VR Juggler 2.2, and it is the 
     8      code that is used to create the VR juggler 2.2 pre-releases. Please be 
     9      aware that this code represents a work in progress, and if you acquired 
     10      it directly from CVS rather than using a pre-packaged source code 
     11      snapshot, the code may have bugs affecting compilation and 
     12      execution.</p><p>This document explains how to build the modules of the Juggler 
     13      Project from the source code. We begin by explaining some issues related 
     14      to specific operating systems. We then explain how to get the source 
     15      code from our CVS repository. (Those users who downloaded a pre-packaged 
     16      source release can skip ahead to <a href="#using.configure.pl" title="Using configure.pl">the section called &#8220;Using <span><strong class="command">configure.pl</strong></span>&#8221;</a>). 
     17      We conclude with instructions on how to build VR Juggler and its 
     18      individual components.</p><p>Before reading further, we recommend that readers take a look at 
     19      the Wiki page relating to building from CVS (<a href="http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs" target="_top">http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs</a>). 
     20      It is a <span class="emphasis"><em>supplement</em></span> to this document containing tips 
     21      and reminders for those users building the CVS version of VR Juggler. It 
     22      is not a replacement for this document, nor can it stand on its own as 
     23      build instructions. You are reading the definitive build instructions; 
     24      the Wiki page merely provides informal, extra information.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e32"></a>Important Notes for IRIX Users</h3></div></div></div><p>Despite our best efforts, there are some issues related to 
     25         compiling the Juggler Project on IRIX. We introduce them in this 
     26         section and explain how to work around them.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e37"></a>Perl Version</h4></div></div></div><p>There are many Perl scripts used as part of getting, 
     27            configuring, and building the Juggler Suite of tools. In 
     28            particular, two scripts required for compiling need Perl 5.005 or 
     29            newer. The version of Perl that ships with IRIX 6.5 is very old 
     30            (circa 1997) and does not work with many Perl scripts we have 
     31            written. SGI provides a much newer version of Perl (5.6.1) with 
     32            their freeware tools (<a href="http://freeware.sgi.com/" target="_top">http://freeware.sgi.com/</a>). 
     33            It will be necessary to install that version for our scripts to 
     34            work. This version is typically installed as 
     35            <code class="filename">/usr/freeware/bin/perl</code>.</p><p>Once you have a modern Perl installed, you can run various 
     36            Perl scripts as follows:</p><pre class="screen">/usr/freeware/bin/perl &lt;script-name&gt;</pre><p>The above will be required any time a Perl script fails with 
     37            an error similar to the following:</p><pre class="screen">Perl 5.005 required--this is only version 5.00404, stopped at ./configure.pl line 35. 
    3538BEGIN failed--compilation aborted at ./configure.pl line 35.</pre><p>Furthermore, it is highly recommended that the 
    36         <code class="option">--with-perl</code> argument be passed to 
    37         <span><strong class="command">configure.pl</strong></span>. This argument gives all the 
    38         Autoconf-based configure scripts a hint about where the preferred 
    39         version of Perl lives. If using 
    40         <code class="filename">/usr/freeware/bin/perl</code> to run 
    41         <span><strong class="command">configure.pl</strong></span>, we recommend that the 
    42         <span><strong class="command">configure.pl</strong></span> command line appear similar to the 
    43         following:</p><pre class="screen">/usr/freeware/bin/perl configure.pl --with-perl=/usr/freeware/bin</pre><p>Note that the value given to <code class="option">--with-perl</code> is the 
    44         <span class="emphasis"><em>directory</em></span> where the <span><strong class="command">perl</strong></span> 
    45         executable can be found. The configure scripts will add this directory 
    46         to the front of the search path when trying to find a suitable 
    47         <span><strong class="command">perl</strong></span> executable. Once it is found, all the Perl 
    48         scripts used for configuration, compilation, and installation will use 
    49         that executable.</p><p>To simplify command execution somewhat, it can help to have 
    50         <code class="filename">/usr/freeware/bin</code> (or whatever path is 
    51         appropriate) in your path before <code class="filename">/bin</code> or 
    52         <code class="filename">/usr/bin</code> or any of the other myriad directories 
    53         where Perl might exist on IRIX. In such a situation, none of the above 
    54         extra steps should be necessary. The correct version of Perl will be 
    55         found simply by virtue of it being early in your path.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e100"></a>MIPSpro Compiler Version</h4></div></div></div><p>Reports have been made on the VR Juggler mailing list regarding 
    56         compile failures (including segmentation faults within the compiler) 
    57         occur when using the MIPSpro Compilers Version 7.3.1.1m. We have found 
    58         upgrading to Version 7.3.1.3m (or newer) fixes the problems.</p><p>A new feature of VR Juggler 1.1 and newer is support for GCC on 
    59         IRIX. Users who do not have MIPSpro or cannot upgrade can compile and 
    60         run VR Juggler (without OpenGL Performer support) using the version of 
    61         GCC distributed by SGI. It can be downloaded from <a href="http://freeware.sgi.com/index-by-alpha.html" target="_top">http://freeware.sgi.com/index-by-alpha.html</a> 
    62         for free. When configuring the source with 
    63         <span><strong class="command">configure.pl</strong></span> (described later), use the option 
    64         <code class="option">--with-gcc</code>.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e116"></a>Important Note for Win32 Users</h3></div></div></div><p>VR Juggler 1.1 and newer use a lot of C++ features not supported 
    65       by Visual Studio 6.0. Microsoft <a href="http://support.microsoft.com/default.aspx?scid=http://support.microsoft.com:80/support/kb/articles/q243/4/51.asp&amp;NoWebContent=1" target="_top">acknowledges</a> 
    66       the issues concerning noncompliance to the C++ Standard with Visual 
    67       Studio 6.0, and it appears that they have no plans to fix these 
    68       problems. Therefore, we require the use of Visual Studio 7.x (.NET 2002 
    69       or 2003) to compile the source code.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="source.code.section"></a>Getting the Source Code and the Dependencies</h2></div></div></div><p>In this section, we explain how to get the Juggler Project source 
    70     code and the dependencies required to build Juggler. There are two ways to 
    71     get the source code: from a pre-packaged source release archive or from 
    72     the CVS repository on SourceForge. If you got the code from a pre-packaged 
    73     source archive, that code is a complete &#8220;<span class="quote">snapshot</span>&#8221; of the CVS 
    74     repository at the time of release. It contains all dependencies that would 
    75     otherwise have been acquired using CVS. It <span class="emphasis"><em>does not</em></span> 
    76     contain binary dependencies that must be downloaded separately (such as 
    77     NSPR, the Java Developer Kit, a C++ compiler, etc.).</p><p>The current list of <span class="emphasis"><em>required</em></span> software packages 
    78     is as follows:</p><div class="itemizedlist"><ul type="disc"><li><p>CppDOM (<a href="http://www.sourceforge.net/projects/xml-cppdom/" target="_top">http://www.sf.net/projects/xml-cppdom/</a>): 
    79         A lightweight, easy-to-use XML parser written in C++. CppDOM must be 
    80         compiled and installed for use with VR Juggler.</p></li><li><p>Boost (<a href="http://www.boost.org/" target="_top">http://www.boost.org/</a>): A C++ 
    81         library providing many powerful utility classes and libraries. Boost 
    82         must be compiled and installed for use with VR Juggler.</p></li><li><p>GMTL (<a href="http://ggt.sourceforge.net/" target="_top">http://ggt.sf.net/</a>): A 
    83         generic math library that makes use of C++ templates and STL 
    84         paradigms. GMTL must be installed for use with VR Juggler.</p></li></ul></div><p>The following lists <span class="emphasis"><em>semi-optional</em></span> 
    85     packages:</p><div class="itemizedlist"><ul type="disc"><li><p>NSPR (<a href="http://www.mozilla.org/projects/nspr/" target="_top">http://www.mozilla.org/projects/nspr/</a>): 
    86         The Netscape Portable Runtime, which can be used by VPR for threading 
    87         and sockets (required on Win32 and Solaris).</p></li><li><p>Java Developer Kit (<a href="http://java.sun.com/" target="_top">http://java.sun.com/</a>): The J2SE SDK 
    88         (or JDK) is used to compile all the Java code used in the Juggler 
    89         Project. Without it, none of the Java code can be built. We require 
    90         version 1.4 or newer. The Java Standard Edition (J2SE) can be 
    91         downloaded from <a href="http://java.sun.com/j2se/" target="_top">http://java.sun.com/j2se/</a>.</p></li><li><p>omniORB (<a href="http://www.jdom.org/" target="_top">http://omniorb.sourceforge.net/</a>): A 
    92         C++ implementation of CORBA 2.3, required for the Tweek C++ 
    93         API.</p></li></ul></div><p>The following are fully optional packages that are primarily of 
    94     interest only to people doing development on the Juggler Suite 
    95     itself:</p><div class="itemizedlist"><ul type="disc"><li><p>JUnit (<a href="http://www.junit.org/" target="_top">http://www.junit.org/</a>): A unit 
    96         testing framework for Java.</p></li><li><p>CppUnit (<a href="http://cppunit.sourceforge.net/" target="_top">http://cppunit.sourceforge.net/</a>): 
    97         A unit testing framework for C++. The Juggler C++ test suties make use 
    98         of extensions to CppUnit. An extended version of the CppUnit source 
    99         that includes these extensions can be acquired from the Juggler CVS 
    100         repository in the module <code class="literal">cppunit</code>. Refer to <a href="#section.cvs.access" title="How to Get the Juggler Suite from CVS">the section called &#8220;How to Get the Juggler Suite from CVS&#8221;</a> for instructions about accessing the 
    101         Juggler CVS repository.</p></li></ul></div><p>The third-party dependencies must be downloaded from the sites 
    102     listed above and installed manually. You may also have to compile one or 
    103     more of the packages if binary distributions are not available. Which 
    104     packages you download depends on what you already have installed. Note 
    105     carefully which packages are needed based on the software you have 
    106     installed and what versions of tools (such as the JDK) that you 
    107     download.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="section.cvs.access"></a>How to Get the Juggler Suite from CVS</h3></div></div></div><p>You can optionally get the Juggler Project as a source code 
    108       tarball from the website (<a href="http://www.vrjuggler.org/" target="_top">http://www.vrjuggler.org/</a>) or 
    109       you can execute the following commands from a shell to get the code from 
    110       our CVS repository:</p><pre class="screen">cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vrjuggler login 
    111 cvs -z3 -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vrjuggler co juggler</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e218"></a>Downloading Third-Party Dependencies</h3></div></div></div><p>In addition to source the dependencies acquired through CVS, there 
    112       are some third-party dependencies that must be installed separately. 
    113       Remember that no Java code in VR Juggler can be used without the JDK and 
    114       a working Java version of CORBA.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e223"></a>Boost</h4></div></div></div><p>The minimum required version of Boost, as of this writing, is 
    115         1.31.0. The Boost source can be downloaded from <a href="http://www.sf.net/projects/boost/" target="_top">http://www.sf.net/projects/boost/</a>. 
    116         To compile and install Boost, refer to its installation documentation 
    117         (<a href="http://www.boost.org/more/getting_started.html#Build_Install" target="_top">http://www.boost.org/more/getting_started.html#Build_Install</a>). 
    118         Note that you need the command <span><strong class="command">bjam</strong></span> (referred to as 
    119         &#8220;<span class="quote">boost-jam</span>&#8221; on the Boost download page) to build 
    120         Boost.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e240"></a>CppDOM</h4></div></div></div><p>For XML processing, we use CppDOM 0.3.2 or newer. The source and 
    121         binary distributions for some platforms can be downloaded from <a href="http://www.sf.net/projects/xml-cppdom/" target="_top">http://www.sf.net/projects/xml-cppdom/</a>. 
    122         If a binary version is not available for your operating system you 
    123         must compile and install CppDOM yourself. Note that you need SCons 
    124         (<a href="http://scons.sourceforge.net/" target="_top">http://scons.sourceforge.net/</a>) 
    125         to build and install CppDOM.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e251"></a>GMTL</h4></div></div></div><p>For high-level mathematical operations, we use GMTL 0.3.2 or 
    126         newer. The source distribution can be downloaded from <a href="http://www.sf.net/projects/ggt/" target="_top">http://www.sf.net/projects/ggt/</a>. 
    127         Note that you need SCons (<a href="http://scons.sourceforge.net/" target="_top">http://scons.sourceforge.net/</a>) 
    128         to build and install GMTL.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e262"></a>Netscape Portable Runtime (NSPR)</h4></div></div></div><p>Our operating system abstraction, VPR, can make use of NSPR for 
    129         operating system primitives. On some platforms (IRIX, FreeBSD, Linux, 
    130         Mac OS X), the use of NSPR is strictly optional. On others (Win32, 
    131         HP-UX, and Solaris), it is required. Based on your local system, you 
    132         should decide whether you need NSPR. Binary versions of NSPR can be 
    133         downloaded from <a href="ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases" target="_top">ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases</a>. 
    134         At this time, we recommend the use of version 4.2 or newer.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e270"></a>Java Developer Kit (also called the J2SE SDK)</h4></div></div></div><p>We make use of the Java programming language in addition to C++. 
    135         Java is used exclusively for GUIs such as Tweek and VRJConfig (which 
    136         is a JavaBean that is loaded into Tweek). To compile the Java code, a 
    137         JDK is necessary. We currently require version 1.4 or newer. The Java 
    138         Standard Edition can be downloaded from <a href="http://java.sun.com/j2se/" target="_top">http://java.sun.com/j2se/</a>. 
    139         More information can be found at <a href="http://java.sun.com/" target="_top">http://java.sun.com/</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e281"></a>omniORB</h4></div></div></div><p>omniORB is a C++ implementation of CORBA 2.3. It is required in 
    140         order to compile the Tweek C++ API. At this time, the Tweek C++ API is 
    141         not required for VR Juggler, but this situation will change in the 
    142         near future. At this time, we primarily use omniORB 4.0.x. omniORB can 
    143         be downloaded from <a href="http://omniorb.sourceforge.net/" target="_top">http://omniorb.sourceforge.net/</a>.</p><p>omniORB 3.0 has strange conventions for how installations are 
    144         made. Within the <code class="filename">bin</code> and <code class="filename">lib</code> 
    145         directories, there are platform-specific subdirectories that contain 
    146         the actual binaries (except when installed on FreeBSD via the Ports 
    147         Collection). Because of this, several extra options must be specified 
    148         in order to tell the Tweek configure script where to find everything. 
    149         Please refer to <a href="#tweek.build.section" title="Tweek">the section called &#8220;Tweek&#8221;</a> for more 
    150         details on this.</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="compile.section"></a>Compiling</h2></div></div></div><p>In this section, we describe how to compile the Juggler Project. We 
    151     focus on VR Juggler as a whole, but information about some of the 
    152     individual components is provided later.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e304"></a>Important Note Regarding Compiling</h3></div></div></div><p>You have downloaded <span class="emphasis"><em>developmental</em></span> code. It 
    153       may not be stable, and it may not even compile. Compiling VR Juggler 
    154       itself can be a little complicated for anyone who does not have some 
    155       background in using CVS, Autoconf, C++, and <span><strong class="command">make</strong></span> or 
    156       Visual Studio.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e315"></a>Compiling the Juggler Suite of Tools</h3></div></div></div><p>This section explains how to get, configure, and compile all of 
    157       the tools that make up VR Juggler. Each tool compiles to its own library 
    158       and can be installed individually. (Refer to the 
    159       <code class="filename">README</code> file in this directory for more information 
    160       about the specific modules.)</p><p>To build VR Juggler on Windows, you must use the Visual Studio 
    161       solution. After getting the dependencies needed to compile VR Juggler 
    162       (see the next section), refer to the <a href="vc7/README.html" target="_top">README.html</a> file located in the 
    163       <code class="filename">vc7</code> subdirectory of this directory. Do not bother 
    164       to the rest of this document.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="config.vrjuggler.section"></a>Configuring the Juggler Build</h4></div></div></div><p>We now explain the process by which the Juggler build is 
    165         configured. The Juggler Suite makes use of the well-known, widely used 
    166         GNU tools Autoconf and GNU Make. We provide a wrapper script written 
    167         in Perl called <span><strong class="command">configure.pl</strong></span> that gets the process 
    168         started.</p><p>The Juggler build is highly automated. The trickiest part is 
    169         telling the build where to find the third-party dependencies. This 
    170         part can be simplified, however, by installing the third-party 
    171         dependencies in the default location where the search will be 
    172         performed. In most cases, this is <code class="filename">/usr/local</code>, but 
    173         in others it is <code class="filename">/usr</code>. The default search location 
    174         is determined by whether the dependency is considered to be a 
    175         fundamental part of the operating system installation (such as OpenGL) 
    176         or if it is an &#8220;<span class="quote">add-on</span>&#8221; package (such as Boost, GMTL, 
    177         CppDOM, or omniORB).</p><div class="sidebar"><p>The distinction between <code class="filename">/usr/local</code> and 
    178           <code class="filename">/usr</code> is complicated by the fact that most Linux 
    179           distributions have <span class="emphasis"><em>everything</em></span> installed in 
    180           <code class="filename">/usr</code>. While Linux may be popular, it should not 
    181           (yet) be considered a model example of how to do things. In 
    182           traditional UN*X distributions (BSD and System V), 
    183           <code class="filename">/usr</code> is only used for the fundamental operating 
    184           system pieces; <code class="filename">/usr/local</code> is used for extra 
    185           bits. The Juggler build is based on these assumptions. Furthermore, 
    186           most open source software packages (e.g., Boost, omniORB, Perl, 
    187           Python) default to installing themselves in 
    188           <code class="filename">/usr/local</code>, which suggests that the authors of 
    189           those tools generally expect their software to be in 
    190           <code class="filename">/usr/local</code>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="using.configure.pl"></a>Using <span><strong class="command">configure.pl</strong></span></h5></div></div></div><p>In the base <code class="filename">juggler</code> source directory, we 
    191           have a &#8220;<span class="quote">global</span>&#8221; configure script written in Perl called 
    192           <span><strong class="command">configure.pl</strong></span>. To get the command-line options for 
    193           this script, use one of the following (the second being much more 
    194           detailed):</p><pre class="screen">./configure.pl --help 
    195 ./configure.pl --manual</pre><p>To configure your system, you will need to see what options 
    196           all the Autoconf-based configure scripts in VR Juggler need. To get 
    197           this text, enter:</p><pre class="screen">./configure.pl --all-help</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>In order for this to work, the configure script for each 
    198               of the Juggler modules must be generated. This can be done 
    199               manually by running <span><strong class="command">autogen.sh</strong></span> in the 
    200               top-level <code class="filename">juggler</code> directory. It use is 
    201               simple:</p><pre class="screen">./autogen.sh</pre><p>This <span><strong class="command">autogen.sh</strong></span> script must be run from 
    202               the directory where it exists. Do not try to run it from a build 
    203               directory or any other place in the Juggler source tree. The 
    204               same holds for the individual <span><strong class="command">autogen.sh</strong></span> 
    205               scripts in the various modules, should you need to run one 
    206               individually.</p></div><p><span><strong class="command">configure.pl</strong></span> can run in a unique 
    207           &#8220;<span class="quote">build</span>&#8221; directory or in the directory where it resides. 
    208           Here is how we (the Juggler Team) have been using it:</p><div class="orderedlist"><ol type="1"><li><p>Make a directory for compiling. There are many good 
    209               reasons to do this away from the main source tree (though they 
    210               will not be listed here).</p><pre class="screen">mkdir build.linux.posix</pre><p>This example using an ad hoc naming convention based on 
    211               operating system and threading subsystem. Other examples could 
    212               be <code class="filename">build.irix.sproc</code>, 
    213               <code class="filename">build.solaris.nspr</code>, etc.</p></li><li><p>Enter the new build directory.</p><pre class="screen">cd build.linux.posix</pre></li><li><p>Configure all the modules making up VR Juggler. This is 
    214               when you must tell the module configure scripts where all the 
    215               package dependencies are found.</p><pre class="screen">../configure.pl --prefix=$HOME/vrjuggler-2.2 --with-java-orb=JDK</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>You will probably have to specify the paths to your 
    216                 local CppDOM, GMTL, and Boost installations using the options 
    217                 <code class="option">--with-cppdom</code>, <code class="option">--with-gmtl</code>, 
    218                 and <code class="option">--with-boost</code> unless they are installed in 
    219                 the default location (<code class="filename">/usr/local</code>). By 
    220                 default, Boost 1.31 installs its header files in a 
    221                 subdirectory of <code class="filename">include</code> called 
    222                 <code class="filename">boost-1_31</code>. That is, if Boost is 
    223                 installed in <code class="filename">/home/user1/pkgs/boost</code>, the 
    224                 header files will be in 
    225                 <code class="filename">/home/user1/pkgs/boost/include/boost-1_31</code>. 
    226                 In this case, you must also specify the option 
    227                 <code class="option">--with-boost-includes=/home/user1/pkgs/boost/include/boost-1_31</code> 
    228                 when running <span><strong class="command">configure.pl</strong></span>.</p></div></li></ol></div><p>By default, the configuration process will configure VR 
    229           Juggler and all of its dependencies. This includes Sonix, which is 
    230           an interesting special case. Sonix can make use of Aaudiere, OpenAL, 
    231           or AudioWorks to add sound to VR Juggler applications. If none of 
    232           those packages is found, Sonix will &#8220;<span class="quote">stub out</span>&#8221; its 
    233           sound APIs. This means that Sonix and the VR Juggler Sound Manager 
    234           can still be used in applications, but no audio will be heard at run 
    235           time. See <a href="#sonix.compile.section" title="Sonix">the section called &#8220;Sonix&#8221;</a> for more 
    236           information about how to configure Sonix to use Audiere, OpenAL, or 
    237           AudioWorks.</p><p>For example uses of <span><strong class="command">configure.pl</strong></span>, take a 
    238           look at the Wiki page relating to building from CVS (<a href="http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs" target="_top">http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs</a>). 
    239           It is not a replacement for this document, but it shows how some 
    240           members of the Juggler team configure VR Juggler. It also has 
    241           information on more advanced uses of <span><strong class="command">configure.pl</strong></span> 
    242           that are beyond the scope of this document.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e500"></a>Using Locally Installed Software</h5></div></div></div><p>As noted in <a href="#source.code.section" title="Getting the Source Code and the Dependencies">the section called &#8220;Getting the Source Code and the Dependencies&#8221;</a>, VR Juggler 
    243           depends on several external software packages. As an example, 
    244           consider the case where the GMTL library is installed in 
    245           <code class="filename">/home/user1/pkgs/GMTL</code> with the headers in 
    246           <code class="filename">/home/user1/pkgs/GMTL/include</code>. To use this 
    247           installation, run <span><strong class="command">configure.pl</strong></span> as follows:</p><pre class="screen">../configure.pl --with-gmtl=/home/user1/pkgs/GMTL</pre><p>The <code class="option">--with-gmtl</code> option could of course be 
    248           mixed in with those shown in the previous section.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="compile.vrjuggler.section"></a>Compiling VR Juggler</h4></div></div></div><p>Once the configuration process is complete, the code can be 
    249         compiled. Remember that we require the use of GNU make 3.78 or 
    250         newer.</p><div class="orderedlist"><ol type="1"><li><p>Compile the source tree using GNU make.</p><pre class="screen">gmake build</pre></li><li><p>Once this completes, you will have a full build of VR 
    251             Juggler. For those who are not interested in developing VR Juggler 
    252             or its component modules, it is recommended that you install the 
    253             software and use the installed version for application 
    254             development. Do this as follows:</p><pre class="screen">gmake install</pre></li></ol></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="compile.individual.section"></a>Tips for Compiling Individual Tools in the Juggler Suite</h3></div></div></div><p>In this section, we provide tips for ensuring that individual 
    255       tools in the Juggler Suite are compiled correctly. For the most part, 
    256       this duplicates information that can be found on the Wiki page relating 
    257       to building from CVS (<a href="http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs" target="_top">http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs</a>).</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sonix.compile.section"></a>Sonix</h4></div></div></div><p>Sonix wraps other audio subsystems such as OpenAL (<a href="http://www.openal.org/" target="_top">www.openal.org</a>), Audiere (<a href="http://audiere.sf.net/" target="_top">audiere.sf.net</a>), or AudioWorks 
    258         (<a href="http://www.multigen.com/" target="_top">multigen.com</a>). At least 
    259         one of these packages must be installed for use by Sonix in order to 
    260         hear sounds in VR Juggler applications. Once you have all the 
    261         necessary source code and third-party package installations, add one 
    262         or more of the following options to your 
    263         <span><strong class="command">configure.pl</strong></span> command line to enable the appropriate 
    264         audio subsystem:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="option">--enable-openal 
    265             --with-openal=&lt;OPENAL_PATH&gt;</code>: Enable the use of 
    266             OpenAL and tell the build where OpenAL is installed. The default 
    267             search path is <code class="filename">/usr/local</code>.</p></li><li><p><code class="option">--enable-audiere 
    268             --with-audiere=&lt;AUDIERE_PATH&gt;</code>: Enable the use of 
    269             Audiere and tell the build where Audiere is installed. The default 
    270             search path is <code class="filename">/usr/local</code>.</p></li><li><p><code class="option">--enable-audioworks 
    271             --with-audioworks=&lt;AUDIOWORKS_PATH&gt;</code>: Enable the use 
    272             of AudioWorks and tell the build where AudioWorks is installed. 
    273             The default search path is <code class="filename">/usr</code>.</p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>AudioWorks and OpenAL cannot be compiled together. They depend 
    274           on mutually exclusive VPR threading subsystems. Warnings will be 
    275           printed by the Sonix configure script indicating this fact. OpenAL 
    276           and Audiere can be compiled together, however.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="tweek.build.section"></a>Tweek</h4></div></div></div><p>Tweek needs JDK 1.4 or newer and a C++ CORBA implementation. 
    277         Currently, we primarily use omniORB 4.0, but omniORB 3.0 can be used. 
    278         Visit the <a href="http://omniorb.sourceforge.net/" target="_top">omniORB 
    279         website</a> to download omniORB.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>IRIX users must configure Tweek (and its VPR dependency) to 
    280           use the POSIX subsystem or the NSPR subsystem. omniORB 
    281           <span class="emphasis"><em>will not work</em></span> with SPROC threads. To configure 
    282           VPR to use either POSIX threads or NSPR threads, pass either 
    283           <code class="option">--enable-subsystem=POSIX</code> or 
    284           <code class="option">--enable-subsystem=NSPR</code> respectively to 
    285           <span><strong class="command">configure.pl</strong></span>.</p></div><p>For the following steps, assume that you have omniORB installed 
    286         in <code class="filename">&lt;OMNIORB_PATH&gt;</code>. Assuming you have the 
    287         external packages installed, do the following from the top-level 
    288         <code class="filename">juggler</code> directory:</p><pre class="screen">mkdir build 
     39            <code class="option">--with-perl</code> argument be passed to 
     40            <span><strong class="command">configure.pl</strong></span>. This argument gives all the 
     41            Autoconf-based configure scripts a hint about where the preferred 
     42            version of Perl lives. If using 
     43            <code class="filename">/usr/freeware/bin/perl</code> to run 
     44            <span><strong class="command">configure.pl</strong></span>, we recommend that the 
     45            <span><strong class="command">configure.pl</strong></span> command line appear similar to the 
     46            following:</p><pre class="screen">/usr/freeware/bin/perl configure.pl --with-perl=/usr/freeware/bin</pre><p>Note that the value given to <code class="option">--with-perl</code> is 
     47            the <span class="emphasis"><em>directory</em></span> where the 
     48            <span><strong class="command">perl</strong></span> executable can be found. The configure 
     49            scripts will add this directory to the front of the search path 
     50            when trying to find a suitable <span><strong class="command">perl</strong></span> executable. 
     51            Once it is found, all the Perl scripts used for configuration, 
     52            compilation, and installation will use that executable.</p><p>To simplify command execution somewhat, it can help to have 
     53            <code class="filename">/usr/freeware/bin</code> (or whatever path is 
     54            appropriate) in your path before <code class="filename">/bin</code> or 
     55            <code class="filename">/usr/bin</code> or any of the other myriad 
     56            directories where Perl might exist on IRIX. In such a situation, 
     57            none of the above extra steps should be necessary. The correct 
     58            version of Perl will be found simply by virtue of it being early 
     59            in your path.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e100"></a>MIPSpro Compiler Version</h4></div></div></div><p>Reports have been made on the VR Juggler mailing list 
     60            regarding compile failures (including segmentation faults within 
     61            the compiler) occur when using the MIPSpro Compilers Version 
     62            7.3.1.1m. We have found upgrading to Version 7.3.1.3m (or newer) 
     63            fixes the problems.</p><p>A new feature of VR Juggler 1.1 and newer is support for GCC 
     64            on IRIX. Users who do not have MIPSpro or cannot upgrade can 
     65            compile and run VR Juggler (without OpenGL Performer support) 
     66            using the version of GCC distributed by SGI. It can be downloaded 
     67            from <a href="http://freeware.sgi.com/index-by-alpha.html" target="_top">http://freeware.sgi.com/index-by-alpha.html</a> 
     68            for free. When configuring the source with 
     69            <span><strong class="command">configure.pl</strong></span> (described later), use the option 
     70            <code class="option">--with-gcc</code>.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e116"></a>Important Note for Win32 Users</h3></div></div></div><p>VR Juggler 1.1 and newer use a lot of C++ features not 
     71         supported by Visual Studio 6.0. Microsoft <a href="http://support.microsoft.com/default.aspx?scid=http://support.microsoft.com:80/support/kb/articles/q243/4/51.asp&amp;NoWebContent=1" target="_top">acknowledges</a> 
     72         the issues concerning noncompliance to the C++ Standard with Visual 
     73         Studio 6.0, and it appears that they have no plans to fix these 
     74         problems. Therefore, we require the use of Visual Studio 7.x (.NET 
     75         2002 or 2003) to compile the source code.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="source.code.section"></a>Getting the Source Code and the Dependencies</h2></div></div></div><p>In this section, we explain how to get the Juggler Project source 
     76      code and the dependencies required to build Juggler. There are two ways 
     77      to get the source code: from a pre-packaged source release archive or 
     78      from the CVS repository on SourceForge. If you got the code from a 
     79      pre-packaged source archive, that code is a complete 
     80      &#8220;<span class="quote">snapshot</span>&#8221; of the CVS repository at the time of release. It 
     81      contains all dependencies that would otherwise have been acquired using 
     82      CVS. It <span class="emphasis"><em>does not</em></span> contain binary dependencies that 
     83      must be downloaded separately (such as NSPR, the Java Developer Kit, a 
     84      C++ compiler, etc.).</p><p>The current list of <span class="emphasis"><em>required</em></span> software 
     85      packages is as follows:</p><div class="itemizedlist"><ul type="disc"><li><p>CppDOM (<a href="http://www.sourceforge.net/projects/xml-cppdom/" target="_top">http://www.sf.net/projects/xml-cppdom/</a>): 
     86            A lightweight, easy-to-use XML parser written in C++. CppDOM must 
     87            be compiled and installed for use with VR Juggler.</p></li><li><p>Boost (<a href="http://www.boost.org/" target="_top">http://www.boost.org/</a>): A C++ 
     88            library providing many powerful utility classes and libraries. 
     89            Boost must be compiled and installed for use with VR 
     90            Juggler.</p></li><li><p>GMTL (<a href="http://ggt.sourceforge.net/" target="_top">http://ggt.sf.net/</a>): A 
     91            generic math library that makes use of C++ templates and STL 
     92            paradigms. GMTL must be installed for use with VR Juggler.</p></li></ul></div><p>The following lists <span class="emphasis"><em>semi-optional</em></span> 
     93      packages:</p><div class="itemizedlist"><ul type="disc"><li><p>NSPR (<a href="http://www.mozilla.org/projects/nspr/" target="_top">http://www.mozilla.org/projects/nspr/</a>): 
     94            The Netscape Portable Runtime, which can be used by VPR for 
     95            threading and sockets (required on Win32 and Solaris).</p></li><li><p>Java Developer Kit (<a href="http://java.sun.com/" target="_top">http://java.sun.com/</a>): The J2SE 
     96            SDK (or JDK) is used to compile all the Java code used in the 
     97            Juggler Project. Without it, none of the Java code can be built. 
     98            We require version 1.4 or newer. The Java Standard Edition (J2SE) 
     99            can be downloaded from <a href="http://java.sun.com/j2se/" target="_top">http://java.sun.com/j2se/</a>.</p></li><li><p>omniORB (<a href="http://www.jdom.org/" target="_top">http://omniorb.sourceforge.net/</a>): 
     100            A C++ implementation of CORBA 2.3, required for the Tweek C++ 
     101            API.</p></li></ul></div><p>The following are fully optional packages that are primarily of 
     102      interest only to people doing development on the Juggler Suite 
     103      itself:</p><div class="itemizedlist"><ul type="disc"><li><p>JUnit (<a href="http://www.junit.org/" target="_top">http://www.junit.org/</a>): A unit 
     104            testing framework for Java.</p></li><li><p>CppUnit (<a href="http://cppunit.sourceforge.net/" target="_top">http://cppunit.sourceforge.net/</a>): 
     105            A unit testing framework for C++. The Juggler C++ test suties make 
     106            use of extensions to CppUnit. An extended version of the CppUnit 
     107            source that includes these extensions can be acquired from the 
     108            Juggler CVS repository in the module <code class="literal">cppunit</code>. 
     109            Refer to <a href="#section.cvs.access" title="How to Get the Juggler Suite from CVS">the section called &#8220;How to Get the Juggler Suite from CVS&#8221;</a> for instructions 
     110            about accessing the Juggler CVS repository.</p></li></ul></div><p>The third-party dependencies must be downloaded from the sites 
     111      listed above and installed manually. You may also have to compile one or 
     112      more of the packages if binary distributions are not available. Which 
     113      packages you download depends on what you already have installed. Note 
     114      carefully which packages are needed based on the software you have 
     115      installed and what versions of tools (such as the JDK) that you 
     116      download.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="section.cvs.access"></a>How to Get the Juggler Suite from CVS</h3></div></div></div><p>You can optionally get the Juggler Project as a source code 
     117         tarball from the website (<a href="http://www.vrjuggler.org/" target="_top">http://www.vrjuggler.org/</a>) or 
     118         you can execute the following commands from a shell to get the code 
     119         from our CVS repository:</p><pre class="screen">cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vrjuggler login 
     120cvs -z3 -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vrjuggler co juggler</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e218"></a>Downloading Third-Party Dependencies</h3></div></div></div><p>In addition to source the dependencies acquired through CVS, 
     121         there are some third-party dependencies that must be installed 
     122         separately. Remember that no Java code in VR Juggler can be used 
     123         without the JDK and a working Java version of CORBA.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e223"></a>Boost</h4></div></div></div><p>The minimum required version of Boost, as of this writing, 
     124            is 1.31.0. The Boost source can be downloaded from <a href="http://www.sf.net/projects/boost/" target="_top">http://www.sf.net/projects/boost/</a>. 
     125            To compile and install Boost, refer to its installation 
     126            documentation (<a href="http://www.boost.org/more/getting_started.html#Build_Install" target="_top">http://www.boost.org/more/getting_started.html#Build_Install</a>). 
     127            Note that you need the command <span><strong class="command">bjam</strong></span> (referred 
     128            to as &#8220;<span class="quote">boost-jam</span>&#8221; on the Boost download page) to 
     129            build Boost.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e240"></a>CppDOM</h4></div></div></div><p>For XML processing, we use CppDOM 0.3.2 or newer. The source 
     130            and binary distributions for some platforms can be downloaded from 
     131            <a href="http://www.sf.net/projects/xml-cppdom/" target="_top">http://www.sf.net/projects/xml-cppdom/</a>. 
     132            If a binary version is not available for your operating system you 
     133            must compile and install CppDOM yourself. Note that you need SCons 
     134            (<a href="http://scons.sourceforge.net/" target="_top">http://scons.sourceforge.net/</a>) 
     135            to build and install CppDOM.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e251"></a>GMTL</h4></div></div></div><p>For high-level mathematical operations, we use GMTL 0.3.2 or 
     136            newer. The source distribution can be downloaded from <a href="http://www.sf.net/projects/ggt/" target="_top">http://www.sf.net/projects/ggt/</a>. 
     137            Note that you need SCons (<a href="http://scons.sourceforge.net/" target="_top">http://scons.sourceforge.net/</a>) 
     138            to build and install GMTL.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e262"></a>Netscape Portable Runtime (NSPR)</h4></div></div></div><p>Our operating system abstraction, VPR, can make use of NSPR 
     139            for operating system primitives. On some platforms (IRIX, FreeBSD, 
     140            Linux, Mac OS X), the use of NSPR is strictly optional. On others 
     141            (Win32, HP-UX, and Solaris), it is required. Based on your local 
     142            system, you should decide whether you need NSPR. Binary versions 
     143            of NSPR can be downloaded from <a href="ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases" target="_top">ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases</a>. 
     144            At this time, we recommend the use of version 4.2 or newer.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e270"></a>Java Developer Kit (also called the J2SE SDK)</h4></div></div></div><p>We make use of the Java programming language in addition to 
     145            C++. Java is used exclusively for GUIs such as Tweek and VRJConfig 
     146            (which is a JavaBean that is loaded into Tweek). To compile the 
     147            Java code, a JDK is necessary. We currently require version 1.4 or 
     148            newer. The Java Standard Edition can be downloaded from <a href="http://java.sun.com/j2se/" target="_top">http://java.sun.com/j2se/</a>. 
     149            More information can be found at <a href="http://java.sun.com/" target="_top">http://java.sun.com/</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e281"></a>omniORB</h4></div></div></div><p>omniORB is a C++ implementation of CORBA 2.3. It is required 
     150            in order to compile the Tweek C++ API. At this time, the Tweek C++ 
     151            API is not required for VR Juggler, but this situation will change 
     152            in the near future. At this time, we primarily use omniORB 4.0.x. 
     153            omniORB can be downloaded from <a href="http://omniorb.sourceforge.net/" target="_top">http://omniorb.sourceforge.net/</a>.</p><p>omniORB 3.0 has strange conventions for how installations 
     154            are made. Within the <code class="filename">bin</code> and 
     155            <code class="filename">lib</code> directories, there are platform-specific 
     156            subdirectories that contain the actual binaries (except when 
     157            installed on FreeBSD via the Ports Collection). Because of this, 
     158            several extra options must be specified in order to tell the Tweek 
     159            configure script where to find everything. Please refer to <a href="#tweek.build.section" title="Tweek">the section called &#8220;Tweek&#8221;</a> for more details on this.</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="compile.section"></a>Compiling</h2></div></div></div><p>In this section, we describe how to compile the Juggler Project. 
     160      We focus on VR Juggler as a whole, but information about some of the 
     161      individual components is provided later.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e304"></a>Important Note Regarding Compiling</h3></div></div></div><p>You have downloaded <span class="emphasis"><em>developmental</em></span> code. It 
     162         may not be stable, and it may not even compile. Compiling VR Juggler 
     163         itself can be a little complicated for anyone who does not have some 
     164         background in using CVS, Autoconf, C++, and <span><strong class="command">make</strong></span> 
     165         or Visual Studio.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e315"></a>Compiling the Juggler Suite of Tools</h3></div></div></div><p>This section explains how to get, configure, and compile all of 
     166         the tools that make up VR Juggler. Each tool compiles to its own 
     167         library and can be installed individually. (Refer to the 
     168         <code class="filename">README</code> file in this directory for more 
     169         information about the specific modules.)</p><p>To build VR Juggler on Windows, you must use the Visual Studio 
     170         solution. After getting the dependencies needed to compile VR Juggler 
     171         (see the next section), refer to the <a href="README-WINDOWS.html" target="_top">README-WINDOWS.html</a> file located in 
     172         this directory. Do not bother to the rest of this document.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="config.vrjuggler.section"></a>Configuring the Juggler Build</h4></div></div></div><p>We now explain the process by which the Juggler build is 
     173            configured. The Juggler Suite makes use of the well-known, widely 
     174            used GNU tools Autoconf and GNU Make. We provide a wrapper script 
     175            written in Perl called <span><strong class="command">configure.pl</strong></span> that gets 
     176            the process started.</p><p>The Juggler build is highly automated. The trickiest part is 
     177            telling the build where to find the third-party dependencies. This 
     178            part can be simplified, however, by installing the third-party 
     179            dependencies in the default location where the search will be 
     180            performed. In most cases, this is <code class="filename">/usr/local</code>, 
     181            but in others it is <code class="filename">/usr</code>. The default search 
     182            location is determined by whether the dependency is considered to 
     183            be a fundamental part of the operating system installation (such 
     184            as OpenGL) or if it is an &#8220;<span class="quote">add-on</span>&#8221; package (such as 
     185            Boost, GMTL, CppDOM, or omniORB).</p><div class="sidebar"><p>The distinction between <code class="filename">/usr/local</code> 
     186               and <code class="filename">/usr</code> is complicated by the fact that 
     187               most Linux distributions have <span class="emphasis"><em>everything</em></span> 
     188               installed in <code class="filename">/usr</code>. While Linux may be 
     189               popular, it should not (yet) be considered a model example of 
     190               how to do things. In traditional UN*X distributions (BSD and 
     191               System V), <code class="filename">/usr</code> is only used for the 
     192               fundamental operating system pieces; 
     193               <code class="filename">/usr/local</code> is used for extra bits. The 
     194               Juggler build is based on these assumptions. Furthermore, most 
     195               open source software packages (e.g., Boost, omniORB, Perl, 
     196               Python) default to installing themselves in 
     197               <code class="filename">/usr/local</code>, which suggests that the 
     198               authors of those tools generally expect their software to be in 
     199               <code class="filename">/usr/local</code>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="using.configure.pl"></a>Using <span><strong class="command">configure.pl</strong></span></h5></div></div></div><p>In the base <code class="filename">juggler</code> source 
     200               directory, we have a &#8220;<span class="quote">global</span>&#8221; configure script 
     201               written in Perl called <span><strong class="command">configure.pl</strong></span>. To get 
     202               the command-line options for this script, use one of the 
     203               following (the second being much more detailed):</p><pre class="screen">./configure.pl --help 
     204./configure.pl --manual</pre><p>To configure your system, you will need to see what 
     205               options all the Autoconf-based configure scripts in VR Juggler 
     206               need. To get this text, enter:</p><pre class="screen">./configure.pl --all-help</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>In order for this to work, the configure script for 
     207                     each of the Juggler modules must be generated. This can 
     208                     be done manually by running <span><strong class="command">autogen.sh</strong></span> 
     209                     in the top-level <code class="filename">juggler</code> directory. 
     210                     It use is simple:</p><pre class="screen">./autogen.sh</pre><p>This <span><strong class="command">autogen.sh</strong></span> script must be 
     211                     run from the directory where it exists. Do not try to run 
     212                     it from a build directory or any other place in the 
     213                     Juggler source tree. The same holds for the individual 
     214                     <span><strong class="command">autogen.sh</strong></span> scripts in the various 
     215                     modules, should you need to run one individually.</p></div><p><span><strong class="command">configure.pl</strong></span> can run in a 
     216               unique &#8220;<span class="quote">build</span>&#8221; directory or in the directory where 
     217               it resides. Here is how we (the Juggler Team) have been using 
     218               it:</p><div class="orderedlist"><ol type="1"><li><p>Make a directory for compiling. There are many good 
     219                     reasons to do this away from the main source tree (though 
     220                     they will not be listed here).</p><pre class="screen">mkdir build.linux.posix</pre><p>This example using an ad hoc naming convention 
     221                     based on operating system and threading subsystem. Other 
     222                     examples could be <code class="filename">build.irix.sproc</code>, 
     223                     <code class="filename">build.solaris.nspr</code>, etc.</p></li><li><p>Enter the new build directory.</p><pre class="screen">cd build.linux.posix</pre></li><li><p>Configure all the modules making up VR Juggler. 
     224                     This is when you must tell the module configure scripts 
     225                     where all the package dependencies are found.</p><pre class="screen">../configure.pl --prefix=$HOME/vrjuggler-2.2 --with-java-orb=JDK</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>You will probably have to specify the paths to 
     226                        your local CppDOM, GMTL, and Boost installations using 
     227                        the options <code class="option">--with-cppdom</code>, 
     228                        <code class="option">--with-gmtl</code>, and 
     229                        <code class="option">--with-boost</code> unless they are 
     230                        installed in the default location 
     231                        (<code class="filename">/usr/local</code>). By default, Boost 
     232                        1.31 installs its header files in a subdirectory of 
     233                        <code class="filename">include</code> called 
     234                        <code class="filename">boost-1_31</code>. That is, if Boost is 
     235            &n