-
Notifications
You must be signed in to change notification settings - Fork 9
/
INSTALL.html
378 lines (378 loc) · 50.2 KB
/
INSTALL.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Building and Installing the Juggler Project (Version 3.1)</title><link rel="stylesheet" type="text/css" href="base_style.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" title="Building and Installing the Juggler Project (Version 3.1)"><div class="titlepage"><div><div><h2 class="title"><a name="d0e1"></a>Building and Installing the Juggler Project (Version 3.1)</h2></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 Note for Windows Users</a></span></dt><dt><span class="section"><a href="#d0e40">Important Notes for IRIX Users</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e124">Build Tools</a></span></dt><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 Subversion</a></span></dt><dt><span class="section"><a href="#d0e250">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="#d0e332">Important Note Regarding Compiling</a></span></dt><dt><span class="section"><a href="#d0e343">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" title="Introduction"><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 3.1 of the Juggler
Project. This is the code that will become VR Juggler 3.2, and it is the
code that is used to create the VR Juggler 3.1 pre-releases. Please be
aware that this code represents a work in progress, and if you acquired it
directly from Subversion rather than using a pre-packaged source code
snapshot, the code may have bugs affecting compilation and
execution.</p><p>This document explains how to build the modules of the Juggler
Project from the source code. We begin by explaining some issues related
to specific operating systems. We then explain how to get the source code
from our Subversion repository. (Those users who downloaded a pre-packaged
source release can skip ahead to <a class="xref" href="#using.configure.pl" title="Using configure.pl">Using <span class="command"><strong>configure.pl</strong></span></a>).
We conclude with instructions on how to build VR Juggler and its
individual components.</p><p>Before reading further, we recommend that readers take a look at the
Wiki page relating to building from source (<a class="ulink" href="http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromSvn" target="_top">http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromSvn</a>).
It is a <span class="emphasis"><em>supplement</em></span> to this document containing tips
and reminders for those users building the SVN version of VR Juggler. It
is not a replacement for this document, nor can it stand on its own as
build instructions. You are reading the definitive build instructions; the
Wiki page merely provides informal, extra information.</p><div class="section" title="Important Note for Windows Users"><div class="titlepage"><div><div><h3 class="title"><a name="d0e32"></a>Important Note for Windows Users</h3></div></div></div><p>VR Juggler 3.0 and newer use a lot of C++ features not supported
by Visual Studio 6.0. Microsoft <a class="ulink" href="http://support.microsoft.com/default.aspx?scid=http://support.microsoft.com:80/support/kb/articles/q243/4/51.asp&NoWebContent=1" target="_top">acknowledges</a>
the issues concerning noncompliance to the C++ Standard with Visual
Studio 6.0. Furthermore, workarounds for Visual C++ 7.0 (.NET 2002) and
7.1 (.NET 2003) bugs have been removed. Therefore, we require the use of
Visual Studio 9.0 (2008) or newer to compile the source code.</p></div><div class="section" title="Important Notes for IRIX Users"><div class="titlepage"><div><div><h3 class="title"><a name="d0e40"></a>Important Notes for IRIX Users</h3></div></div></div><p>Despite our best efforts, there are some issues related to
compiling the Juggler Project on IRIX. We introduce them in this section
and explain how to work around them.</p><div class="section" title="Perl Version"><div class="titlepage"><div><div><h4 class="title"><a name="d0e45"></a>Perl Version</h4></div></div></div><p>There are many Perl scripts used as part of getting,
configuring, and building the Juggler Suite of tools. In particular,
two scripts required for compiling need Perl 5.005 or newer. The
version of Perl that ships with IRIX 6.5 is very old (circa 1997) and
does not work with many Perl scripts we have written. SGI provides a
much newer version of Perl (5.6.1) with their freeware tools (<a class="ulink" href="http://freeware.sgi.com/" target="_top">http://freeware.sgi.com/</a>). It
will be necessary to install that version for our scripts to work.
This version is typically installed as
<code class="filename">/usr/freeware/bin/perl</code>.</p><p>Once you have a modern Perl installed, you can run various Perl
scripts as follows:</p><pre class="screen">/usr/freeware/bin/perl <script-name></pre><p>The above will be required any time a Perl script fails with 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.
BEGIN failed--compilation aborted at ./configure.pl line 35.</pre><p>Furthermore, it is highly recommended that the
<code class="option">--with-perl</code> argument be passed to
<span class="command"><strong>configure.pl</strong></span>. This argument gives all the
Autoconf-based configure scripts a hint about where the preferred
version of Perl lives. If using
<code class="filename">/usr/freeware/bin/perl</code> to run
<span class="command"><strong>configure.pl</strong></span>, we recommend that the
<span class="command"><strong>configure.pl</strong></span> command line appear similar to the
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
<span class="emphasis"><em>directory</em></span> where the <span class="command"><strong>perl</strong></span>
executable can be found. The configure scripts will add this directory
to the front of the search path when trying to find a suitable
<span class="command"><strong>perl</strong></span> executable. Once it is found, all the Perl
scripts used for configuration, compilation, and installation will use
that executable.</p><p>To simplify command execution somewhat, it can help to have
<code class="filename">/usr/freeware/bin</code> (or whatever path is
appropriate) in your path before <code class="filename">/bin</code> or
<code class="filename">/usr/bin</code> or any of the other myriad directories
where Perl might exist on IRIX. In such a situation, none of the above
extra steps should be necessary. The correct version of Perl will be
found simply by virtue of it being early in your path.</p></div><div class="section" title="MIPSpro Compiler Version"><div class="titlepage"><div><div><h4 class="title"><a name="d0e108"></a>MIPSpro Compiler Version</h4></div></div></div><p>Reports have been made on the VR Juggler mailing list regarding
compile failures (including segmentation faults within the compiler)
occur when using the MIPSpro Compilers Version 7.3.1.1m. We have found
upgrading to Version 7.3.1.3m (or newer) fixes the problems.</p><p>A new feature of VR Juggler 1.1 and newer is support for GCC on
IRIX. Users who do not have MIPSpro or cannot upgrade can compile and
run VR Juggler (without OpenGL Performer support) using the version of
GCC distributed by SGI. It can be downloaded from <a class="ulink" href="http://freeware.sgi.com/index-by-alpha.html" target="_top">http://freeware.sgi.com/index-by-alpha.html</a>
for free. When configuring the source with
<span class="command"><strong>configure.pl</strong></span> (described later), use the option
<code class="option">--with-gcc</code>.</p></div></div></div><div class="section" title="Build Tools"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e124"></a>Build Tools</h2></div></div></div><p>When building on non-Windows platforms, the GNU Autotools are
required. This means that, in addition to a C++ compiler (e.g., GCC), the
following packages must be installed in order to compile VR
Juggler:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>GNU Make 3.79 or newer</p></li><li class="listitem"><p>GNU Autoconf 2.53 or newer</p></li><li class="listitem"><p>GNU Automake 1.8 or newer</p></li></ul></div><p>Additionally, VR Juggler 2.1 and beyond require the <a class="ulink" href="https://realityforge.vrsource.org/view/FlagPoll/" target="_top">Flagpoll</a>
software tool. As of this writing, the minimum required version is 0.8.1.
It is recommended that all of these tools be installed in either the
<code class="filename">/usr</code> or the <code class="filename">/usr/local</code> directory
trees so that search paths do not have to be extended.</p></div><div class="section" title="Getting the Source Code and the Dependencies"><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
code and the dependencies required to build Juggler. There are two ways to
get the source code: from a pre-packaged source release archive or from
the Subversion repository on Google Code. If you got the code from a
pre-packaged source archive, that code is a complete
<span class="quote">“<span class="quote">snapshot</span>”</span> of the Subversion repository at the time of
release. It contains all dependencies that would otherwise have been
acquired using Subversion. It <span class="emphasis"><em>does not</em></span> contain binary
dependencies that must be downloaded separately (such as NSPR, the Java
Developer Kit, a C++ compiler, etc.).</p><p>The current list of <span class="emphasis"><em>required</em></span> software packages
is as follows:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>CppDOM (<a class="ulink" href="http://www.sourceforge.net/projects/xml-cppdom/" target="_top">http://www.sf.net/projects/xml-cppdom/</a>):
A lightweight, easy-to-use XML parser written in C++. CppDOM must be
compiled and installed for use with VR Juggler.</p></li><li class="listitem"><p>Boost (<a class="ulink" href="http://www.boost.org/" target="_top">http://www.boost.org/</a>): A C++
library providing many powerful utility classes and libraries. Boost
must be compiled and installed for use with VR Juggler.</p></li><li class="listitem"><p>GMTL (<a class="ulink" href="http://ggt.sourceforge.net/" target="_top">http://ggt.sf.net/</a>): A
generic math library that makes use of C++ templates and STL
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>
packages:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>NSPR (<a class="ulink" href="http://www.mozilla.org/projects/nspr/" target="_top">http://www.mozilla.org/projects/nspr/</a>):
The Netscape Portable Runtime, which can be used by VPR for threading
and sockets (required on Solaris).</p></li><li class="listitem"><p>Java Developer Kit (<a class="ulink" href="http://java.sun.com/" target="_top">http://java.sun.com/</a>): The J2SE SDK
(or JDK) is used to compile all the Java code used in the Juggler
Project. Without it, none of the Java code can be built. We require
version 1.4 or newer. The Java Standard Edition (J2SE) can be
downloaded from <a class="ulink" href="http://java.sun.com/j2se/" target="_top">http://java.sun.com/j2se/</a>.</p></li><li class="listitem"><p>omniORB (<a class="ulink" href="http://www.jdom.org/" target="_top">http://omniorb.sourceforge.net/</a>): A
C++ implementation of CORBA 2.3, required for the Tweek C++
API.</p></li><li class="listitem"><p>Doozer (<a class="ulink" href="http://sourceforge.net/projects/doozer" target="_top">http://sourceforge.net/projects/doozer</a>):
A collection of makefile stubs written for use with GNU Make and
intended for simplifying the creation of cross-platform VR Juggler
application builds. Version 2.1.4 or newer is needed for building VR
Juggler sample applications.</p></li></ul></div><p>The following are fully optional packages that are primarily of
interest only to people doing development on the Juggler Suite
itself:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>JUnit (<a class="ulink" href="http://www.junit.org/" target="_top">http://www.junit.org/</a>): A unit
testing framework for Java.</p></li><li class="listitem"><p>CppUnit (<a class="ulink" href="http://cppunit.sourceforge.net/" target="_top">http://cppunit.sourceforge.net/</a>):
A unit testing framework for C++. The Juggler C++ test suties make use
of extensions to CppUnit. An extended version of the CppUnit source
that includes these extensions can be acquired from the Juggler
Subversion repository in the module <code class="literal">cppunit</code>. Refer
to <a class="xref" href="#section.cvs.access" title="How to Get the Juggler Suite from Subversion">How to Get the Juggler Suite from Subversion</a> for instructions about
accessing the Juggler Subversion repository.</p></li></ul></div><p>The third-party dependencies must be downloaded from the sites
listed above and installed manually. You may also have to compile one or
more of the packages if binary distributions are not available. Which
packages you download depends on what you already have installed. Note
carefully which packages are needed based on the software you have
installed and what versions of tools (such as the JDK) that you
download.</p><div class="section" title="How to Get the Juggler Suite from Subversion"><div class="titlepage"><div><div><h3 class="title"><a name="section.cvs.access"></a>How to Get the Juggler Suite from Subversion</h3></div></div></div><p>You can optionally get the Juggler Project as a source code
tarball from the website (<a class="ulink" href="http://www.vrjuggler.org/" target="_top">http://www.vrjuggler.org/</a>) or
you can execute the following command from a shell to get the code from
our Subversion repository:</p><pre class="screen">svn co http://vrjuggler.googlecode.com/svn/juggler/trunk juggler
</pre></div><div class="section" title="Downloading Third-Party Dependencies"><div class="titlepage"><div><div><h3 class="title"><a name="d0e250"></a>Downloading Third-Party Dependencies</h3></div></div></div><p>In addition to source the dependencies acquired through
Subversion, there are some third-party dependencies that must be
installed separately. Remember that no Java code in VR Juggler can be
used without the JDK and a working Java version of CORBA.</p><div class="section" title="Boost"><div class="titlepage"><div><div><h4 class="title"><a name="d0e255"></a>Boost</h4></div></div></div><p>The minimum required version of Boost, as of this writing, is
1.31.0. The Boost source can be downloaded from <a class="ulink" href="http://www.sf.net/projects/boost/" target="_top">http://www.sf.net/projects/boost/</a>.
To compile and install Boost, refer to its installation documentation
(<a class="ulink" href="http://www.boost.org/more/getting_started.html#Build_Install" target="_top">http://www.boost.org/more/getting_started.html#Build_Install</a>).
Note that you need the command <span class="command"><strong>bjam</strong></span> (referred to as
<span class="quote">“<span class="quote">boost-jam</span>”</span> on the Boost download page) to build
Boost.</p><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Mac OS X users should compile the Boost libraries using the
<span class="quote">“<span class="quote">darwin</span>”</span> toolset.</p></div></div><div class="section" title="CppDOM"><div class="titlepage"><div><div><h4 class="title"><a name="d0e278"></a>CppDOM</h4></div></div></div><p>For XML processing, we use CppDOM 0.6.5 or newer. The source and
binary distributions for some platforms can be downloaded from <a class="ulink" href="http://www.sf.net/projects/xml-cppdom/" target="_top">http://www.sf.net/projects/xml-cppdom/</a>.
If a binary version is not available for your operating system you
must compile and install CppDOM yourself. Note that you need SCons
(<a class="ulink" href="http://scons.sourceforge.net/" target="_top">http://scons.sourceforge.net/</a>)
to build and install CppDOM.</p></div><div class="section" title="GMTL"><div class="titlepage"><div><div><h4 class="title"><a name="d0e289"></a>GMTL</h4></div></div></div><p>For high-level mathematical operations, we use GMTL 0.4.12 or
newer. The source distribution can be downloaded from <a class="ulink" href="http://www.sf.net/projects/ggt/" target="_top">http://www.sf.net/projects/ggt/</a>.
Note that you need SCons (<a class="ulink" href="http://scons.sourceforge.net/" target="_top">http://scons.sourceforge.net/</a>)
to build and install GMTL.</p></div><div class="section" title="Netscape Portable Runtime (NSPR)"><div class="titlepage"><div><div><h4 class="title"><a name="d0e300"></a>Netscape Portable Runtime (NSPR)</h4></div></div></div><p>Our operating system abstraction, VPR, can make use of NSPR for
operating system primitives. On some platforms (IRIX, FreeBSD, Linux,
Mac OS X), the use of NSPR is strictly optional. On others (HP-UX and
Solaris), it is required. Based on your local system, you should
decide whether you need NSPR. Binary versions of NSPR can be
downloaded from <a class="ulink" href="ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases" target="_top">ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases</a>.
At this time, we recommend the use of version 4.2 or newer.</p></div><div class="section" title="Java Developer Kit (also called the J2SE SDK)"><div class="titlepage"><div><div><h4 class="title"><a name="d0e308"></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++.
Java is used exclusively for GUIs such as Tweek and VRJConfig (which
is a JavaBean that is loaded into Tweek). To compile the Java code, a
JDK is necessary. We currently require version 1.4 or newer. The Java
Standard Edition can be downloaded from <a class="ulink" href="http://java.sun.com/j2se/" target="_top">http://java.sun.com/j2se/</a>.
More information can be found at <a class="ulink" href="http://java.sun.com/" target="_top">http://java.sun.com/</a>.</p></div><div class="section" title="omniORB"><div class="titlepage"><div><div><h4 class="title"><a name="d0e319"></a>omniORB</h4></div></div></div><p>omniORB is a C++ implementation of CORBA 2.3. It is required in
order to compile the Tweek C++ API. At this time, the Tweek C++ API is
not required for VR Juggler, but this situation will change in the
near future. At this time, we primarily use omniORB 4.0.x; omniORB 3.0
is not supported. omniORB can be downloaded from <a class="ulink" href="http://omniorb.sourceforge.net/" target="_top">http://omniorb.sourceforge.net/</a>.</p></div></div></div><div class="section" title="Compiling"><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
focus on VR Juggler as a whole, but information about some of the
individual components is provided later.</p><div class="section" title="Important Note Regarding Compiling"><div class="titlepage"><div><div><h3 class="title"><a name="d0e332"></a>Important Note Regarding Compiling</h3></div></div></div><p>You have downloaded <span class="emphasis"><em>developmental</em></span> code. It
may not be stable, and it may not even compile. Compiling VR Juggler
itself can be a little complicated for anyone who does not have some
background in using Subversion, Autoconf, C++, and
<span class="command"><strong>make</strong></span> or Visual Studio.</p></div><div class="section" title="Compiling the Juggler Suite of Tools"><div class="titlepage"><div><div><h3 class="title"><a name="d0e343"></a>Compiling the Juggler Suite of Tools</h3></div></div></div><p>This section explains how to get, configure, and compile all of
the tools that make up VR Juggler. Each tool compiles to its own library
and can be installed individually. (Refer to the
<code class="filename">README</code> file in this directory for more information
about the specific modules.)</p><p>To build VR Juggler on Windows, you must use the Visual Studio
solution. After getting the dependencies needed to compile VR Juggler
(see the next section), refer to the <a class="ulink" href="README-WINDOWS.html" target="_top">README-WINDOWS.html</a> file located in
this directory. Do not bother to the rest of this document.</p><div class="section" title="Per-Module Dependencies"><div class="titlepage"><div><div><h4 class="title"><a name="d0e356"></a>Per-Module Dependencies</h4></div></div></div><p>Here, we provide per-module dependency information. Given that
the dependencies for any single module are met, the modules may be
reused effectively outside the scope of immersive VR application
development. Below, we list the <span class="emphasis"><em>minimum</em></span> required
version for each dependency, and where appropriate, we note which
dependencies are optional.</p><div class="section" title="VPR"><div class="titlepage"><div><div><h5 class="title"><a name="d0e364"></a>VPR</h5></div></div></div><p>VPR provides a cross-platform, object-oriented operating
system abstraction. It is the foundation for all other Juggler
modules.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>CppDOM 0.6.6</p></li><li class="listitem"><p>Boost headers and Boost.Filesystem 1.31.0</p></li><li class="listitem"><p>NSPR (Solaris and HP-UX only) 4.4</p></li></ul></div></div><div class="section" title="Tweek C++ API"><div class="titlepage"><div><div><h5 class="title"><a name="d0e379"></a>Tweek C++ API</h5></div></div></div><p>Tweek implements a distributed model/view/controller system on
top of CORBA. The Tweek C++ API provides the C++ component of that
system. Code written on top of the Tweek C++ API normally acts as
the model piece of the distributed model/view/controller
system.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>VPR</p></li><li class="listitem"><p>omniORB 4.0</p></li></ul></div></div><div class="section" title="Tweek Java API"><div class="titlepage"><div><div><h5 class="title"><a name="d0e391"></a>Tweek Java API</h5></div></div></div><p>Tweek implements a distributed model/view/controller system on
top of CORBA. The Tweek Java API provides the Java component of that
system. The main part of the Tweek Java API is the Tweek JavaBean
Loader, a GUI application that loads Tweek Beans that normally
function as the view and controller pieces of the distributed
module/view/controller system.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>J2SE SDK 1.4</p></li><li class="listitem"><p>JDOM (included with Juggler source)</p></li><li class="listitem"><p>Ant (included with Juggler source)</p></li><li class="listitem"><p>JacORB IDL-to-Java compiler (included with Juggler
source)</p></li></ul></div></div><div class="section" title="Tweek Python API"><div class="titlepage"><div><div><h5 class="title"><a name="d0e409"></a>Tweek Python API</h5></div></div></div><p>Tweek implements a distributed model/view/controller system on
top of CORBA. The Tweek Python API provides the Python component of
that system. The main part of the Tweek Java API is the
<span class="emphasis"><em>unfinished</em></span> TweekQt GUI, an application that
loads Python modules that normally function as the view and
controller pieces of the distributed module/view/controller
system.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Python 2.3</p></li><li class="listitem"><p>omniORBpy 2.0</p></li></ul></div></div><div class="section" title="JCCL C++ API"><div class="titlepage"><div><div><h5 class="title"><a name="d0e424"></a>JCCL C++ API</h5></div></div></div><p>The JCCL C++ API provides an interface for loading XML-based
configurations. It includes the run-time reconfiguration feature of
Juggler.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>VPR</p></li></ul></div></div><div class="section" title="JCCL Java API"><div class="titlepage"><div><div><h5 class="title"><a name="d0e433"></a>JCCL Java API</h5></div></div></div><p>The JCCL Java API provides a programming interface for editing
Juggler configuration files and config definition files as well as
JavaBeans for editing these files using a graphical
interface.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Tweek Java API</p></li><li class="listitem"><p>TableLayout package (included with Juggler source)</p></li></ul></div></div><div class="section" title="JCCL Remote Run-Time Reconfiguration Plug-in (C++)"><div class="titlepage"><div><div><h5 class="title"><a name="d0e445"></a>JCCL Remote Run-Time Reconfiguration Plug-in (C++)</h5></div></div></div><p>The C++ JCCL Remote Run-Time Reconfiguration Plug-in is an
optional extension to the JCCL Config Manager for allowing remote
manipulation of a Juggler configuration at run time based on
Tweek.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Tweek C++ API</p></li></ul></div></div><div class="section" title="JCCL Remote Run-Time Reconfiguration Plug-in (Java)"><div class="titlepage"><div><div><h5 class="title"><a name="d0e454"></a>JCCL Remote Run-Time Reconfiguration Plug-in (Java)</h5></div></div></div><p>The Java JCCL Remote Run-Time Reconfiguration Plug-in is an
optional extension that provides the features needed for a
Java-based editor to communicate with the C++ Remote Run-Time
Reconfiguration Plug-in to edit Juggler configurations live.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Tweek Java API</p></li></ul></div></div><div class="section" title="Sonix"><div class="titlepage"><div><div><h5 class="title"><a name="d0e463"></a>Sonix</h5></div></div></div><p>Sonix is an abstraction layer for positional sound software.
Sonix itself cannot play audio, but it includes plug-ins based on
popular interfaces for playing audio. Each plug-in depends on a
specific audio software library.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>VPR</p></li><li class="listitem"><p>GMTL 0.4.12</p></li></ul></div><div class="section" title="Sonix OpenAL Plug-in"><div class="titlepage"><div><div><h6 class="title"><a name="d0e475"></a>Sonix OpenAL Plug-in</h6></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Sonix</p></li><li class="listitem"><p>OpenAL</p></li><li class="listitem"><p>Free ALUT</p></li></ul></div></div><div class="section" title="Sonix Audiere Plug-in"><div class="titlepage"><div><div><h6 class="title"><a name="d0e488"></a>Sonix Audiere Plug-in</h6></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Sonix</p></li><li class="listitem"><p>Audiere</p></li></ul></div></div></div><div class="section" title="Gadgeteer"><div class="titlepage"><div><div><h5 class="title"><a name="d0e498"></a>Gadgeteer</h5></div></div></div><p>Gadgeteer handles all input devices that can be used by VR
Juggler applications.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>VPR</p></li><li class="listitem"><p>JCCL</p></li><li class="listitem"><p>GMTL 0.4.12</p></li><li class="listitem"><p>X Window System (non-Windows platforms)</p></li></ul></div></div><div class="section" title="Gadgeteer Device Driver Plug-ins"><div class="titlepage"><div><div><h5 class="title"><a name="d0e516"></a>Gadgeteer Device Driver Plug-ins</h5></div></div></div><p>The device driver plug-ins for Gadgeteer are independent
components that are discovered and used at run time based on the
application configuration. Drivers with dependencies are
optional.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Gadgeteer</p></li><li class="listitem"><p>VRPN 07.03 for the VRPN driver plug-in</p></li><li class="listitem"><p>TrackD API 4 for the TrackD API driver plug-in</p></li><li class="listitem"><p>Microsoft Speech API for the MS Speech API driver
plug-in</p></li></ul></div></div><div class="section" title="Gadgeteer Cluster Plug-ins"><div class="titlepage"><div><div><h5 class="title"><a name="d0e534"></a>Gadgeteer Cluster Plug-ins</h5></div></div></div><p>The cluster plug-ins extend the functionality of the
clustering infrastructure built into Gadgeteer.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Gadgeteer</p></li></ul></div></div><div class="section" title="VR Juggler"><div class="titlepage"><div><div><h5 class="title"><a name="d0e543"></a>VR Juggler</h5></div></div></div><p>The VR Juggler module is the unifying piece that pulls all the
other Juggler modules together. It provides a virtual platform for
VR application development. Real-time rendering is controlled by
Draw Managers. The OpenGL Performer Draw Manager is optional.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Gadgeteer</p></li><li class="listitem"><p>Sonix</p></li><li class="listitem"><p>OpenGL</p></li><li class="listitem"><p>OpenGL Performer for the <span class="emphasis"><em>optional</em></span>
OpenGL Performer Draw Manager</p></li></ul></div></div><div class="section" title="VR Juggler Run-Time Performance Monitoring Plug-in (C++)"><div class="titlepage"><div><div><h5 class="title"><a name="d0e564"></a>VR Juggler Run-Time Performance Monitoring Plug-in
(C++)</h5></div></div></div><p>The C++ VR Juggler Run-Time Performance Monitoring Plug-in
provides an optional extension to VR Juggler for remote
visualization of performance metrics that are captured while running
a VR Juggler application. Communication is performed using the Tweek
C++ API on top of CORBA.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Tweek C++ API</p></li><li class="listitem"><p>VR Juggler</p></li></ul></div></div><div class="section" title="VR Juggler Run-Time Performance Monitoring Plug-in (Java)"><div class="titlepage"><div><div><h5 class="title"><a name="d0e576"></a>VR Juggler Run-Time Performance Monitoring Plug-in
(Java)</h5></div></div></div><p>The Java VR Juggler Run-Time Performance Monitoring Plug-in is
an optional extension that provides the features needed for
Java-based visualization of performance data collected while a VR
Juggler application is running. This is another JavaBean handled by
the Tweek JavaBean Loader, and it uses CORBA to communicate with the
C++ VR Juggler Run-Time Performance Monitoring Plug-in.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>JCCL Java API</p></li><li class="listitem"><p>JFreeChart (included with Juggler source)</p></li></ul></div></div><div class="section" title="VRJConfig"><div class="titlepage"><div><div><h5 class="title"><a name="d0e588"></a>VRJConfig</h5></div></div></div><p>VRJConfig is the graphical editor for Juggler configurations.
It is a JavaBean loaded by the Tweek JavaBean Loader, and it makes
use of the editor Beans provided by the JCCL Java API.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>JCCL Java API</p></li><li class="listitem"><p>JGraph (included with Juggler source)</p></li></ul></div></div></div><div class="section" title="Preparing Flagpoll"><div class="titlepage"><div><div><h4 class="title"><a name="d0e600"></a>Preparing Flagpoll</h4></div></div></div><p>The Flagpoll software has a default search path where it looks
for <code class="filename">.pc</code> and <code class="filename">.fpc</code> package
metadata files. It searchs <code class="filename">/usr/lib/pkgconfig</code>,
<code class="filename">/usr/lib/flagpoll</code>,
<code class="filename">/usr/lib64/pkgconfig</code>,
<code class="filename">/usr/lib64/flagpoll</code>,
<code class="filename">/usr/share/pkgconfig</code>, and
<code class="filename">/usr/share/flagpoll</code>. If
<code class="envar">LD_LIBRARY_PATH</code> (or <code class="envar">DYLD_LIBRARY_PATH</code> on
Mac OS X) is set, Flagpoll will search each of the directories in that
environment variable for subdirectories named
<code class="filename">pkgconfig</code> and <code class="filename">flagpoll</code>.
Users can extend this search path further by setting the environment
variables <code class="envar">PKG_CONFIG_PATH</code> and/or
<code class="envar">FLAGPOLL_PATH</code> to list more directories for Flagpoll to
search. (All of the environment variables mentioned here have as their
value a colon-separated list of directories.)</p><p>The Juggler build relies upon Flagpoll for getting compiler and
linker flags for the following packages:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>CppDOM</p></li><li class="listitem"><p>GMTL</p></li><li class="listitem"><p>omniORB</p></li></ul></div><p>Therefore, it is critical that Flagpoll be able to find the
package metadata file for each. For CppDOM, the
<code class="filename">.fpc</code> file is under the CppDOM
<code class="filename">lib</code> (or <code class="filename">lib64</code>) directory in
the <code class="filename">flagpoll</code> subdirectory. For omniORB, the
<code class="filename">.pc</code> files (there are several) are under the
omniORB <code class="filename">lib</code> (or <code class="filename">lib64</code>)
directory in the <code class="filename">pkgconfig</code> subdirectory. Finally,
for GMTL, the <code class="filename">.pc</code> file is under the GMTL
<code class="filename">share</code> directory in the
<code class="filename">pkgconfig</code> subdirectory. If these packages are
installed in <code class="filename">/usr</code>, then Flagpoll will be able to
find the information it needs with no extra work on the part of the
user.</p><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>If Flagpoll is not installed in a place where the
<span class="command"><strong>aclocal</strong></span> tool searches for
<code class="filename">.m4</code> files by default, then it is necessary to
extend <span class="command"><strong>aclocal</strong></span>'s search path. This is done by
setting the environment variable <code class="envar">ACLOCAL_FLAGS</code> to
<span class="quote">“<span class="quote"><code class="literal">-I .../share/alocal</code></span>”</span> where
<span class="quote">“<span class="quote"><code class="literal">...</code></span>”</span> is the path to the directory
tree where Flagpoll is installed.</p></div></div><div class="section" title="Configuring the Juggler Build"><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
configured. The Juggler Suite makes use of the well-known, widely used
GNU tools Autoconf and GNU Make. We provide a wrapper script written
in Perl called <span class="command"><strong>configure.pl</strong></span> that gets the process
started.</p><p>The Juggler build is highly automated. The trickiest part is
telling the build where to find the third-party dependencies. This
part can be simplified, however, by installing the third-party
dependencies in the default location where the search will be
performed. In most cases, this is <code class="filename">/usr/local</code>, but
in others it is <code class="filename">/usr</code>. The default search location
is determined by whether the dependency is considered to be a
fundamental part of the operating system installation (such as OpenGL)
or if it is an <span class="quote">“<span class="quote">add-on</span>”</span> package (such as Boost, GMTL,
CppDOM, or omniORB).</p><div class="sidebar"><div class="titlepage"></div><p>The distinction between <code class="filename">/usr/local</code> and
<code class="filename">/usr</code> is complicated by the fact that most Linux
distributions have <span class="emphasis"><em>everything</em></span> installed in
<code class="filename">/usr</code>. While Linux may be popular, it should not
(yet) be considered a model example of how to do things. In
traditional UN*X distributions (BSD and System V),
<code class="filename">/usr</code> is only used for the fundamental operating
system pieces; <code class="filename">/usr/local</code> is used for extra
bits. The Juggler build is based on these assumptions. Furthermore,
most open source software packages (e.g., Boost, omniORB, Perl,
Python) default to installing themselves in
<code class="filename">/usr/local</code>, which suggests that the authors of
those tools generally expect their software to be in
<code class="filename">/usr/local</code>.</p></div><div class="section" title="Using configure.pl"><div class="titlepage"><div><div><h5 class="title"><a name="using.configure.pl"></a>Using <span class="command"><strong>configure.pl</strong></span></h5></div></div></div><p>In the base <code class="filename">juggler</code> source directory, we
have a <span class="quote">“<span class="quote">global</span>”</span> configure script written in Perl called
<span class="command"><strong>configure.pl</strong></span>. To get the command-line options for
this script, use one of the following (the second being much more
detailed):</p><pre class="screen">./configure.pl --help
./configure.pl --manual</pre><p>To configure your system, you will need to see what options
all the Autoconf-based configure scripts in VR Juggler need. To get
this text, enter:</p><pre class="screen">./configure.pl --all-help</pre><div class="important" title="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
of the Juggler modules must be generated. This can be done
manually by running <span class="command"><strong>autogen.sh</strong></span> in the
top-level <code class="filename">juggler</code> directory. It use is
simple:</p><pre class="screen">./autogen.sh</pre><p>This <span class="command"><strong>autogen.sh</strong></span> script must be run from
the directory where it exists. Do not try to run it from a build
directory or any other place in the Juggler source tree. The
same holds for the individual <span class="command"><strong>autogen.sh</strong></span>
scripts in the various modules, should you need to run one
individually.</p></div><p><span class="command"><strong>configure.pl</strong></span> can run in a unique
<span class="quote">“<span class="quote">build</span>”</span> directory or in the directory where it resides.
Here is how we (the Juggler Team) have been using it:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Make a directory for compiling. There are many good
reasons to do this away from the main source tree (though they
will not be listed here).</p><pre class="screen">mkdir build.linux.posix</pre><p>This example using an ad hoc naming convention based on
operating system and threading subsystem. Other examples could
be <code class="filename">build.linux.posix</code>,
<code class="filename">build.solaris.nspr</code>, etc.</p></li><li class="listitem"><p>Enter the new build directory.</p><pre class="screen">cd build.linux.posix</pre></li><li class="listitem"><p>Configure all the modules making up VR Juggler. This is
when you must tell the module configure scripts where all the
package dependencies are found.</p><pre class="screen">../configure.pl --prefix=$HOME/vrjuggler-3.1 --with-java-orb=JDK</pre><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>You will probably have to specify the path to your local
Boost installation using the option
<code class="option">--with-boost</code> unless it is installed in the
default location (<code class="filename">/usr/local</code>). By
default, Boost 1.31 and newer install the Boost header files
in a subdirectory of <code class="filename">include</code> called
<code class="filename">boost-VERSION</code> (where
<code class="filename">VERSION</code> is the Boost version number with
underscores instead of periods). That is, if Boost 1.34 is
installed in <code class="filename">/home/user1/pkgs/boost</code>, the
header files will be in
<code class="filename">/home/user1/pkgs/boost/include/boost-1_34</code>.
In this case, you must also specify the option
<code class="option">--with-boost-includes=/home/user1/pkgs/boost/include/boost-1_34</code>
when running <span class="command"><strong>configure.pl</strong></span>.</p></div></li></ol></div><p>By default, the configuration process will configure VR
Juggler and all of its dependencies. This includes Sonix, which is
an interesting special case. Sonix can make use of Audiere or OpenAL
to add sound to VR Juggler applications. If none of those packages
is found, Sonix will <span class="quote">“<span class="quote">stub out</span>”</span> its sound APIs. This
means that Sonix and the VR Juggler Sound Manager can still be used
in applications, but no audio will be heard at run time. See <a class="xref" href="#sonix.compile.section" title="Sonix">Sonix</a> for more information about how to
configure Sonix to use Audiere or OpenAL.</p><p>For example uses of <span class="command"><strong>configure.pl</strong></span>, take a
look at the Wiki page relating to building from source (<a class="ulink" href="http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromSvn" target="_top">http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromSvn</a>).
It is not a replacement for this document, but it shows how some
members of the Juggler team configure VR Juggler. It also has
information on more advanced uses of <span class="command"><strong>configure.pl</strong></span>
that are beyond the scope of this document.</p></div><div class="section" title="Using Locally Installed Software"><div class="titlepage"><div><div><h5 class="title"><a name="d0e886"></a>Using Locally Installed Software</h5></div></div></div><p>As noted in <a class="xref" href="#source.code.section" title="Getting the Source Code and the Dependencies">Getting the Source Code and the Dependencies</a>, VR Juggler
depends on several external software packages. As an example,
consider the case where the Boost libraries are installed in
<code class="filename">/home/user1/pkgs/boost</code> with the headers in
<code class="filename">/home/user1/pkgs/boost/include</code>. To use this
installation, run <span class="command"><strong>configure.pl</strong></span> as follows:</p><pre class="screen">../configure.pl --with-boost=/home/user1/pkgs/boost</pre></div></div><div class="section" title="Compiling VR Juggler"><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
compiled. Remember that we require the use of GNU make 3.78 or
newer.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Compile the source tree using GNU make.</p><pre class="screen">gmake build</pre></li><li class="listitem"><p>Once this completes, you will have a full build of VR
Juggler. For those who are not interested in developing VR Juggler
or its component modules, it is recommended that you install the
software and use the installed version for application
development. Do this as follows:</p><pre class="screen">gmake install</pre></li></ol></div></div></div><div class="section" title="Tips for Compiling Individual Tools in the Juggler Suite"><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
tools in the Juggler Suite are compiled correctly. For the most part,
this duplicates information that can be found on the Wiki page relating
to building from source (<a class="ulink" href="http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromSvn" target="_top">http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromSvn</a>).</p><div class="section" title="Sonix"><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 class="ulink" href="http://www.openal.org/" target="_top">www.openal.org</a>) or Audiere
(<a class="ulink" href="http://audiere.sf.net/" target="_top">audiere.sf.net</a>). At least
one of these packages must be installed for use by Sonix in order to
hear sounds in VR Juggler applications. Once you have all the
necessary source code and third-party package installations, add one
or more of the following options to your
<span class="command"><strong>configure.pl</strong></span> command line to enable the appropriate
audio subsystem:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="option">--enable-openal
--with-openal=<OPENAL_PATH></code>: Enable the use of
OpenAL and tell the build where OpenAL is installed. The default
search path is <code class="filename">/usr/local</code>.</p></li><li class="listitem"><p><code class="option">--enable-audiere
--with-audiere=<AUDIERE_PATH></code>: Enable the use of
Audiere and tell the build where Audiere is installed. The default
search path is <code class="filename">/usr/local</code>.</p></li></ul></div></div><div class="section" title="Tweek"><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.
Currently, we primarily use omniORB 4.0. Visit the <a class="ulink" href="http://omniorb.sourceforge.net/" target="_top">omniORB website</a> to
download omniORB.</p><p>For the following steps, assume that you have omniORB installed
in <code class="filename"><OMNIORB_PATH></code>. Assuming you have the
external packages installed, do the following from the top-level
<code class="filename">juggler</code> directory:</p><pre class="screen">mkdir build
cd build
../configure.pl --with-cxx-orb=omniORB4 --with-cxx-orb-root=<OMNIORB_PATH> --with-java-orb=JDK --module=Tweek
gmake build install</pre></div></div></div></div></body></html>