Changeset 18950

Show
Ignore:
Timestamp:
06/04/06 08:28:00 (2 years ago)
Author:
patrick
Message:

Reformatted to use three spaces for indentation. On the trunk, I
accidentally made this formatting change in Revision 18807 and did not
notice. No content changes.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • juggler/branches/2.0/doc/INSTALL.xml

    r17625 r18950  
    33"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> 
    44<article> 
    5   <articleinfo> 
    6     <title>Building and Installing the Juggler Project (Version 2.0)</title> 
    7  
    8     <authorgroup> 
    9       <author> 
    10         <othername>The Juggler Team</othername> 
    11       </author> 
    12     </authorgroup> 
    13  
    14     <pubdate>$Date$</pubdate> 
    15   </articleinfo> 
    16  
    17   <section> 
    18     <title>Introduction</title> 
    19  
    20     <para>You have downloaded the source code for Version 2.0 of the Juggler 
    21     Project. This document explains how to build the modules of the Juggler 
    22     Project from the source code. We begin by explaining some issues related 
    23     to specific operating systems. We then explain how to get the source code 
    24     from our CVS repository. (Those users who downloaded a pre-packaged source 
    25     release can skip ahead to <xref linkend="using.configure.pl" />). We 
    26     conclude with instructions on how to build VR Juggler and its individual 
    27     components.</para> 
    28  
    29     <para>Before reading further, we recommend that readers take a look at the 
    30     Wiki page relating to building from CVS (<ulink 
    31     url="http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs">http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs</ulink>). 
    32     It is a <emphasis>supplement</emphasis> to this document containing tips 
    33     and reminders for those users building the CVS version of VR Juggler. It 
    34     is not a replacement for this document, nor can it stand on its own as 
    35     build instructions. You are reading the definitive build instructions; the 
    36     Wiki page merely provides informal, extra information.</para> 
    37  
    38     <section> 
    39       <title>Important Notes for IRIX Users</title> 
    40  
    41       <para>Despite our best efforts, there are some issues related to 
    42       compiling the Juggler Project on IRIX. We introduce them in this section 
    43       and explain how to work around them.</para> 
     5   <articleinfo> 
     6      <title>Building and Installing the Juggler Project (Version 2.0)</title> 
     7 
     8      <authorgroup> 
     9         <author> 
     10            <othername>The Juggler Team</othername> 
     11         </author> 
     12      </authorgroup> 
     13 
     14      <pubdate>$Date$</pubdate> 
     15   </articleinfo> 
     16 
     17   <section> 
     18      <title>Introduction</title> 
     19 
     20      <para>You have downloaded the source code for Version 2.0 of the Juggler 
     21      Project. This document explains how to build the modules of the Juggler 
     22      Project from the source code. We begin by explaining some issues related 
     23      to specific operating systems. We then explain how to get the source 
     24      code from our CVS repository. (Those users who downloaded a pre-packaged 
     25      source release can skip ahead to <xref linkend="using.configure.pl" />). 
     26      We conclude with instructions on how to build VR Juggler and its 
     27      individual components.</para> 
     28 
     29      <para>Before reading further, we recommend that readers take a look at 
     30      the Wiki page relating to building from CVS (<ulink 
     31      url="http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs">http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs</ulink>). 
     32      It is a <emphasis>supplement</emphasis> to this document containing tips 
     33      and reminders for those users building the CVS version of VR Juggler. It 
     34      is not a replacement for this document, nor can it stand on its own as 
     35      build instructions. You are reading the definitive build instructions; 
     36      the Wiki page merely provides informal, extra information.</para> 
    4437 
    4538      <section> 
    46         <title>Perl Version</title> 
    47  
    48         <para>There are many Perl scripts used as part of getting, 
    49         configuring, and building the Juggler Suite of tools. In particular, 
    50         two scripts required for compiling need Perl 5.005 or newer. The 
    51         version of Perl that ships with IRIX 6.5 is very old (circa 1997) and 
    52         does not work with many Perl scripts we have written. SGI provides a 
    53         much newer version of Perl (5.6.1) with their freeware tools (<ulink 
    54         url="http://freeware.sgi.com/">http://freeware.sgi.com/</ulink>). It 
    55         will be necessary to install that version for our scripts to work. 
    56         This version is typically installed as 
    57         <filename>/usr/freeware/bin/perl</filename>.</para> 
    58  
    59         <para>Once you have a modern Perl installed, you can run various Perl 
    60         scripts as follows:</para> 
    61  
    62         <screen>/usr/freeware/bin/perl &lt;script-name&gt;</screen> 
    63  
    64         <para>The above will be required any time a Perl script fails with an 
    65         error similar to the following:</para> 
    66  
    67         <screen>Perl 5.005 required--this is only version 5.00404, stopped at ./configure.pl line 35. 
     39         <title>Important Notes for IRIX Users</title> 
     40 
     41         <para>Despite our best efforts, there are some issues related to 
     42         compiling the Juggler Project on IRIX. We introduce them in this 
     43         section and explain how to work around them.</para> 
     44 
     45         <section> 
     46            <title>Perl Version</title> 
     47 
     48            <para>There are many Perl scripts used as part of getting, 
     49            configuring, and building the Juggler Suite of tools. In 
     50            particular, two scripts required for compiling need Perl 5.005 or 
     51            newer. The version of Perl that ships with IRIX 6.5 is very old 
     52            (circa 1997) and does not work with many Perl scripts we have 
     53            written. SGI provides a much newer version of Perl (5.6.1) with 
     54            their freeware tools (<ulink 
     55            url="http://freeware.sgi.com/">http://freeware.sgi.com/</ulink>). 
     56            It will be necessary to install that version for our scripts to 
     57            work. This version is typically installed as 
     58            <filename>/usr/freeware/bin/perl</filename>.</para> 
     59 
     60            <para>Once you have a modern Perl installed, you can run various 
     61            Perl scripts as follows:</para> 
     62 
     63            <screen>/usr/freeware/bin/perl &lt;script-name&gt;</screen> 
     64 
     65            <para>The above will be required any time a Perl script fails with 
     66            an error similar to the following:</para> 
     67 
     68            <screen>Perl 5.005 required--this is only version 5.00404, stopped at ./configure.pl line 35. 
    6869BEGIN failed--compilation aborted at ./configure.pl line 35.</screen> 
    6970 
    70         <para>Furthermore, it is highly recommended that the 
    71         <option>--with-perl</option> argument be passed to 
    72         <command>configure.pl</command>. This argument gives all the 
    73         Autoconf-based configure scripts a hint about where the preferred 
    74         version of Perl lives. If using 
    75         <filename>/usr/freeware/bin/perl</filename> to run 
    76         <command>configure.pl</command>, we recommend that the 
    77         <command>configure.pl</command> command line appear similar to the 
    78         following:</para> 
    79  
    80         <screen>/usr/freeware/bin/perl configure.pl --with-perl=/usr/freeware/bin</screen> 
    81  
    82         <para>Note that the value given to <option>--with-perl</option> is the 
    83         <emphasis>directory</emphasis> where the <command>perl</command> 
    84         executable can be found. The configure scripts will add this directory 
    85         to the front of the search path when trying to find a suitable 
    86         <command>perl</command> executable. Once it is found, all the Perl 
    87         scripts used for configuration, compilation, and installation will use 
    88         that executable.</para> 
    89  
    90         <para>To simplify command execution somewhat, it can help to have 
    91         <filename>/usr/freeware/bin</filename> (or whatever path is 
    92         appropriate) in your path before <filename>/bin</filename> or 
    93         <filename>/usr/bin</filename> or any of the other myriad directories 
    94         where Perl might exist on IRIX. In such a situation, none of the above 
    95         extra steps should be necessary. The correct version of Perl will be 
    96         found simply by virtue of it being early in your path.</para> 
     71            <para>Furthermore, it is highly recommended that the 
     72            <option>--with-perl</option> argument be passed to 
     73            <command>configure.pl</command>. This argument gives all the 
     74            Autoconf-based configure scripts a hint about where the preferred 
     75            version of Perl lives. If using 
     76            <filename>/usr/freeware/bin/perl</filename> to run 
     77            <command>configure.pl</command>, we recommend that the 
     78            <command>configure.pl</command> command line appear similar to the 
     79            following:</para> 
     80 
     81            <screen>/usr/freeware/bin/perl configure.pl --with-perl=/usr/freeware/bin</screen> 
     82 
     83            <para>Note that the value given to <option>--with-perl</option> is 
     84            the <emphasis>directory</emphasis> where the 
     85            <command>perl</command> executable can be found. The configure 
     86            scripts will add this directory to the front of the search path 
     87            when trying to find a suitable <command>perl</command> executable. 
     88            Once it is found, all the Perl scripts used for configuration, 
     89            compilation, and installation will use that executable.</para> 
     90 
     91            <para>To simplify command execution somewhat, it can help to have 
     92            <filename>/usr/freeware/bin</filename> (or whatever path is 
     93            appropriate) in your path before <filename>/bin</filename> or 
     94            <filename>/usr/bin</filename> or any of the other myriad 
     95            directories where Perl might exist on IRIX. In such a situation, 
     96            none of the above extra steps should be necessary. The correct 
     97            version of Perl will be found simply by virtue of it being early 
     98            in your path.</para> 
     99         </section> 
     100 
     101         <section> 
     102            <title>MIPSpro Compiler Version</title> 
     103 
     104            <para>Reports have been made on the VR Juggler mailing list 
     105            regarding compile failures (including segmentation faults within 
     106            the compiler) occur when using the MIPSpro Compilers Version 
     107            7.3.1.1m. We have found upgrading to Version 7.3.1.3m (or newer) 
     108            fixes the problems.</para> 
     109 
     110            <para>A new feature of VR Juggler 1.1 and newer is support for GCC 
     111            on IRIX. Users who do not have MIPSpro or cannot upgrade can 
     112            compile and run VR Juggler (without OpenGL Performer support) 
     113            using the version of GCC distributed by SGI. It can be downloaded 
     114            from <ulink 
     115            url="http://freeware.sgi.com/index-by-alpha.html">http://freeware.sgi.com/index-by-alpha.html</ulink> 
     116            for free. When configuring the source with 
     117            <command>configure.pl</command> (described later), use the option 
     118            <option>--with-gcc</option>.</para> 
     119         </section> 
    97120      </section> 
    98121 
    99122      <section> 
    100         <title>MIPSpro Compiler Version</title> 
    101  
    102         <para>Reports have been made on the VR Juggler mailing list regarding 
    103         compile failures (including segmentation faults within the compiler) 
    104         occur when using the MIPSpro Compilers Version 7.3.1.1m. We have found 
    105         upgrading to Version 7.3.1.3m (or newer) fixes the problems.</para> 
    106  
    107         <para>A new feature of VR Juggler 1.1 and newer is support for GCC on 
    108         IRIX. Users who do not have MIPSpro or cannot upgrade can compile and 
    109         run VR Juggler (without OpenGL Performer support) using the version of 
    110         GCC distributed by SGI. It can be downloaded from <ulink 
    111         url="http://freeware.sgi.com/index-by-alpha.html">http://freeware.sgi.com/index-by-alpha.html</ulink> 
    112         for free. When configuring the source with 
    113         <command>configure.pl</command> (described later), use the option 
    114         <option>--with-gcc</option>.</para> 
     123         <title>Important Note for Win32 Users</title> 
     124 
     125         <para>VR Juggler 1.1 and newer use a lot of C++ features not 
     126         supported by Visual Studio 6.0. Microsoft <ulink 
     127         url="http://support.microsoft.com/default.aspx?scid=http://support.microsoft.com:80/support/kb/articles/q243/4/51.asp&amp;NoWebContent=1">acknowledges</ulink> 
     128         the issues concerning noncompliance to the C++ Standard with Visual 
     129         Studio 6.0, and it appears that they have no plans to fix these 
     130         problems. Therefore, we require the use of Visual Studio 7.x (.NET 
     131         2002 or 2003) to compile the source code.</para> 
    115132      </section> 
    116     </section> 
    117  
    118     <section> 
    119       <title>Important Note for Win32 Users</title> 
    120  
    121       <para>VR Juggler 1.1 and newer use a lot of C++ features not supported 
    122       by Visual Studio 6.0. Microsoft <ulink 
    123       url="http://support.microsoft.com/default.aspx?scid=http://support.microsoft.com:80/support/kb/articles/q243/4/51.asp&amp;NoWebContent=1">acknowledges</ulink> 
    124       the issues concerning noncompliance to the C++ Standard with Visual 
    125       Studio 6.0, and it appears that they have no plans to fix these 
    126       problems. Therefore, we require the use of Visual Studio 7.x (.NET 2002 
    127       or 2003) to compile the source code.</para> 
    128     </section> 
    129   </section> 
    130  
    131   <section id="source.code.section"> 
    132     <title>Getting the Source Code and the Dependencies</title> 
    133  
    134     <para>In this section, we explain how to get the Juggler Project source 
    135     code and the dependencies required to build Juggler. There are two ways to 
    136     get the source code: from a pre-packaged source release archive or from 
    137     the CVS repository on SourceForge. If you got the code from a pre-packaged 
    138     source archive, that code is a complete <quote>snapshot</quote> of the CVS 
    139     repository at the time of release. It contains all dependencies that would 
    140     otherwise have been acquired using CVS. It <emphasis>does not</emphasis> 
    141     contain binary dependencies that must be downloaded separately (such as 
    142     NSPR, the Java Developer Kit, a C++ compiler, etc.).</para> 
    143  
    144     <para>The current list of <emphasis>required</emphasis> software packages 
    145     is as follows:</para> 
    146  
    147     <itemizedlist> 
    148       <listitem> 
    149         <para>CppDOM (<ulink 
    150         url="http://www.sourceforge.net/projects/xml-cppdom/">http://www.sf.net/projects/xml-cppdom/</ulink>): 
    151         A lightweight, easy-to-use XML parser written in C++. CppDOM must be 
    152         compiled and installed for use with VR Juggler.</para> 
    153       </listitem> 
    154  
    155       <listitem> 
    156         <para>Boost (<ulink 
    157         url="http://www.boost.org/">http://www.boost.org/</ulink>): A C++ 
    158         library providing many powerful utility classes and libraries. Boost 
    159         must be compiled and installed for use with VR Juggler.</para> 
    160       </listitem> 
    161  
    162       <listitem> 
    163         <para>GMTL (<ulink 
    164         url="http://ggt.sourceforge.net/">http://ggt.sf.net/</ulink>): A 
    165         generic math library that makes use of C++ templates and STL 
    166         paradigms. GMTL must be installed for use with VR Juggler.</para> 
    167       </listitem> 
    168     </itemizedlist> 
    169  
    170     <para>The following lists <emphasis>semi-optional</emphasis> 
    171     packages:</para> 
    172  
    173     <itemizedlist> 
    174       <listitem> 
    175         <para>NSPR (<ulink 
    176         url="http://www.mozilla.org/projects/nspr/">http://www.mozilla.org/projects/nspr/</ulink>): 
    177         The Netscape Portable Runtime, which can be used by VPR for threading 
    178         and sockets (required on Win32 and Solaris).</para> 
    179       </listitem> 
    180  
    181       <listitem> 
    182         <para>Java Developer Kit (<ulink 
    183         url="http://java.sun.com/">http://java.sun.com/</ulink>): The J2SE SDK 
    184         (or JDK) is used to compile all the Java code used in the Juggler 
    185         Project. Without it, none of the Java code can be built. We require 
    186         version 1.4 or newer. The Java Standard Edition (J2SE) can be 
    187         downloaded from <ulink 
    188         url="http://java.sun.com/j2se/">http://java.sun.com/j2se/</ulink>.</para> 
    189       </listitem> 
    190  
    191       <listitem> 
    192         <para>omniORB (<ulink 
    193         url="http://www.jdom.org/">http://omniorb.sourceforge.net/</ulink>): A 
    194         C++ implementation of CORBA 2.3, required for the Tweek C++ 
    195         API.</para> 
    196       </listitem> 
    197     </itemizedlist> 
    198  
    199     <para>The following are fully optional packages that are primarily of 
    200     interest only to people doing development on the Juggler Suite 
    201     itself:</para> 
    202  
    203     <itemizedlist> 
    204       <listitem> 
    205         <para>JUnit (<ulink 
    206         url="http://www.junit.org/">http://www.junit.org/</ulink>): A unit 
    207         testing framework for Java.</para> 
    208       </listitem> 
    209  
    210       <listitem> 
    211         <para>CppUnit (<ulink 
    212         url="http://cppunit.sourceforge.net/">http://cppunit.sourceforge.net/</ulink>): 
    213         A unit testing framework for C++. The Juggler C++ test suties make use 
    214         of extensions to CppUnit. An extended version of the CppUnit source 
    215         that includes these extensions can be acquired from the Juggler CVS 
    216         repository in the module <literal>cppunit</literal>. Refer to <xref 
    217         linkend="section.cvs.access" /> for instructions about accessing the 
    218         Juggler CVS repository.</para> 
    219       </listitem> 
    220     </itemizedlist> 
    221  
    222     <para>The third-party dependencies must be downloaded from the sites 
    223     listed above and installed manually. You may also have to compile one or 
    224     more of the packages if binary distributions are not available. Which 
    225     packages you download depends on what you already have installed. Note 
    226     carefully which packages are needed based on the software you have 
    227     installed and what versions of tools (such as the JDK) that you 
    228     download.</para> 
    229  
    230     <section id="section.cvs.access"> 
    231       <title>How to Get the Juggler Suite from CVS</title> 
    232  
    233       <para>You can optionally get the Juggler Project as a source code 
    234       tarball from the website (<ulink 
    235       url="http://www.vrjuggler.org/">http://www.vrjuggler.org/</ulink>) or 
    236       you can execute the following commands from a shell to get the code from 
    237       our CVS repository:</para> 
    238  
    239       <screen>cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vrjuggler login 
     133   </section> 
     134 
     135   <section id="source.code.section"> 
     136      <title>Getting the Source Code and the Dependencies</title> 
     137 
     138      <para>In this section, we explain how to get the Juggler Project source 
     139      code and the dependencies required to build Juggler. There are two ways 
     140      to get the source code: from a pre-packaged source release archive or 
     141      from the CVS repository on SourceForge. If you got the code from a 
     142      pre-packaged source archive, that code is a complete 
     143      <quote>snapshot</quote> of the CVS repository at the time of release. It 
     144      contains all dependencies that would otherwise have been acquired using 
     145      CVS. It <emphasis>does not</emphasis> contain binary dependencies that 
     146      must be downloaded separately (such as NSPR, the Java Developer Kit, a 
     147      C++ compiler, etc.).</para> 
     148 
     149      <para>The current list of <emphasis>required</emphasis> software 
     150      packages is as follows:</para> 
     151 
     152      <itemizedlist> 
     153         <listitem> 
     154            <para>CppDOM (<ulink 
     155            url="http://www.sourceforge.net/projects/xml-cppdom/">http://www.sf.net/projects/xml-cppdom/</ulink>): 
     156            A lightweight, easy-to-use XML parser written in C++. CppDOM must 
     157            be compiled and installed for use with VR Juggler.</para> 
     158         </listitem> 
     159 
     160         <listitem> 
     161            <para>Boost (<ulink 
     162            url="http://www.boost.org/">http://www.boost.org/</ulink>): A C++ 
     163            library providing many powerful utility classes and libraries. 
     164            Boost must be compiled and installed for use with VR 
     165            Juggler.</para> 
     166         </listitem> 
     167 
     168         <listitem> 
     169            <para>GMTL (<ulink 
     170            url="http://ggt.sourceforge.net/">http://ggt.sf.net/</ulink>): A 
     171            generic math library that makes use of C++ templates and STL 
     172            paradigms. GMTL must be installed for use with VR Juggler.</para> 
     173         </listitem> 
     174      </itemizedlist> 
     175 
     176      <para>The following lists <emphasis>semi-optional</emphasis> 
     177      packages:</para> 
     178 
     179      <itemizedlist> 
     180         <listitem> 
     181            <para>NSPR (<ulink 
     182            url="http://www.mozilla.org/projects/nspr/">http://www.mozilla.org/projects/nspr/</ulink>): 
     183            The Netscape Portable Runtime, which can be used by VPR for 
     184            threading and sockets (required on Win32 and Solaris).</para> 
     185         </listitem> 
     186 
     187         <listitem> 
     188            <para>Java Developer Kit (<ulink 
     189            url="http://java.sun.com/">http://java.sun.com/</ulink>): The J2SE 
     190            SDK (or JDK) is used to compile all the Java code used in the 
     191            Juggler Project. Without it, none of the Java code can be built. 
     192            We require version 1.4 or newer. The Java Standard Edition (J2SE) 
     193            can be downloaded from <ulink 
     194            url="http://java.sun.com/j2se/">http://java.sun.com/j2se/</ulink>.</para> 
     195         </listitem> 
     196 
     197         <listitem> 
     198            <para>omniORB (<ulink 
     199            url="http://www.jdom.org/">http://omniorb.sourceforge.net/</ulink>): 
     200            A C++ implementation of CORBA 2.3, required for the Tweek C++ 
     201            API.</para> 
     202         </listitem> 
     203      </itemizedlist> 
     204 
     205      <para>The following are fully optional packages that are primarily of 
     206      interest only to people doing development on the Juggler Suite 
     207      itself:</para> 
     208 
     209      <itemizedlist> 
     210         <listitem> 
     211            <para>JUnit (<ulink 
     212            url="http://www.junit.org/">http://www.junit.org/</ulink>): A unit 
     213            testing framework for Java.</para> 
     214         </listitem> 
     215 
     216         <listitem> 
     217            <para>CppUnit (<ulink 
     218            url="http://cppunit.sourceforge.net/">http://cppunit.sourceforge.net/</ulink>): 
     219            A unit testing framework for C++. The Juggler C++ test suties make 
     220            use of extensions to CppUnit. An extended version of the CppUnit 
     221            source that includes these extensions can be acquired from the 
     222            Juggler CVS repository in the module <literal>cppunit</literal>. 
     223            Refer to <xref linkend="section.cvs.access" /> for instructions 
     224            about accessing the Juggler CVS repository.</para> 
     225         </listitem> 
     226      </itemizedlist> 
     227 
     228      <para>The third-party dependencies must be downloaded from the sites 
     229      listed above and installed manually. You may also have to compile one or 
     230      more of the packages if binary distributions are not available. Which 
     231      packages you download depends on what you already have installed. Note 
     232      carefully which packages are needed based on the software you have 
     233      installed and what versions of tools (such as the JDK) that you 
     234      download.</para> 
     235 
     236      <section id="section.cvs.access"> 
     237         <title>How to Get the Juggler Suite from CVS</title> 
     238 
     239         <para>You can optionally get the Juggler Project as a source code 
     240         tarball from the website (<ulink 
     241         url="http://www.vrjuggler.org/">http://www.vrjuggler.org/</ulink>) or 
     242         you can execute the following commands from a shell to get the code 
     243         from our CVS repository:</para> 
     244 
     245         <screen>cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vrjuggler login 
    240246cvs -z3 -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vrjuggler co juggler</screen> 
    241     </section> 
    242  
    243     <section> 
    244       <title>Downloading Third-Party Dependencies</title> 
    245  
    246       <para>In addition to source the dependencies acquired through CVS, there 
    247       are some third-party dependencies that must be installed separately. 
    248       Remember that no Java code in VR Juggler can be used without the JDK and 
    249       a working Java version of CORBA.</para> 
     247      </section> 
    250248 
    251249      <section> 
    252         <title>Boost</title> 
    253  
    254         <para>The minimum required version of Boost, as of this writing, is 
    255         1.31.0. The Boost source can be downloaded from <ulink 
    256         url="http://www.sf.net/projects/boost/">http://www.sf.net/projects/boost/</ulink>. 
    257         To compile and install Boost, refer to its installation documentation 
    258         (<ulink 
    259         url="http://www.boost.org/more/getting_started.html#Build_Install">http://www.boost.org/more/getting_started.html#Build_Install</ulink>). 
    260         Note that you need the command <command>bjam</command> (referred to as 
    261         <quote>boost-jam</quote> on the Boost download page) to build 
    262         Boost.</para> 
     250         <title>Downloading Third-Party Dependencies</title> 
     251 
     252         <para>In addition to source the dependencies acquired through CVS, 
     253         there are some third-party dependencies that must be installed 
     254         separately. Remember that no Java code in VR Juggler can be used 
     255         without the JDK and a working Java version of CORBA.</para> 
     256 
     257         <section> 
     258            <title>Boost</title> 
     259 
     260            <para>The minimum required version of Boost, as of this writing, 
     261            is 1.31.0. The Boost source can be downloaded from <ulink 
     262            url="http://www.sf.net/projects/boost/">http://www.sf.net/projects/boost/</ulink>. 
     263            To compile and install Boost, refer to its installation 
     264            documentation (<ulink 
     265            url="http://www.boost.org/more/getting_started.html#Build_Install">http://www.boost.org/more/getting_started.html#Build_Install</ulink>). 
     266            Note that you need the command <command>bjam</command> (referred 
     267            to as <quote>boost-jam</quote> on the Boost download page) to 
     268            build Boost.</para> 
     269         </section> 
     270 
     271         <section> 
     272            <title>CppDOM</title> 
     273 
     274            <para>For XML processing, we use CppDOM 0.3.2 or newer. The source 
     275            and binary distributions for some platforms can be downloaded from 
     276            <ulink 
     277            url="http://www.sf.net/projects/xml-cppdom/">http://www.sf.net/projects/xml-cppdom/</ulink>. 
     278            If a binary version is not available for your operating system you 
     279            must compile and install CppDOM yourself. Note that you need SCons 
     280            (<ulink 
     281            url="http://scons.sourceforge.net/">http://scons.sourceforge.net/</ulink>) 
     282            to build and install CppDOM.</para> 
     283         </section> 
     284 
     285         <section> 
     286            <title>GMTL</title> 
     287 
     288            <para>For high-level mathematical operations, we use GMTL 0.3.2 or 
     289            newer. The source distribution can be downloaded from <ulink 
     290            url="http://www.sf.net/projects/ggt/">http://www.sf.net/projects/ggt/</ulink>. 
     291            Note that you need SCons (<ulink 
     292            url="http://scons.sourceforge.net/">http://scons.sourceforge.net/</ulink>) 
     293            to build and install GMTL.</para> 
     294         </section> 
     295 
     296         <section> 
     297            <title>Netscape Portable Runtime (NSPR)</title> 
     298 
     299            <para>Our operating system abstraction, VPR, can make use of NSPR 
     300            for operating system primitives. On some platforms (IRIX, FreeBSD, 
     301            Linux, Mac OS X), the use of NSPR is strictly optional. On others 
     302            (Win32, HP-UX, and Solaris), it is required. Based on your local 
     303            system, you should decide whether you need NSPR. Binary versions 
     304            of NSPR can be downloaded from <ulink 
     305            url="ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases">ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases</ulink>. 
     306            At this time, we recommend the use of version 4.2 or newer.</para> 
     307         </section> 
     308 
     309         <section> 
     310            <title>Java Developer Kit (also called the J2SE SDK)</title> 
     311 
     312            <para>We make use of the Java programming language in addition to 
     313            C++. Java is used exclusively for GUIs such as Tweek and VRJConfig 
     314            (which is a JavaBean that is loaded into Tweek). To compile the 
     315            Java code, a JDK is necessary. We currently require version 1.4 or 
     316            newer. The Java Standard Edition can be downloaded from <ulink 
     317            url="http://java.sun.com/j2se/">http://java.sun.com/j2se/</ulink>. 
     318            More information can be found at <ulink 
     319            url="http://java.sun.com/">http://java.sun.com/</ulink>.</para> 
     320         </section> 
     321 
     322         <section> 
     323            <title>omniORB</title> 
     324 
     325            <para>omniORB is a C++ implementation of CORBA 2.3. It is required 
     326            in order to compile the Tweek C++ API. At this time, the Tweek C++ 
     327            API is not required for VR Juggler, but this situation will change 
     328            in the near future. At this time, we primarily use omniORB 4.0.x. 
     329            omniORB can be downloaded from <ulink 
     330            url="http://omniorb.sourceforge.net/">http://omniorb.sourceforge.net/</ulink>.</para> 
     331 
     332            <para>omniORB 3.0 has strange conventions for how installations 
     333            are made. Within the <filename>bin</filename> and 
     334            <filename>lib</filename> directories, there are platform-specific 
     335            subdirectories that contain the actual binaries (except when 
     336            installed on FreeBSD via the Ports Collection). Because of this, 
     337            several extra options must be specified in order to tell the Tweek 
     338            configure script where to find everything. Please refer to <xref 
     339            linkend="tweek.build.section" /> for more details on this.</para> 
     340         </section> 
    263341      </section> 
     342   </section> 
     343 
     344   <section id="compile.section"> 
     345      <title>Compiling</title> 
     346 
     347      <para>In this section, we describe how to compile the Juggler Project. 
     348      We focus on VR Juggler as a whole, but information about some of the 
     349      individual components is provided later.</para> 
    264350 
    265351      <section> 
    266         <title>CppDOM</title> 
    267  
    268         <para>For XML processing, we use CppDOM 0.3.2 or newer. The source and 
    269         binary distributions for some platforms can be downloaded from <ulink 
    270         url="http://www.sf.net/projects/xml-cppdom/">http://www.sf.net/projects/xml-cppdom/</ulink>. 
    271         If a binary version is not available for your operating system you 
    272         must compile and install CppDOM yourself. Note that you need SCons 
    273         (<ulink 
    274         url="http://scons.sourceforge.net/">http://scons.sourceforge.net/</ulink>) 
    275         to build and install CppDOM.</para> 
     352         <title>Important Note Regarding Compiling</title> 
     353 
     354         <para>You have downloaded <emphasis>developmental</emphasis> code. It 
     355         may not be stable, and it may not even compile. Compiling VR Juggler 
     356         itself can be a little complicated for anyone who does not have some 
     357         background in using CVS, Autoconf, C++, and <command>make</command> 
     358         or Visual Studio.</para> 
    276359      </section> 
    277360 
    278361      <section> 
    279         <title>GMTL</title> 
    280  
    281         <para>For high-level mathematical operations, we use GMTL 0.3.2 or 
    282         newer. The source distribution can be downloaded from <ulink 
    283         url="http://www.sf.net/projects/ggt/">http://www.sf.net/projects/ggt/</ulink>. 
    284         Note that you need SCons (<ulink 
    285         url="http://scons.sourceforge.net/">http://scons.sourceforge.net/</ulink>) 
    286         to build and install GMTL.</para> 
     362         <title>Compiling the Juggler Suite of Tools</title> 
     363 
     364         <para>This section explains how to get, configure, and compile all of 
     365         the tools that make up VR Juggler. Each tool compiles to its own 
     366         library and can be installed individually. (Refer to the 
     367         <filename>README</filename> file in this directory for more 
     368         information about the specific modules.)</para> 
     369 
     370         <para>To build VR Juggler on Windows, you must use the Visual Studio 
     371         solution. After getting the dependencies needed to compile VR Juggler 
     372         (see the next section), refer to the <ulink 
     373         url="vc7/README.html">README.html</ulink> file located in the 
     374         <filename>vc7</filename> subdirectory of this directory. Do not 
     375         bother to the rest of this document.</para> 
     376 
     377         <section id="config.vrjuggler.section"> 
     378            <title>Configuring the Juggler Build</title> 
     379 
     380            <para>We now explain the process by which the Juggler build is 
     381            configured. The Juggler Suite makes use of the well-known, widely 
     382            used GNU tools Autoconf and GNU Make. We provide a wrapper script 
     383            written in Perl called <command>configure.pl</command> that gets 
     384            the process started.</para> 
     385 
     386            <para>The Juggler build is highly automated. The trickiest part is 
     387            telling the build where to find the third-party dependencies. This 
     388            part can be simplified, however, by installing the third-party 
     389            dependencies in the default location where the search will be 
     390            performed. In most cases, this is <filename>/usr/local</filename>, 
     391            but in others it is <filename>/usr</filename>. The default search 
     392            location is determined by whether the dependency is considered to 
     393            be a fundamental part of the operating system installation (such 
     394            as OpenGL) or if it is an <quote>add-on</quote> package (such as 
     395            Boost, GMTL, CppDOM, or omniORB).</para> 
     396 
     397            <sidebar> 
     398               <para>The distinction between <filename>/usr/local</filename> 
     399               and <filename>/usr</filename> is complicated by the fact that 
     400               most Linux distributions have <emphasis>everything</emphasis> 
     401               installed in <filename>/usr</filename>. While Linux may be 
     402               popular, it should not (yet) be considered a model example of 
     403               how to do things. In traditional UN*X distributions (BSD and 
     404               System V), <filename>/usr</filename> is only used for the 
     405               fundamental operating system pieces; 
     406               <filename>/usr/local</filename> is used for extra bits. The 
     407               Juggler build is based on these assumptions. Furthermore, most 
     408               open source software packages (e.g., Boost, omniORB, Perl, 
     409               Python) default to installing themselves in 
     410               <filename>/usr/local</filename>, which suggests that the 
     411               authors of those tools generally expect their software to be in 
     412               <filename>/usr/local</filename>.</para> 
     413            </sidebar> 
     414 
     415            <section id="using.configure.pl"> 
     416               <title>Using <command>configure.pl</command></title> 
     417 
     418               <para>In the base <filename>juggler</filename> source 
     419               directory, we have a <quote>global</quote> configure script 
     420               written in Perl called <command>configure.pl</command>. To get 
     421               the command-line options for this script, use one of the 
     422               following (the second being much more detailed):</para> 
     423 
     424               <screen>./configure.pl --help 
     425./configure.pl --manual</screen> 
     426 
     427               <para>To configure your system, you will need to see what 
     428               options all the Autoconf-based configure scripts in VR Juggler 
     429               need. To get this text, enter:</para> 
     430 
     431               <screen>./configure.pl --all-help</screen> 
     432 
     433               <para><important> 
     434                     <para>In order for this to work, the configure script for 
     435                     each of the Juggler modules must be generated. This can 
     436                     be done manually by running <command>autogen.sh</command> 
     437                     in the top-level <filename>juggler</filename> directory. 
     438                     It use is simple:</para> 
     439 
     440                     <screen>./autogen.sh</screen> 
     441 
     442                     <para>This <command>autogen.sh</command> script must be 
     443                     run from the directory where it exists. Do not try to run 
     444                     it from a build directory or any other place in the 
     445                     Juggler source tree. The same holds for the individual 
     446                     <command>autogen.sh</command> scripts in the various 
     447                     modules, should you need to run one individually.</para> 
     448                  </important><command>configure.pl</command> can run in a 
     449               unique <quote>build</quote> directory or in the directory where 
     450               it resides. Here is how we (the Juggler Team) have been using 
     451               it:</para> 
     452 
     453               <orderedlist> 
     454                  <listitem> 
     455                     <para>Make a directory for compiling. There are many good 
     456                     reasons to do this away from the main source tree (though 
     457                     they will not be listed here).</para> 
     458 
     459                     <screen>mkdir build.linux.posix</screen> 
     460 
     461                     <para>This example using an ad hoc naming convention 
     462                     based on operating system and threading subsystem. Other 
     463                     examples could be <filename>build.irix.sproc</filename>, 
     464                     <filename>build.solaris.nspr</filename>, etc.</para> 
     465                  </listitem> 
     466 
     467                  <listitem> 
     468                     <para>Enter the new build directory.</para> 
     469 
     470                     <screen>cd build.linux.posix</screen> 
     471                  </listitem> 
     472 
     473                  <listitem> 
     474                     <para>Configure all the modules making up VR Juggler. 
     475                     This is when you must tell the module configure scripts 
     476                     where all the package dependencies are found.</para> 
     477 
     478                     <screen>../configure.pl --prefix=$HOME/vrjuggler-2.0 --with-java-orb=JDK</screen> 
     479 
     480                     <important> 
     481                        <para>You will probably have to specify the paths to 
     482                        your local CppDOM, GMTL, and Boost installations using 
     483                        the options <option>--with-cppdom</option>, 
     484                        <option>--with-gmtl</option>, and 
     485                        <option>--with-boost</option> unless they are 
     486                        installed in the default location 
     487                        (<filename>/usr/local</filename>). By default, Boost 
     488                        1.31 installs its header files in a subdirectory of 
     489                        <filename>include</filename> called 
     490                        <filename>boost-1_31</filename>. That is, if Boost is 
     491                        installed in 
     492                        <filename>/home/user1/pkgs/boost</filename>, the 
     493                        header files will be in 
     494                        <filename>/home/user1/pkgs/boost/include/boost-1_31</filename>. 
     495                        In this case, you must also specify the option 
     496                        <option>--with-boost-includes=/home/user1/pkgs/boost/include/boost-1_31</option> 
     497                        when running <command>configure.pl</command>.</para> 
     498                     </important> 
     499                  </listitem> 
     500               </orderedlist> 
     501 
     502               <para>By default, the configuration process will configure VR 
     503               Juggler and all of its dependencies. This includes Sonix, which 
     504               is an interesting special case. Sonix can make use of Aaudiere, 
     505               OpenAL, or AudioWorks to add sound to VR Juggler applications. 
     506               If none of those packages is found, Sonix will <quote>stub 
     507               out</quote> its sound APIs. This means that Sonix and the VR 
     508               Juggler Sound Manager can still be used in applications, but no 
     509               audio will be heard at run time. See <xref 
     510               linkend="sonix.compile.section" /> for more information about 
     511               how to configure Sonix to use Audiere, OpenAL, or 
     512               AudioWorks.</para> 
     513 
     514               <para>For example uses of <command>configure.pl</command>, take 
     515               a look at the Wiki page relating to building from CVS (<ulink 
     516               url="http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs">http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromCvs</ulink>). 
     517               It is not a replacement for this document, but it shows how 
     518               some members of the Juggler team configure VR Juggler. It also 
     519               has information on more advanced uses of 
     520               <command>configure.pl</command> that are beyond the scope of 
     521               this document.</para> 
     522            </section> 
     523 
     524            <section> 
     525               <title>Using Locally Installed Software</title> 
     526 
     527               <para>As noted in <xref linkend="source.code.section" />, VR 
     528               Juggler depends on several external software packages. As an 
     529               example, consider the case where the GMTL library is installed 
     530               in <filename>/home/user1/pkgs/GMTL</filename> with the headers 
     531               in <filename>/home/user1/pkgs/GMTL/include</filename>. To use 
     532               this installation, run <command>configure.pl</command> as 
     533               follows:</para> 
     534 
     535               <screen>../configure.pl --with-gmtl=/home/user1/pkgs/GMTL</screen> 
     536 
     537               <para>The <option>--with-gmtl</option> option could of course 
     538               be mixed in with those shown in the previous section.</para> 
     539            </section> 
     540         </section> 
     541 
     542         <section id="compile.vrjuggler.section"> 
     543            <title>Compiling VR Juggler</title> 
     544 
     545            <para>Once the configuration process is complete, the code can be 
     546            compiled. Remember that we require the use of GNU make 3.78 or 
     547            newer.</para> 
     548 
     549            <orderedlist> 
     550               <listitem> 
     551                  <para>Compile the source tree using GNU make.</para> 
     552 
     553                  <screen>gmake build</screen> 
     554               </listitem> 
     555 
     556               <listitem> 
     557                  <para>Once this completes, you will have a full build of VR 
     558                  Juggler. For those who are not interested in developing VR 
     559                  Juggler or its component modules, it is recommended that you 
     560                  install the software and use the installed version for 
     561                  application development. Do this as follows:</para> 
     562 
     563                  <screen>gmake install</screen> 
     564               </listitem> 
     565            </orderedlist> 
     566         </section> 
    287567      </section> 
    288568 
    289       <section> 
    290         <title>Netscape Portable Runtime (NSPR)</title> 
    291  
    292         <para>Our operating system abstraction, VPR, can make use of NSPR for 
    293         operating system primitives. On some platforms (IRIX, FreeBSD, Linux, 
    294         Mac OS X), the use of NSPR is strictly optional. On others (Win32, 
    295         HP-UX, and Solaris), it is required. Based on your local system, you 
    296         should decide whether you need NSPR. Binary versions of NSPR can be 
    297         downloaded from <ulink 
    298         url="ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases">ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases</ulink>. 
    299         At this time, we recommend the use of version 4.2 or newer.</para> 
    300       </section> 
    301  
    302       <section> 
    303         <title>Java Developer Kit (also called the J2SE SDK)</title> 
    304  
    305         <para>We make use of the Java programming language in addition to C++. 
    306         Java is used exclusively for GUIs such as Tweek and VRJConfig (which 
    307         is a JavaBean that is loaded into Tweek). To compile the Java code, a 
    308         JDK is necessary. We currently require version 1.4 or newer. The Java