INSTALL.xml

Revision 19199, 46.8 kB (checked in by patrick, 2 years ago)

MFT [rev 19198]: Replace all the remaining references to CVS with Subversion

information.

Property svn:eol-style set to native
Property svn:keywords set to Author Date Id Revision

Line
1	<?xml version="1.0" encoding="UTF-8"?>
2	<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4	<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
24	code from our Subversion repository. (Those users who downloaded a
25	pre-packaged source release can skip ahead to <xref
26	linkend="using.configure.pl" />). We conclude with instructions on how
27	to build VR Juggler and its 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 source (<ulink
31	url="http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromSvn">http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromSvn</ulink>).
32	It is a <emphasis>supplement</emphasis> to this document containing tips
33	and reminders for those users building the SVN 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>
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
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 <script-name></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.
69	BEGIN failed--compilation aborted at ./configure.pl line 35.</screen>
70
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>
120	</section>
121
122	<section>
123	<title>Important Note for Windows 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&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) or newer to compile the source code.</para>
132	</section>
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 Subversion repository on RealityForge. If you got the code from
142	a pre-packaged source archive, that code is a complete
143	<quote>snapshot</quote> of the Subversion repository at the time of
144	release. It contains all dependencies that would otherwise have been
145	acquired using Subversion. It <emphasis>does not</emphasis> contain
146	binary dependencies that must be downloaded separately (such as NSPR,
147	the Java Developer Kit, a 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 Subversion repository in the module
223	<literal>cppunit</literal>. Refer to <xref
224	linkend="section.cvs.access" /> for instructions about accessing
225	the Juggler Subversion repository.</para>
226	</listitem>
227	</itemizedlist>
228
229	<para>The third-party dependencies must be downloaded from the sites
230	listed above and installed manually. You may also have to compile one or
231	more of the packages if binary distributions are not available. Which
232	packages you download depends on what you already have installed. Note
233	carefully which packages are needed based on the software you have
234	installed and what versions of tools (such as the JDK) that you
235	download.</para>
236
237	<section id="section.cvs.access">
238	<title>How to Get the Juggler Suite from Subversion</title>
239
240	<para>You can optionally get the Juggler Project as a source code
241	tarball from the website (<ulink
242	url="http://www.vrjuggler.org/">http://www.vrjuggler.org/</ulink>) or
243	you can execute the following command from a shell to get the code
244	from our Subversion repository:</para>
245
246	<screen>svn co https://realityforge.vrsource.org/svn/vrjuggler/juggler/branches/2.0 juggler
247	</screen>
248	</section>
249
250	<section>
251	<title>Downloading Third-Party Dependencies</title>
252
253	<para>In addition to source the dependencies acquired through
254	Subversion, there are some third-party dependencies that must be
255	installed separately. Remember that no Java code in VR Juggler can be
256	used without the JDK and a working Java version of CORBA.</para>
257
258	<section>
259	<title>Boost</title>
260
261	<para>The minimum required version of Boost, as of this writing,
262	is 1.31.0. The Boost source can be downloaded from <ulink
263	url="http://www.sf.net/projects/boost/">http://www.sf.net/projects/boost/</ulink>.
264	To compile and install Boost, refer to its installation
265	documentation (<ulink
266	url="http://www.boost.org/more/getting_started.html#Build_Install">http://www.boost.org/more/getting_started.html#Build_Install</ulink>).
267	Note that you need the command <command>bjam</command> (referred
268	to as <quote>boost-jam</quote> on the Boost download page) to
269	build Boost.</para>
270
271	<important>
272	<para>Mac OS X users should compile the Boost libraries using
273	the <quote>darwin</quote> toolset.</para>
274	</important>
275	</section>
276
277	<section>
278	<title>CppDOM</title>
279
280	<para>For XML processing, we use CppDOM 0.3.2 or newer. The source
281	and binary distributions for some platforms can be downloaded from
282	<ulink
283	url="http://www.sf.net/projects/xml-cppdom/">http://www.sf.net/projects/xml-cppdom/</ulink>.
284	If a binary version is not available for your operating system you
285	must compile and install CppDOM yourself. Note that you need SCons
286	(<ulink
287	url="http://scons.sourceforge.net/">http://scons.sourceforge.net/</ulink>)
288	to build and install CppDOM.</para>
289	</section>
290
291	<section>
292	<title>GMTL</title>
293
294	<para>For high-level mathematical operations, we use GMTL 0.3.2 or
295	newer. The source distribution can be downloaded from <ulink
296	url="http://www.sf.net/projects/ggt/">http://www.sf.net/projects/ggt/</ulink>.
297	Note that you need SCons (<ulink
298	url="http://scons.sourceforge.net/">http://scons.sourceforge.net/</ulink>)
299	to build and install GMTL.</para>
300	</section>
301
302	<section>
303	<title>Netscape Portable Runtime (NSPR)</title>
304
305	<para>Our operating system abstraction, VPR, can make use of NSPR
306	for operating system primitives. On some platforms (IRIX, FreeBSD,
307	Linux, Mac OS X), the use of NSPR is strictly optional. On others
308	(Win32, HP-UX, and Solaris), it is required. Based on your local
309	system, you should decide whether you need NSPR. Binary versions
310	of NSPR can be downloaded from <ulink
311	url="ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases">ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases</ulink>.
312	At this time, we recommend the use of version 4.2 or newer.</para>
313	</section>
314
315	<section>
316	<title>Java Developer Kit (also called the J2SE SDK)</title>
317
318	<para>We make use of the Java programming language in addition to
319	C++. Java is used exclusively for GUIs such as Tweek and VRJConfig
320	(which is a JavaBean that is loaded into Tweek). To compile the
321	Java code, a JDK is necessary. We currently require version 1.4 or
322	newer. The Java Standard Edition can be downloaded from <ulink
323	url="http://java.sun.com/j2se/">http://java.sun.com/j2se/</ulink>.
324	More information can be found at <ulink
325	url="http://java.sun.com/">http://java.sun.com/</ulink>.</para>
326	</section>
327
328	<section>
329	<title>omniORB</title>
330
331	<para>omniORB is a C++ implementation of CORBA 2.3. It is required
332	in order to compile the Tweek C++ API. At this time, the Tweek C++
333	API is not required for VR Juggler, but this situation will change
334	in the near future. At this time, we primarily use omniORB 4.0.x.
335	omniORB can be downloaded from <ulink
336	url="http://omniorb.sourceforge.net/">http://omniorb.sourceforge.net/</ulink>.</para>
337
338	<para>omniORB 3.0 has strange conventions for how installations
339	are made. Within the <filename>bin</filename> and
340	<filename>lib</filename> directories, there are platform-specific
341	subdirectories that contain the actual binaries (except when
342	installed on FreeBSD via the Ports Collection). Because of this,
343	several extra options must be specified in order to tell the Tweek
344	configure script where to find everything. Please refer to <xref
345	linkend="tweek.build.section" /> for more details on this.</para>
346	</section>
347	</section>
348	</section>
349
350	<section id="compile.section">
351	<title>Compiling</title>
352
353	<para>In this section, we describe how to compile the Juggler Project.
354	We focus on VR Juggler as a whole, but information about some of the
355	individual components is provided later.</para>
356
357	<section>
358	<title>Important Note Regarding Compiling</title>
359
360	<para>You have downloaded <emphasis>developmental</emphasis> code. It
361	may not be stable, and it may not even compile. Compiling VR Juggler
362	itself can be a little complicated for anyone who does not have some
363	background in using Subversion, Autoconf, C++, and
364	<command>make</command> or Visual Studio.</para>
365	</section>
366
367	<section>
368	<title>Compiling the Juggler Suite of Tools</title>
369
370	<para>This section explains how to get, configure, and compile all of
371	the tools that make up VR Juggler. Each tool compiles to its own
372	library and can be installed individually. (Refer to the
373	<filename>README</filename> file in this directory for more
374	information about the specific modules.)</para>
375
376	<para>To build VR Juggler on Windows, you must use the Visual Studio
377	solution. After getting the dependencies needed to compile VR Juggler
378	(see the next section), refer to the <ulink
379	url="vc7/README.html">README.html</ulink> file located in the
380	<filename>vc7</filename> subdirectory of this directory. Do not
381	bother to the rest of this document.</para>
382
383	<section>
384	<title>Per-Module Dependencies</title>
385
386	<para>Here, we provide per-module dependency information. Given
387	that the dependencies for any single module are met, the modules
388	may be reused effectively outside the scope of immersive VR
389	application development. Below, we list the
390	<emphasis>minimum</emphasis> required version for each dependency,
391	and where appropriate, we note which dependencies are
392	optional.</para>
393
394	<section>
395	<title>VPR</title>
396
397	<para>VPR provides a cross-platform, object-oriented operating
398	system abstraction. It is the foundation for all other Juggler
399	modules.</para>
400
401	<itemizedlist>
402	<listitem>
403	<para>CppDOM 0.3.2</para>
404	</listitem>
405
406	<listitem>
407	<para>Boost headers and Boost.Filesystem 1.31.0</para>
408	</listitem>
409
410	<listitem>
411	<para>NSPR (Windows, Solaris, and HP-UX only) 4.4</para>
412	</listitem>
413	</itemizedlist>
414	</section>
415
416	<section>
417	<title>Tweek C++ API</title>
418
419	<para>Tweek implements a distributed model/view/controller
420	system on top of CORBA. The Tweek C++ API provides the C++
421	component of that system. Code written on top of the Tweek C++
422	API normally acts as the model piece of the distributed
423	model/view/controller system.</para>
424
425	<itemizedlist>
426	<listitem>
427	<para>VPR</para>
428	</listitem>
429
430	<listitem>
431	<para>omniORB 4.0</para>
432	</listitem>
433	</itemizedlist>
434	</section>
435
436	<section>
437	<title>Tweek Java API</title>
438
439	<para>Tweek implements a distributed model/view/controller
440	system on top of CORBA. The Tweek Java API provides the Java
441	component of that system. The main part of the Tweek Java API
442	is the Tweek JavaBean Loader, a GUI application that loads
443	Tweek Beans that normally function as the view and controller
444	pieces of the distributed module/view/controller system.</para>
445
446	<itemizedlist>
447	<listitem>
448	<para>J2SE SDK 1.4</para>
449	</listitem>
450
451	<listitem>
452	<para>JDOM (included with Juggler source)</para>
453	</listitem>
454
455	<listitem>
456	<para>Ant (included with Juggler source)</para>
457	</listitem>
458
459	<listitem>
460	<para>JacORB IDL-to-Java compiler (included with Juggler
461	source)</para>
462	</listitem>
463	</itemizedlist>
464	</section>
465
466	<section>
467	<title>Tweek Python API</title>
468
469	<para>Tweek implements a distributed model/view/controller
470	system on top of CORBA. The Tweek Python API provides the
471	Python component of that system. The main part of the Tweek
472	Java API is the <emphasis>unfinished</emphasis> TweekQt GUI, an
473	application that loads Python modules that normally function as
474	the view and controller pieces of the distributed
475	module/view/controller system.</para>
476
477	<itemizedlist>
478	<listitem>
479	<para>Python 2.3</para>
480	</listitem>
481
482	<listitem>
483	<para>omniORBpy 2.0</para>
484	</listitem>
485	</itemizedlist>
486	</section>
487
488	<section>
489	<title>JCCL C++ API</title>
490
491	<para>The JCCL C++ API provides an interface for loading
492	XML-based configurations. It includes the run-time
493	reconfiguration feature of Juggler.</para>
494
495	<itemizedlist>
496	<listitem>
497	<para>VPR</para>
498	</listitem>
499	</itemizedlist>
500	</section>
501
502	<section>
503	<title>JCCL Java API</title>
504
505	<para>The JCCL Java API provides a programming interface for
506	editing Juggler configuration files and config definition files
507	as well as JavaBeans for editing these files using a graphical
508	interface.</para>
509
510	<itemizedlist>
511	<listitem>
512	<para>Tweek Java API</para>
513	</listitem>
514
515	<listitem>
516	<para>TableLayout package (included with Juggler
517	source)</para>
518	</listitem>
519	</itemizedlist>
520	</section>
521
522	<section>
523	<title>JCCL Remote Run-Time Reconfiguration Plug-in
524	(C++)</title>
525
526	<para>The C++ JCCL Remote Run-Time Reconfiguration Plug-in is
527	an optional extension to the JCCL Config Manager for allowing
528	remote manipulation of a Juggler configuration at run time
529	based on Tweek.</para>
530
531	<itemizedlist>
532	<listitem>
533	<para>Tweek C++ API</para>
534	</listitem>
535	</itemizedlist>
536	</section>
537
538	<section>
539	<title>JCCL Remote Run-Time Reconfiguration Plug-in
540	(Java)</title>
541
542	<para>The Java JCCL Remote Run-Time Reconfiguration Plug-in is
543	an optional extension that provides the features needed for a
544	Java-based editor to communicate with the C++ Remote Run-Time
545	Reconfiguration Plug-in to edit Juggler configurations
546	live.</para>
547
548	<itemizedlist>
549	<listitem>
550	<para>Tweek Java API</para>
551	</listitem>
552	</itemizedlist>
553	</section>
554
555	<section>
556	<title>Sonix</title>
557
558	<para>Sonix is an abstraction layer for positional sound
559	software. Sonix itself cannot play audio, but it includes
560	plug-ins based on popular interfaces for playing audio. Each
561	plug-in depends on a specific audio software library.</para>
562
563	<itemizedlist>
564	<listitem>
565	<para>VPR</para>
566	</listitem>
567
568	<listitem>
569	<para>GMTL 0.1.9</para>
570	</listitem>
571	</itemizedlist>
572
573	<section>
574	<title>Sonix OpenAL Plug-in</title>
575
576	<itemizedlist>
577	<listitem>
578	<para>Sonix</para>
579	</listitem>
580
581	<listitem>
582	<para>OpenAL</para>
583	</listitem>
584
585	<listitem>
586	<para>Free ALUT</para>
587	</listitem>
588	</itemizedlist>
589	</section>
590
591	<section>
592	<title>Sonix Audiere Plug-in</title>
593
594	<itemizedlist>
595	<listitem>
596	<para>Sonix</para>
597	</listitem>
598
599	<listitem>
600	<para>Audiere</para>
601	</listitem>
602	</itemizedlist>
603	</section>
604
605	<section>
606	<title>Sonix AudioWorks Plug-in</title>
607
608	<itemizedlist>
609	<listitem>
610	<para>Sonix</para>
611	</listitem>
612
613	<listitem>
614	<para>AudioWorks</para>
615	</listitem>
616	</itemizedlist>
617	</section>
618	</section>
619
620	<section>
621	<title>Gadgeteer</title>
622
623	<para>Gadgeteer handles all input devices that can be used by
624	VR Juggler applications.</para>
625
626	<itemizedlist>
627	<listitem>
628	<para>VPR</para>
629	</listitem>
630
631	<listitem>
632	<para>JCCL</para>
633	</listitem>
634
635	<listitem>
636	<para>GMTL 0.1.9</para>
637	</listitem>
638
639	<listitem>
640	<para>X Window System (non-Windows platforms)</para>
641	</listitem>
642	</itemizedlist>
643	</section>
644
645	<section>
646	<title>Gadgeteer Device Driver Plug-ins</title>
647
648	<para>The device driver plug-ins for Gadgeteer are independent
649	components that are discovered and used at run time based on
650	the application configuration. Drivers with dependencies are
651	optional.</para>
652
653	<itemizedlist>
654	<listitem>
655	<para>Gadgeteer</para>
656	</listitem>
657
658	<listitem>
659	<para>VRPN 06.06 for the VRPN driver plug-in</para>
660	</listitem>
661
662	<listitem>
663	<para>TrackD API 4 for the TrackD API driver
664	plug-in</para>
665	</listitem>
666
667	<listitem>
668	<para>Microsoft Speech API for the MS Speech API driver
669	plug-in</para>
670	</listitem>
671	</itemizedlist>
672	</section>
673
674	<section>
675	<title>Gadgeteer Cluster Plug-ins</title>
676
677	<para>The cluster plug-ins extend the functionality of the
678	clustering infrastructure built into Gadgeteer.</para>
679
680	<itemizedlist>
681	<listitem>
682	<para>Gadgeteer</para>
683	</listitem>
684	</itemizedlist>
685	</section>
686
687	<section>
688	<title>VR Juggler</title>
689
690	<para>The VR Juggler module is the unifying piece that pulls
691	all the other Juggler modules together. It provides a virtual
692	platform for VR application development. Real-time rendering is
693	controlled by Draw Managers. The OpenGL Performer Draw Manager
694	is optional.</para>
695
696	<itemizedlist>
697	<listitem>
698	<para>Gadgeteer</para>
699	</listitem>
700
701	<listitem>
702	<para>Sonix</para>
703	</listitem>
704
705	<listitem>
706	<para>OpenGL</para>
707	</listitem>
708
709	<listitem>
710	<para>OpenGL Performer for the
711	<emphasis>optional</emphasis> OpenGL Performer Draw
712	Manager</para>
713	</listitem>
714	</itemizedlist>
715	</section>
716
717	<section>
718	<title>VR Juggler Run-Time Performance Monitoring Plug-in
719	(C++)</title>
720
721	<para>The C++ VR Juggler Run-Time Performance Monitoring
722	Plug-in provides an optional extension to VR Juggler for remote
723	visualization of performance metrics that are captured while
724	running a VR Juggler application. Communication is performed
725	using the Tweek C++ API on top of CORBA.</para>
726
727	<itemizedlist>
728	<listitem>
729	<para>Tweek C++ API</para>
730	</listitem>
731
732	<listitem>
733	<para>VR Juggler</para>
734	</listitem>
735	</itemizedlist>
736	</section>
737
738	<section>
739	<title>VR Juggler Run-Time Performance Monitoring Plug-in
740	(Java)</title>
741
742	<para>The Java VR Juggler Run-Time Performance Monitoring
743	Plug-in is an optional extension that provides the features
744	needed for Java-based visualization of performance data
745	collected while a VR Juggler application is running. This is
746	another JavaBean handled by the Tweek JavaBean Loader, and it
747	uses CORBA to communicate with the C++ VR Juggler Run-Time
748	Performance Monitoring Plug-in.</para>
749
750	<itemizedlist>
751	<listitem>
752	<para>JCCL Java API</para>
753	</listitem>
754
755	<listitem>
756	<para>JFreeChart (included with Juggler source)</para>
757	</listitem>
758	</itemizedlist>
759	</section>
760
761	<section>
762	<title>VRJConfig</title>
763
764	<para>VRJConfig is the graphical editor for Juggler
765	configurations. It is a JavaBean loaded by the Tweek JavaBean
766	Loader, and it makes use of the editor Beans provided by the
767	JCCL Java API.</para>
768
769	<itemizedlist>
770	<listitem>
771	<para>JCCL Java API</para>
772	</listitem>
773
774	<listitem>
775	<para>JGraph (included with Juggler source)</para>
776	</listitem>
777	</itemizedlist>
778	</section>
779	</section>
780
781	<section id="config.vrjuggler.section">
782	<title>Configuring the Juggler Build</title>
783
784	<para>We now explain the process by which the Juggler build is
785	configured. The Juggler Suite makes use of the well-known, widely
786	used GNU tools Autoconf and GNU Make. We provide a wrapper script
787	written in Perl called <command>configure.pl</command> that gets
788	the process started.</para>
789
790	<para>The Juggler build is highly automated. The trickiest part is
791	telling the build where to find the third-party dependencies. This
792	part can be simplified, however, by installing the third-party
793	dependencies in the default location where the search will be
794	performed. In most cases, this is <filename>/usr/local</filename>,
795	but in others it is <filename>/usr</filename>. The default search
796	location is determined by whether the dependency is considered to
797	be a fundamental part of the operating system installation (such
798	as OpenGL) or if it is an <quote>add-on</quote> package (such as
799	Boost, GMTL, CppDOM, or omniORB).</para>
800
801	<sidebar>
802	<para>The distinction between <filename>/usr/local</filename>
803	and <filename>/usr</filename> is complicated by the fact that
804	most Linux distributions have <emphasis>everything</emphasis>
805	installed in <filename>/usr</filename>. While Linux may be
806	popular, it should not (yet) be considered a model example of
807	how to do things. In traditional UN*X distributions (BSD and
808	System V), <filename>/usr</filename> is only used for the
809	fundamental operating system pieces;
810	<filename>/usr/local</filename> is used for extra bits. The
811	Juggler build is based on these assumptions. Furthermore, most
812	open source software packages (e.g., Boost, omniORB, Perl,
813	Python) default to installing themselves in
814	<filename>/usr/local</filename>, which suggests that the
815	authors of those tools generally expect their software to be in
816	<filename>/usr/local</filename>.</para>
817	</sidebar>
818
819	<section id="using.configure.pl">
820	<title>Using <command>configure.pl</command></title>
821
822	<para>In the base <filename>juggler</filename> source
823	directory, we have a <quote>global</quote> configure script
824	written in Perl called <command>configure.pl</command>. To get
825	the command-line options for this script, use one of the
826	following (the second being much more detailed):</para>
827
828	<screen>./configure.pl --help
829	./configure.pl --manual</screen>
830
831	<para>To configure your system, you will need to see what
832	options all the Autoconf-based configure scripts in VR Juggler
833	need. To get this text, enter:</para>
834
835	<screen>./configure.pl --all-help</screen>
836
837	<para><important>
838	<para>In order for this to work, the configure script for
839	each of the Juggler modules must be generated. This can
840	be done manually by running <command>autogen.sh</command>
841	in the top-level <filename>juggler</filename> directory.
842	It use is simple:</para>
843
844	<screen>./autogen.sh</screen>
845
846	<para>This <command>autogen.sh</command> script must be
847	run from the directory where it exists. Do not try to run
848	it from a build directory or any other place in the
849	Juggler source tree. The same holds for the individual
850	<command>autogen.sh</command> scripts in the various
851	modules, should you need to run one individually.</para>
852	</important><command>configure.pl</command> can run in a
853	unique <quote>build</quote> directory or in the directory where
854	it resides. Here is how we (the Juggler Team) have been using
855	it:</para>
856
857	<orderedlist>
858	<listitem>
859	<para>Make a directory for compiling. There are many good
860	reasons to do this away from the main source tree (though
861	they will not be listed here).</para>
862
863	<screen>mkdir build.linux.posix</screen>
864
865	<para>This example using an ad hoc naming convention
866	based on operating system and threading subsystem. Other
867	examples could be <filename>build.irix.sproc</filename>,
868	<filename>build.solaris.nspr</filename>, etc.</para>
869