INSTALL.xml

Revision 20929, 48.9 kB (checked in by patrick, 10 months ago)
Without SPROC support, there is no way to use AudioWorks?. Beyond that, AudioWorks? seems to have disappeared long ago.
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.3)</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.3 of the Juggler
21	Project. This is the code that will become VR Juggler 3.0, and it is the
22	code that is used to create the VR Juggler 3.0 pre-releases. Please be
23	aware that this code represents a work in progress, and if you acquired
24	it directly from Subversion rather than using a pre-packaged source code
25	snapshot, the code may have bugs affecting compilation and
26	execution.</para>
27
28	<para>This document explains how to build the modules of the Juggler
29	Project from the source code. We begin by explaining some issues related
30	to specific operating systems. We then explain how to get the source
31	code from our Subversion repository. (Those users who downloaded a
32	pre-packaged source release can skip ahead to <xref
33	linkend="using.configure.pl" />). We conclude with instructions on how
34	to build VR Juggler and its individual components.</para>
35
36	<para>Before reading further, we recommend that readers take a look at
37	the Wiki page relating to building from source (<ulink
38	url="http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromSvn">http://www.vrjuggler.org/twiki_public/bin/view/Juggler/BuildingFromSvn</ulink>).
39	It is a <emphasis>supplement</emphasis> to this document containing tips
40	and reminders for those users building the SVN version of VR Juggler. It
41	is not a replacement for this document, nor can it stand on its own as
42	build instructions. You are reading the definitive build instructions;
43	the Wiki page merely provides informal, extra information.</para>
44
45	<section>
46	<title>Important Notes for IRIX Users</title>
47
48	<para>Despite our best efforts, there are some issues related to
49	compiling the Juggler Project on IRIX. We introduce them in this
50	section and explain how to work around them.</para>
51
52	<section>
53	<title>Perl Version</title>
54
55	<para>There are many Perl scripts used as part of getting,
56	configuring, and building the Juggler Suite of tools. In
57	particular, two scripts required for compiling need Perl 5.005 or
58	newer. The version of Perl that ships with IRIX 6.5 is very old
59	(circa 1997) and does not work with many Perl scripts we have
60	written. SGI provides a much newer version of Perl (5.6.1) with
61	their freeware tools (<ulink
62	url="http://freeware.sgi.com/">http://freeware.sgi.com/</ulink>).
63	It will be necessary to install that version for our scripts to
64	work. This version is typically installed as
65	<filename>/usr/freeware/bin/perl</filename>.</para>
66
67	<para>Once you have a modern Perl installed, you can run various
68	Perl scripts as follows:</para>
69
70	<screen>/usr/freeware/bin/perl <script-name></screen>
71
72	<para>The above will be required any time a Perl script fails with
73	an error similar to the following:</para>
74
75	<screen>Perl 5.005 required--this is only version 5.00404, stopped at ./configure.pl line 35.
76	BEGIN failed--compilation aborted at ./configure.pl line 35.</screen>
77
78	<para>Furthermore, it is highly recommended that the
79	<option>--with-perl</option> argument be passed to
80	<command>configure.pl</command>. This argument gives all the
81	Autoconf-based configure scripts a hint about where the preferred
82	version of Perl lives. If using
83	<filename>/usr/freeware/bin/perl</filename> to run
84	<command>configure.pl</command>, we recommend that the
85	<command>configure.pl</command> command line appear similar to the
86	following:</para>
87
88	<screen>/usr/freeware/bin/perl configure.pl --with-perl=/usr/freeware/bin</screen>
89
90	<para>Note that the value given to <option>--with-perl</option> is
91	the <emphasis>directory</emphasis> where the
92	<command>perl</command> executable can be found. The configure
93	scripts will add this directory to the front of the search path
94	when trying to find a suitable <command>perl</command> executable.
95	Once it is found, all the Perl scripts used for configuration,
96	compilation, and installation will use that executable.</para>
97
98	<para>To simplify command execution somewhat, it can help to have
99	<filename>/usr/freeware/bin</filename> (or whatever path is
100	appropriate) in your path before <filename>/bin</filename> or
101	<filename>/usr/bin</filename> or any of the other myriad
102	directories where Perl might exist on IRIX. In such a situation,
103	none of the above extra steps should be necessary. The correct
104	version of Perl will be found simply by virtue of it being early
105	in your path.</para>
106	</section>
107
108	<section>
109	<title>MIPSpro Compiler Version</title>
110
111	<para>Reports have been made on the VR Juggler mailing list
112	regarding compile failures (including segmentation faults within
113	the compiler) occur when using the MIPSpro Compilers Version
114	7.3.1.1m. We have found upgrading to Version 7.3.1.3m (or newer)
115	fixes the problems.</para>
116
117	<para>A new feature of VR Juggler 1.1 and newer is support for GCC
118	on IRIX. Users who do not have MIPSpro or cannot upgrade can
119	compile and run VR Juggler (without OpenGL Performer support)
120	using the version of GCC distributed by SGI. It can be downloaded
121	from <ulink
122	url="http://freeware.sgi.com/index-by-alpha.html">http://freeware.sgi.com/index-by-alpha.html</ulink>
123	for free. When configuring the source with
124	<command>configure.pl</command> (described later), use the option
125	<option>--with-gcc</option>.</para>
126	</section>
127	</section>
128
129	<section>
130	<title>Important Note for Windows Users</title>
131
132	<para>VR Juggler 1.1 and newer use a lot of C++ features not
133	supported by Visual Studio 6.0. Microsoft <ulink
134	url="http://support.microsoft.com/default.aspx?scid=http://support.microsoft.com:80/support/kb/articles/q243/4/51.asp&NoWebContent=1">acknowledges</ulink>
135	the issues concerning noncompliance to the C++ Standard with Visual
136	Studio 6.0, and it appears that they have no plans to fix these
137	problems. Therefore, we require the use of Visual Studio 7.1 (.NET
138	2003) or newer to compile the source code.</para>
139	</section>
140	</section>
141
142	<section>
143	<title>Build Tools</title>
144
145	<para>When building on non-Windows platforms, the GNU Autotools are
146	required. This means that, in addition to a C++ compiler (e.g., GCC),
147	the following packages must be installed in order to compile VR
148	Juggler:</para>
149
150	<itemizedlist>
151	<listitem>
152	<para>GNU Make 3.79 or newer</para>
153	</listitem>
154
155	<listitem>
156	<para>GNU Autoconf 2.53 or newer</para>
157	</listitem>
158
159	<listitem>
160	<para>GNU Automake 1.8 or newer</para>
161	</listitem>
162	</itemizedlist>
163
164	<para>Additionally, VR Juggler 2.1 and beyond require the <ulink
165	url="https://realityforge.vrsource.org/view/FlagPoll/">Flagpoll</ulink>
166	software tool. As of this writing, the minimum required version is
167	0.8.1. It is recommended that all of these tools be installed in either
168	the <filename>/usr</filename> or the <filename>/usr/local</filename>
169	directory trees so that search paths do not have to be extended.</para>
170	</section>
171
172	<section id="source.code.section">
173	<title>Getting the Source Code and the Dependencies</title>
174
175	<para>In this section, we explain how to get the Juggler Project source
176	code and the dependencies required to build Juggler. There are two ways
177	to get the source code: from a pre-packaged source release archive or
178	from the Subversion repository on RealityForge. If you got the code from
179	a pre-packaged source archive, that code is a complete
180	<quote>snapshot</quote> of the Subversion repository at the time of
181	release. It contains all dependencies that would otherwise have been
182	acquired using Subversion. It <emphasis>does not</emphasis> contain
183	binary dependencies that must be downloaded separately (such as NSPR,
184	the Java Developer Kit, a C++ compiler, etc.).</para>
185
186	<para>The current list of <emphasis>required</emphasis> software
187	packages is as follows:</para>
188
189	<itemizedlist>
190	<listitem>
191	<para>CppDOM (<ulink
192	url="http://www.sourceforge.net/projects/xml-cppdom/">http://www.sf.net/projects/xml-cppdom/</ulink>):
193	A lightweight, easy-to-use XML parser written in C++. CppDOM must
194	be compiled and installed for use with VR Juggler.</para>
195	</listitem>
196
197	<listitem>
198	<para>Boost (<ulink
199	url="http://www.boost.org/">http://www.boost.org/</ulink>): A C++
200	library providing many powerful utility classes and libraries.
201	Boost must be compiled and installed for use with VR
202	Juggler.</para>
203	</listitem>
204
205	<listitem>
206	<para>GMTL (<ulink
207	url="http://ggt.sourceforge.net/">http://ggt.sf.net/</ulink>): A
208	generic math library that makes use of C++ templates and STL
209	paradigms. GMTL must be installed for use with VR Juggler.</para>
210	</listitem>
211	</itemizedlist>
212
213	<para>The following lists <emphasis>semi-optional</emphasis>
214	packages:</para>
215
216	<itemizedlist>
217	<listitem>
218	<para>NSPR (<ulink
219	url="http://www.mozilla.org/projects/nspr/">http://www.mozilla.org/projects/nspr/</ulink>):
220	The Netscape Portable Runtime, which can be used by VPR for
221	threading and sockets (required on Win32 and Solaris).</para>
222	</listitem>
223
224	<listitem>
225	<para>Java Developer Kit (<ulink
226	url="http://java.sun.com/">http://java.sun.com/</ulink>): The J2SE
227	SDK (or JDK) is used to compile all the Java code used in the
228	Juggler Project. Without it, none of the Java code can be built.
229	We require version 1.4 or newer. The Java Standard Edition (J2SE)
230	can be downloaded from <ulink
231	url="http://java.sun.com/j2se/">http://java.sun.com/j2se/</ulink>.</para>
232	</listitem>
233
234	<listitem>
235	<para>omniORB (<ulink
236	url="http://www.jdom.org/">http://omniorb.sourceforge.net/</ulink>):
237	A C++ implementation of CORBA 2.3, required for the Tweek C++
238	API.</para>
239	</listitem>
240
241	<listitem>
242	<para>Doozer (<ulink
243	url="http://sourceforge.net/projects/doozer">http://sourceforge.net/projects/doozer</ulink>):
244	A collection of makefile stubs written for use with GNU Make and
245	intended for simplifying the creation of cross-platform VR Juggler
246	application builds. Version 2.1.4 or newer is needed for building
247	VR Juggler sample applications.</para>
248	</listitem>
249	</itemizedlist>
250
251	<para>The following are fully optional packages that are primarily of
252	interest only to people doing development on the Juggler Suite
253	itself:</para>
254
255	<itemizedlist>
256	<listitem>
257	<para>JUnit (<ulink
258	url="http://www.junit.org/">http://www.junit.org/</ulink>): A unit
259	testing framework for Java.</para>
260	</listitem>
261
262	<listitem>
263	<para>CppUnit (<ulink
264	url="http://cppunit.sourceforge.net/">http://cppunit.sourceforge.net/</ulink>):
265	A unit testing framework for C++. The Juggler C++ test suties make
266	use of extensions to CppUnit. An extended version of the CppUnit
267	source that includes these extensions can be acquired from the
268	Juggler Subversion repository in the module
269	<literal>cppunit</literal>. Refer to <xref
270	linkend="section.cvs.access" /> for instructions about accessing
271	the Juggler Subversion repository.</para>
272	</listitem>
273	</itemizedlist>
274
275	<para>The third-party dependencies must be downloaded from the sites
276	listed above and installed manually. You may also have to compile one or
277	more of the packages if binary distributions are not available. Which
278	packages you download depends on what you already have installed. Note
279	carefully which packages are needed based on the software you have
280	installed and what versions of tools (such as the JDK) that you
281	download.</para>
282
283	<section id="section.cvs.access">
284	<title>How to Get the Juggler Suite from Subversion</title>
285
286	<para>You can optionally get the Juggler Project as a source code
287	tarball from the website (<ulink
288	url="http://www.vrjuggler.org/">http://www.vrjuggler.org/</ulink>) or
289	you can execute the following command from a shell to get the code
290	from our Subversion repository:</para>
291
292	<screen>svn co https://realityforge.vrsource.org/svn/vrjuggler/juggler/trunk juggler
293	</screen>
294	</section>
295
296	<section>
297	<title>Downloading Third-Party Dependencies</title>
298
299	<para>In addition to source the dependencies acquired through
300	Subversion, there are some third-party dependencies that must be
301	installed separately. Remember that no Java code in VR Juggler can be
302	used without the JDK and a working Java version of CORBA.</para>
303
304	<section>
305	<title>Boost</title>
306
307	<para>The minimum required version of Boost, as of this writing,
308	is 1.31.0. The Boost source can be downloaded from <ulink
309	url="http://www.sf.net/projects/boost/">http://www.sf.net/projects/boost/</ulink>.
310	To compile and install Boost, refer to its installation
311	documentation (<ulink
312	url="http://www.boost.org/more/getting_started.html#Build_Install">http://www.boost.org/more/getting_started.html#Build_Install</ulink>).
313	Note that you need the command <command>bjam</command> (referred
314	to as <quote>boost-jam</quote> on the Boost download page) to
315	build Boost.</para>
316
317	<important>
318	<para>Mac OS X users should compile the Boost libraries using
319	the <quote>darwin</quote> toolset.</para>
320	</important>
321	</section>
322
323	<section>
324	<title>CppDOM</title>
325
326	<para>For XML processing, we use CppDOM 0.6.5 or newer. The source
327	and binary distributions for some platforms can be downloaded from
328	<ulink
329	url="http://www.sf.net/projects/xml-cppdom/">http://www.sf.net/projects/xml-cppdom/</ulink>.
330	If a binary version is not available for your operating system you
331	must compile and install CppDOM yourself. Note that you need SCons
332	(<ulink
333	url="http://scons.sourceforge.net/">http://scons.sourceforge.net/</ulink>)
334	to build and install CppDOM.</para>
335	</section>
336
337	<section>
338	<title>GMTL</title>
339
340	<para>For high-level mathematical operations, we use GMTL 0.4.12
341	or newer. The source distribution can be downloaded from <ulink
342	url="http://www.sf.net/projects/ggt/">http://www.sf.net/projects/ggt/</ulink>.
343	Note that you need SCons (<ulink
344	url="http://scons.sourceforge.net/">http://scons.sourceforge.net/</ulink>)
345	to build and install GMTL.</para>
346	</section>
347
348	<section>
349	<title>Netscape Portable Runtime (NSPR)</title>
350
351	<para>Our operating system abstraction, VPR, can make use of NSPR
352	for operating system primitives. On some platforms (IRIX, FreeBSD,
353	Linux, Mac OS X), the use of NSPR is strictly optional. On others
354	(Win32, HP-UX, and Solaris), it is required. Based on your local
355	system, you should decide whether you need NSPR. Binary versions
356	of NSPR can be downloaded from <ulink
357	url="ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases">ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases</ulink>.
358	At this time, we recommend the use of version 4.2 or newer.</para>
359	</section>
360
361	<section>
362	<title>Java Developer Kit (also called the J2SE SDK)</title>
363
364	<para>We make use of the Java programming language in addition to
365	C++. Java is used exclusively for GUIs such as Tweek and VRJConfig
366	(which is a JavaBean that is loaded into Tweek). To compile the
367	Java code, a JDK is necessary. We currently require version 1.4 or
368	newer. The Java Standard Edition can be downloaded from <ulink
369	url="http://java.sun.com/j2se/">http://java.sun.com/j2se/</ulink>.
370	More information can be found at <ulink
371	url="http://java.sun.com/">http://java.sun.com/</ulink>.</para>
372	</section>
373
374	<section>
375	<title>omniORB</title>
376
377	<para>omniORB is a C++ implementation of CORBA 2.3. It is required
378	in order to compile the Tweek C++ API. At this time, the Tweek C++
379	API is not required for VR Juggler, but this situation will change
380	in the near future. At this time, we primarily use omniORB 4.0.x;
381	omniORB 3.0 is not supported. omniORB can be downloaded from
382	<ulink
383	url="http://omniorb.sourceforge.net/">http://omniorb.sourceforge.net/</ulink>.</para>
384	</section>
385	</section>
386	</section>
387
388	<section id="compile.section">
389	<title>Compiling</title>
390
391	<para>In this section, we describe how to compile the Juggler Project.
392	We focus on VR Juggler as a whole, but information about some of the
393	individual components is provided later.</para>
394
395	<section>
396	<title>Important Note Regarding Compiling</title>
397
398	<para>You have downloaded <emphasis>developmental</emphasis> code. It
399	may not be stable, and it may not even compile. Compiling VR Juggler
400	itself can be a little complicated for anyone who does not have some
401	background in using Subversion, Autoconf, C++, and
402	<command>make</command> or Visual Studio.</para>
403	</section>
404
405	<section>
406	<title>Compiling the Juggler Suite of Tools</title>
407
408	<para>This section explains how to get, configure, and compile all of
409	the tools that make up VR Juggler. Each tool compiles to its own
410	library and can be installed individually. (Refer to the
411	<filename>README</filename> file in this directory for more
412	information about the specific modules.)</para>
413
414	<para>To build VR Juggler on Windows, you must use the Visual Studio
415	solution. After getting the dependencies needed to compile VR Juggler
416	(see the next section), refer to the <ulink
417	url="README-WINDOWS.html">README-WINDOWS.html</ulink> file located in
418	this directory. Do not bother to the rest of this document.</para>
419
420	<section>
421	<title>Per-Module Dependencies</title>
422
423	<para>Here, we provide per-module dependency information. Given
424	that the dependencies for any single module are met, the modules
425	may be reused effectively outside the scope of immersive VR
426	application development. Below, we list the
427	<emphasis>minimum</emphasis> required version for each dependency,
428	and where appropriate, we note which dependencies are
429	optional.</para>
430
431	<section>
432	<title>VPR</title>
433
434	<para>VPR provides a cross-platform, object-oriented operating
435	system abstraction. It is the foundation for all other Juggler
436	modules.</para>
437
438	<itemizedlist>
439	<listitem>
440	<para>CppDOM 0.6.6</para>
441	</listitem>
442
443	<listitem>
444	<para>Boost headers and Boost.Filesystem 1.31.0</para>
445	</listitem>
446
447	<listitem>
448	<para>NSPR (Windows, Solaris, and HP-UX only) 4.4</para>
449	</listitem>
450	</itemizedlist>
451	</section>
452
453	<section>
454	<title>Tweek C++ API</title>
455
456	<para>Tweek implements a distributed model/view/controller
457	system on top of CORBA. The Tweek C++ API provides the C++
458	component of that system. Code written on top of the Tweek C++
459	API normally acts as the model piece of the distributed
460	model/view/controller system.</para>
461
462	<itemizedlist>
463	<listitem>
464	<para>VPR</para>
465	</listitem>
466
467	<listitem>
468	<para>omniORB 4.0</para>
469	</listitem>
470	</itemizedlist>
471	</section>
472
473	<section>
474	<title>Tweek Java API</title>
475
476	<para>Tweek implements a distributed model/view/controller
477	system on top of CORBA. The Tweek Java API provides the Java
478	component of that system. The main part of the Tweek Java API
479	is the Tweek JavaBean Loader, a GUI application that loads
480	Tweek Beans that normally function as the view and controller
481	pieces of the distributed module/view/controller system.</para>
482
483	<itemizedlist>
484	<listitem>
485	<para>J2SE SDK 1.4</para>
486	</listitem>
487
488	<listitem>
489	<para>JDOM (included with Juggler source)</para>
490	</listitem>
491
492	<listitem>
493	<para>Ant (included with Juggler source)</para>
494	</listitem>
495
496	<listitem>
497	<para>JacORB IDL-to-Java compiler (included with Juggler
498	source)</para>
499	</listitem>
500	</itemizedlist>
501	</section>
502
503	<section>
504	<title>Tweek Python API</title>
505
506	<para>Tweek implements a distributed model/view/controller
507	system on top of CORBA. The Tweek Python API provides the
508	Python component of that system. The main part of the Tweek
509	Java API is the <emphasis>unfinished</emphasis> TweekQt GUI, an
510	application that loads Python modules that normally function as
511	the view and controller pieces of the distributed
512	module/view/controller system.</para>
513
514	<itemizedlist>
515	<listitem>
516	<para>Python 2.3</para>
517	</listitem>
518
519	<listitem>
520	<para>omniORBpy 2.0</para>
521	</listitem>
522	</itemizedlist>
523	</section>
524
525	<section>
526	<title>JCCL C++ API</title>
527
528	<para>The JCCL C++ API provides an interface for loading
529	XML-based configurations. It includes the run-time
530	reconfiguration feature of Juggler.</para>
531
532	<itemizedlist>
533	<listitem>
534	<para>VPR</para>
535	</listitem>
536	</itemizedlist>
537	</section>
538
539	<section>
540	<title>JCCL Java API</title>
541
542	<para>The JCCL Java API provides a programming interface for
543	editing Juggler configuration files and config definition files
544	as well as JavaBeans for editing these files using a graphical
545	interface.</para>
546
547	<itemizedlist>
548	<listitem>
549	<para>Tweek Java API</para>
550	</listitem>
551
552	<listitem>
553	<para>TableLayout package (included with Juggler
554	source)</para>
555	</listitem>
556	</itemizedlist>
557	</section>
558
559	<section>
560	<title>JCCL Remote Run-Time Reconfiguration Plug-in
561	(C++)</title>
562
563	<para>The C++ JCCL Remote Run-Time Reconfiguration Plug-in is
564	an optional extension to the JCCL Config Manager for allowing
565	remote manipulation of a Juggler configuration at run time
566	based on Tweek.</para>
567
568	<itemizedlist>
569	<listitem>
570	<para>Tweek C++ API</para>
571	</listitem>
572	</itemizedlist>
573	</section>
574
575	<section>
576	<title>JCCL Remote Run-Time Reconfiguration Plug-in
577	(Java)</title>
578
579	<para>The Java JCCL Remote Run-Time Reconfiguration Plug-in is
580	an optional extension that provides the features needed for a
581	Java-based editor to communicate with the C++ Remote Run-Time
582	Reconfiguration Plug-in to edit Juggler configurations
583	live.</para>
584
585	<itemizedlist>
586	<listitem>
587	<para>Tweek Java API</para>
588	</listitem>
589	</itemizedlist>
590	</section>
591
592	<section>
593	<title>Sonix</title>
594
595	<para>Sonix is an abstraction layer for positional sound
596	software. Sonix itself cannot play audio, but it includes
597	plug-ins based on popular interfaces for playing audio. Each
598	plug-in depends on a specific audio software library.</para>
599
600	<itemizedlist>
601	<listitem>
602	<para>VPR</para>
603	</listitem>
604
605	<listitem>
606	<para>GMTL 0.4.12</para>
607	</listitem>
608	</itemizedlist>
609
610	<section>
611	<title>Sonix OpenAL Plug-in</title>
612
613	<itemizedlist>
614	<listitem>
615	<para>Sonix</para>
616	</listitem>
617
618	<listitem>
619	<para>OpenAL</para>
620	</listitem>
621
622	<listitem>
623	<para>Free ALUT</para>
624	</listitem>
625	</itemizedlist>
626	</section>
627
628	<section>
629	<title>Sonix Audiere Plug-in</title>
630
631	<itemizedlist>
632	<listitem>
633	<para>Sonix</para>
634	</listitem>
635
636	<listitem>
637	<para>Audiere</para>
638	</listitem>
639	</itemizedlist>
640	</section>
641	</section>
642
643	<section>
644	<title>Gadgeteer</title>
645
646	<para>Gadgeteer handles all input devices that can be used by
647	VR Juggler applications.</para>
648
649	<itemizedlist>
650	<listitem>
651	<para>VPR</para>
652	</listitem>
653
654	<listitem>
655	<para>JCCL</para>
656	</listitem>
657
658	<listitem>
659	<para>GMTL 0.4.12</para>
660	</listitem>
661
662	<listitem>
663	<para>X Window System (non-Windows platforms)</para>
664	</listitem>
665	</itemizedlist>
666	</section>
667
668	<section>
669	<title>Gadgeteer Device Driver Plug-ins</title>
670
671	<para>The device driver plug-ins for Gadgeteer are independent
672	components that are discovered and used at run time based on
673	the application configuration. Drivers with dependencies are
674	optional.</para>
675
676	<itemizedlist>
677	<listitem>
678	<para>Gadgeteer</para>
679	</listitem>
680
681	<listitem>
682	<para>VRPN 07.03 for the VRPN driver plug-in</para>
683	</listitem>
684
685	<listitem>
686	<para>TrackD API 4 for the TrackD API driver
687	plug-in</para>
688	</listitem>
689
690	<listitem>
691	<para>Microsoft Speech API for the MS Speech API driver
692	plug-in</para>
693	</listitem>
694	</itemizedlist>
695	</section>
696
697	<section>
698	<title>Gadgeteer Cluster Plug-ins</title>
699
700	<para>The cluster plug-ins extend the functionality of the
701	clustering infrastructure built into Gadgeteer.</para>
702
703	<itemizedlist>
704	<listitem>
705	<para>Gadgeteer</para>
706	</listitem>
707	</itemizedlist>
708	</section>
709
710	<section>
711	<title>VR Juggler</title>
712
713	<para>The VR Juggler module is the unifying piece that pulls
714	all the other Juggler modules together. It provides a virtual
715	platform for VR application development. Real-time rendering is
716	controlled by Draw Managers. The OpenGL Performer Draw Manager
717	is optional.</para>
718
719	<itemizedlist>
720	<listitem>
721	<para>Gadgeteer</para>
722	</listitem>
723
724	<listitem>
725	<para>Sonix</para>
726	</listitem>
727
728	<listitem>
729	<para>OpenGL</para>
730	</listitem>
731
732	<listitem>
733	<para>OpenGL Performer for the
734	<emphasis>optional</emphasis> OpenGL Performer Draw
735	Manager</para>
736	</listitem>
737	</itemizedlist>
738	</section>
739
740	<section>
741	<title>VR Juggler Run-Time Performance Monitoring Plug-in
742	(C++)</title>
743
744	<para>The C++ VR Juggler Run-Time Performance Monitoring
745	Plug-in provides an optional extension to VR Juggler for remote
746	visualization of performance metrics that are captured while
747	running a VR Juggler application. Communication is performed
748	using the Tweek C++ API on top of CORBA.</para>
749
750	<itemizedlist>
751	<listitem>
752	<para>Tweek C++ API</para>
753	</listitem>
754
755	<listitem>
756	<para>VR Juggler</para>
757	</listitem>
758	</itemizedlist>
759	</section>
760
761	<section>
762	<title>VR Juggler Run-Time Performance Monitoring Plug-in
763	(Java)</title>
764
765	<para>The Java VR Juggler Run-Time Performance Monitoring
766	Plug-in is an optional extension that provides the features
767	needed for Java-based visualization of performance data
768	collected while a VR Juggler application is running. This is
769	another JavaBean handled by the Tweek JavaBean Loader, and it
770	uses CORBA to communicate with the C++ VR Juggler Run-Time
771	Performance Monitoring Plug-in.</para>
772
773	<itemizedlist>
774	<listitem>
775	<para>JCCL Java API</para>
776	</listitem>
777
778	<listitem>
779	<para>JFreeChart (included with Juggler source)</para>
780	</listitem>
781	</itemizedlist>
782	</section>
783
784	<section>
785	<title>VRJConfig</title>
786
787	<para>VRJConfig is the graphical editor for Juggler
788	configurations. It is a JavaBean loaded by the Tweek JavaBean
789	Loader, and it makes use of the editor Beans provided by the
790	JCCL Java API.</para>
791
792	<itemizedlist>
793	<listitem>
794	<para>JCCL Java API</para>
795	</listitem>
796
797	<listitem>
798	<para>JGraph (included with Juggler source)</para>
799	</listitem>
800	</itemizedlist>
801	</section>
802	</section>
803
804	<section>
805	<title>Preparing Flagpoll</title>
806
807	<para>The Flagpoll software has a default search path where it
808	looks for <filename>.pc</filename> and <filename>.fpc</filename>
809	package metadata files. It searchs
810	<filename>/usr/lib/pkgconfig</filename>,
811	<filename>/usr/lib/flagpoll</filename>,
812	<filename>/usr/lib64/pkgconfig</filename>,
813	<filename>/usr/lib64/flagpoll</filename>,
814	<filename>/usr/share/pkgconfig</filename>, and
815	<filename>/usr/share/flagpoll</filename>. If
816	<envar>LD_LIBRARY_PATH</envar> (or
817	<envar>DYLD_LIBRARY_PATH</envar> on Mac OS X) is set, Flagpoll
818	will search each of the directories in that environment variable
819	for subdirectories named <filename>pkgconfig</filename> and
820	<filename>flagpoll</filename>. Users can extend this search path
821	further by setting the environment variables
822	<envar>PKG_CONFIG_PATH</envar> and/or <envar>FLAGPOLL_PATH</envar>
823	to list more directories for Flagpoll to search. (All of the
824	environment variables mentioned here have as their value a
825	colon-separated list of directories.)</para>
826
827	<para>The Juggler build relies upon Flagpoll for getting compiler
828	and linker flags for the following packages:</para>
829
830	<itemizedlist>
831	<listitem>
832	<para>CppDOM</para>
833	</listitem>
834
835	<listitem>
836	<para>GMTL</para>
837	</listitem>
838
839	<listitem>
840	<para>omniORB</para>
841	</listitem>
842	</itemizedlist>
843
844	<para>Therefore, it is critical that Flagpoll be able to find the
845	package metadata file for each. For CppDOM, the
846	<filename>.fpc</filename> file is under the CppDOM
847	<filename>lib</filename> (or <filename>lib64</filename>) directory
848	in the <filename>flagpoll</filename> subdirectory. For omniORB,
849	the <filename>.pc</filename> files (there are several) are under
850	the omniORB <filename>lib</filename> (or
851	<filename>lib64</filename>) directory in the
852	<filename>pkgconfig</filename> subdirectory. Finally, for GMTL,
853	the <filename>.pc</filename> file is under the GMTL
854	<filename>share</filename> directory in the
855	<filename>pkgconfig</filename> subdirectory. If these packages are
856	installed in <filename>/usr</filename>, then Flagpoll will be able
857	to find the information it needs with no extra work on the part of
858	the user.</para>
859
860	<important>
861	<para>If Flagpoll is not installed in a place where the
862	<command>aclocal</command> tool searches for
863	<filename>.m4</filename> files by default, then it is necessary
864	to extend <command>aclocal</command>'s search path. This is
865	done by setting the environment variable
866	<envar>ACLOCAL_FLAGS</envar> to <quote><literal>-I
867	.../share/alocal</literal></quote> where
868	<quote><literal>...</literal></quote> is the path to the
869	directory tree where Flagpoll is installed.</para>
870	</important>
871	</section>
872
873	<section id="config.vrjuggler.section">
874	<title>Configuring the Juggler Build</title>
875
876	<para>We now explain the process by which the Juggler build is
877	configured. The Juggler Suite makes use of the well-known, widely
878	used GNU tools Autoconf and GNU Make. We provide a wrapper script
879	written in Perl called <command>configure.pl</command> that gets
880	the process started.</para>
881
882	<para>The Juggler build is highly automated. The trickiest part is