forked from vrjuggler/vrjuggler
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README-WINDOWS.html
362 lines (328 loc) · 14.4 KB
/
README-WINDOWS.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
<head>
<title>Compiling the Juggler Suite Using Visual Studio</title>
</head>
<body>
<h1>Table of Contents</h1>
<ul>
<li><a href="#intro">Introduction</a></li>
<li><a href="#install_python">Install Python</a></li>
<li><a href="#run_build_windows_py">Run <tt>build_windows.py</tt></a></li>
<li><a href="#choose_configuration">Choose a Configuration to Build</a></li>
<li><a href="#install_vrj">Install VR Juggler</a></li>
<li><a href="#install_deps">Install VR Juggler Dependencies</a></li>
</ul>
<a name="intro"><h1>1. Introduction to Compiling and Installing VR
Juggler</h1></a>
<p>
Building VR Juggler (both the C++ and the Java code) on Windows is
straightforward. A Visual Studio solution has been created that collects
each of the redistributable entities into Visual C++ projects. An overview
of the steps for building and installing VR Juggler on Windows follow:
</p>
<ol>
<li>
Install <a href="http://www.python.org/">Python</a> 2.2 or newer. To build
a 64-bit version of VR Juggler on Windows, the 64-bit build of Python 2.5
is <i>required</i>.
</li>
<li>
Run <tt>build_windows.py</tt> and fill in at least the paths to the
required dependencies.
</li>
<li>
In Visual Studio, choose the configuration(s) to build.
</li>
<li>
Install the compiled libraries, tools, and (optionally) dependencies.
</li>
</ol>
<p>
Each of the above steps is described in more detail below.
</p>
<a name="install_python"><h1>2. Install Python</h1></a>
<p>
In order to <a href="#run_build_windows_py">run the helper script
<tt>build_windows.py</tt></a>, you must have
<a href="http://www.python.org/">Python</a> 2.2 or newer installed on your
system. (To build a 64-bit version of VR Juggler, the 64-bit version of
Python 2.5 <i>must</i> be installed.) Visit the Python website for
<a href="http://www.python.org/download/">download and install
instructions</a>.
</p>
<a name="run_build_windows_py"><h1>3. Run <tt>build_windows.py</tt></h1></a>
<p>
Once you have Python installed, you can open the folder containing the
Juggler Project source in Windows Explorer and double-click on the
icon for the script <tt>build_windows.py</tt>. This script simplifies the
process of building VR Juggler on Windows by setting up paths and
environment variables based on input that you provide. It then starts
Visual Studio for you, and when the build is complete, it will perform
all the necessary installation steps—including installation of
VR Juggler's C++ dependencies into a convenient, centralized location.
</p>
<blockquote>
<b>IMPORTANT:</b> To create a 64-bit build on Windows, the command line
option <b><tt>--64</tt></b> must be used, or the <q>64-bit Build</q> option
in the GUI must be selected.
</blockquote>
<blockquote>
<b>NOTE:</b> For the build to work correctly, you must use the
<tt>build_windows.py</tt> script. It does more than just set environment
variables.
</blockquote>
<p>
Regarding the environment variables, the remainder of this
section describes each of the required and optional environment variables
used by the Visual Studio build. You can read through them to get a
better understanding of what <tt>build_windows.py</tt> expects from your
answers to its questions, or you can
<a href="#choose_configuration">skip to the next section</a>.
</p>
<h2>3.1. Set Environment Variables</h2>
<p>
Prior to starting the Visual Studio GUI, several environment variables
must be set. If you run the Python script <tt>build_windows.py</tt>, all of
the necessary environment variables will be set (and cached) based on
responses you provide to several questions.
These variables provide paths to external dependencies of the Juggler
source code. There are some environment variables that are required for
successful compilation of the Juggler source, and there are some that are
optional for getting additional code to compile.
</p>
<h3>3.1.1. Required Environment Variables</h3>
<p>
The required environment variables are as follows:
</p>
<dl>
<dt><tt>BOOST_ROOT</tt></dt>
<dd>
The root directory of an installed copy of
<a href="http://www.boost.org/">Boost</a> 1.31.0 or newer. This must
contain a directory named <tt>lib</tt> that contains <i>at least</i>
compiled versions of the Boost.Filesystem library. Refer to the relevant
<a href="http://www.boost.org/more/getting_started.html#Build_Install">Boost
documentation</a> for instructions on how to get and install Boost.
</dd>
<dt><tt>BOOST_INCLUDES</tt></dt>
<dd>
The directory containing the root of the Boost header tree. For a
Boost 1.31.0 installation, this will normally be set to the value of
<tt>%BOOST_ROOT%\include\boost-1_31</tt>. The requirement here is
that the value of this environment variable must be the full path to
a directory that contains a sub-directory named <tt>boost</tt>, in
which the Boost headers will be found.
</dd>
<dt><tt>BOOST_VERSION</tt></dt>
<dd>
The version of Boost against which the Juggler code will be compiled.
However, this string must use underscores (<tt>_</tt>) instead of
periods (<tt>.</tt>), and it should only reference the major and
minor version number. For example, if you are compiling against Boost
1.31.2, this environment variable would be set to <tt>1_31</tt>.
</dd>
<dt><tt>CPPDOM_ROOT</tt></dt>
<dd>
The root directory of an installed copy of
<a href="http://www.sourceforge.net/projects/xml-cppdom/">CppDOM</a>
0.7.8 or newer. This must contain a directory named <tt>lib</tt> and a
directory named <tt>include</tt>. Within <tt>lib</tt> (or <tt>lib64</tt>
for a 64-bit bit build), there must exist the different builds of CppDOM:
release DLL (<tt>cppdom-0_7_8.lib</tt> and <tt>cppdom-0_7_8.dll</tt>),
debug DLL (<tt>cppddom_d-0_7_8.lib</tt> and <tt>cppdom_d-0_7_8.dll</tt>),
static release (<tt>cppdom_s-0_7_8.lib</tt>), and static debug
(<tt>cppdom_s_d-0_7_8.lib</tt>).
</dd>
<dt><tt>CPPDOM_INCLUDES</tt></dt>
<dd>
The directory containing the root of the CppDOM header tree. For CppDOM
0.7.3 and newer, the header tree may be in a versioned sub-directory of
<tt>%CPPDOM_ROOT%\include</tt> such as
<tt>%CPPDOM_ROOT%\include\cppdom-0.7.3</tt>. The requirement here is
that the value of this environment variable must be the full path to
a directory that contains a sub-directory named <tt>cppdom</tt>, in
which the CppDOM headers will be found.
</dd>
<dt><tt>GMTL_ROOT</tt></dt>
<dd>
The root directory of an installed copy of
<a href="http://www.sourceforge.net/projects/ggt/">GMTL</a>
0.3.2 or newer. This must contain a directory named <tt>include</tt>
which in turn has a subdirectory named <tt>gmtl</tt> containing the
GMTL header files.
</dd>
<dt><tt>GMTL_INCLUDES</tt></dt>
<dd>
The directory containing the root of the CppDOM header tree. For GMTL
0.5.0 and newer, the header tree may be in a versioned sub-directory of
<tt>%GMTL_ROOT%\include</tt> such as
<tt>%GMTL_ROOT%\include\gmtl-0.5.0</tt>. The requirement here is that the
value of this environment variable must be the full path to a directory
that contains a sub-directory named <tt>gmtl</tt>, in which the GMTL
headers will be found.
</dd>
</dl>
<a name="opt_env_vars"><h3>3.1.2. Optional Environment Variables</h3></a>
<p>
The optional environment variables are as follows:
</p>
<dl>
<dt><tt>JAVA_HOME</tt></dt>
<dd>
The root directory of a <a href="http://java.sun.com/j2se/">Java 2 SDK</a>
installation. It is highly recommended that version 1.4.2 or newer be
installed. Version 1.3.1 is the minimum required version.
</dd>
<dt><tt>JOGL_HOME</tt></dt>
<dd>
The root directory of a <a href="http://jogl.dev.java.net">Jogl</a>
installation. This directory must contain two files: <tt>jogl.jar</tt>
and <tt>jogl-demos-util.jar</tt>. The default value is
<tt>%JAVA_HOME%</tt>. The minimum required version of Jogl is 1.0.
</dd>
<dt><tt>JAVA3D_HOME</tt></dt>
<dd>
The root directory of a
<a href="http://java.sun.com/products/java-media/3D/">Java 3D API</a>
installation. Typically, this will be the same as <tt>%JAVA_HOME%</tt>,
but that may not always be the case. The minimum required version of
the Java 3D API is 1.3.1.
</dd>
<dt><tt>PFROOT</tt></dt>
<dd>
The root directory of an
<a href="http://www.sgi.com/software/performer/">OpenGL Performer</a> 3.x
installation. This directory must contain the sub-directories
<tt>Include</tt> and <tt>Lib</tt>. This is the normal structure for a
standard OpenGL Performer installation. This variable is normally set
automatically by the OpenGL Performer installation wizard.
</dd>
<dt><tt>OMNIORB_ROOT</tt></dt>
<dd>
The root directory of an
<a href="http://omniorb.sourceforge.net/">omniORB</a> 4.0.x installation.
This directory must contain the sub-directories <tt>bin</tt>,
<tt>include</tt>, and <tt>lib</tt>.
</dd>
<dt><tt>MS_SPEECH_SDK_ROOT</tt></dt>
<dd>
The root directory of a
<a href="http://www.microsoft.com/speech/download/sdk51/">Microsoft Speech
SDK</a> installation. This directory must contain the sub-directories
<tt>include</tt> and <tt>lib\i386</tt>.
</dd>
<dt><tt>VRPN_ROOT</tt></dt>
<dd>
The root directory of a
<a href="http://www.cs.unc.edu/Research/vrpn/">VRPN</a> 6.04 or newer
tree. This directory must contain the sub-directories <tt>quat</tt>
and <tt>vrpn</tt>. In each of those, there must be a sub-directory
named <tt>pc_win32</tt>, and within it, there must be sub-directories
named <tt>Debug</tt> and <tt>Release</tt>. These contain the compiled
version of the appropriate library. This is the normal directory
structure seen after VRPN is compiled successfully.
</dd>
<dt><tt>AUDIERE_ROOT</tt></dt>
<dd>
The root directory of an
<a href="http://audiere.sourceforge.net/">Audiere</a> 1.9.3 or newer
installation.
</dd>
<dt><tt>OPENAL_ROOT</tt></dt>
<dd>
The root directory of an
<a href="http://www.openal.org/downloads.html">OpenAL SDK</a> 1.0 or newer
installation.
</dd>
<dt><tt>ALUT_ROOT</tt></dt>
<dd>
The root directory of an
<a href="http://www.openal.org/downloads.html">ALUT SDK</a> 1.0 or newer
installation. With OpenAL 1.1 and newer, ALUT is distributed as a
separate package with its own DLL.
<blockquote>
<b>NOTE:</b> Free ALUT 1.0 includes the OpenAL headers relative to
the <tt>AL</tt> directory, but the OpenAL 1.1 SDK on Windows does not
put its header files in the <tt>AL</tt> subdirectory of
<tt>%OPENAL_ROOT%\include</tt>. It appears that the usal workaround
for this is to move or copy the OpenAL 1.1 SDK header files into the
directory <tt>%OPENAL_ROOT%\include\AL</tt> or to change the Free ALUT
headers. The Juggler build will handle either of these workarounds.
</blockquote>
</dd>
<dt><tt>TRACKD_API_ROOT</tt></dt>
<dd>
The root directory of a Trackd API installation.
</dd>
<dt><tt>GADGET_TRACKD_API_H</tt></dt>
<dd>
The name of the Trackd API header file to be included by the Trackd API
driver. Different versions of the Trackd API have different names for the
header file that proides the type declarations needed to use the Trackd
API driver. The build script <tt>build_windows.py</tt> attempts to detect
automatically what value to use, but it has a finite number of choices
based on known possible values. The form for the value of this environment
variable must be either <tt><file.h></tt> or <tt>"file.h"</tt>
(including the quotes). For example, to compile against Trackd API 5.0,
set this environment variable to the value
<tt><trackdAPI_CC.h></tt>.
</dd>
<dt><tt>FTD2XX_ROOT</tt></dt>
<dd>
The root directory of an
<a href="http://www.ftdichip.com/Drivers/D2XX.htm">FTD2XX SDK</a>
installation. Version 2.02.04 or newer is required to build the driver
for the
<a href="http://www.x-ist.de/noDNA_X-IST.394.0.html?&L=1">noDNA X-IST</a>
data glove.
</dd>
<dt><tt>DOOZER_ROOT</tt></dt>
<dd>
The root directory of a <a href="http://">Doozer 2.1</a> installation.
</dd>
</dl>
<a name="choose_configuration"><h1>4. Choose a Configuration to Build</h1></a>
<p>
After you answer the questions asked by <tt>build_windows.py</tt>, the script
will start up the version of Visual Studio that you have in your path (or
that it detected on your system if your environment does not have the
<tt>devenv.exe</tt> command in your path). Inside the Visual Studio GUI,
you must choose the configuration that you want to build.
</p>
<p>
The chosen target should be either "Debug" or "Release". Otherwise, select
"Batch Build" under the "Build" menu and compile everything all at once. If
you choose to build everything but do not have all the
<a href="#opt_env_vars">optional dependencies</a>, some optional targets
such as device drivers or Java features may fail to build. If this is not
acceptable, you must <a href="#run_build_windows_py">go back to Step 3</a>
and run <tt>build_windows.py</tt> again.
</p>
<a name="install_vrj"><h1>5. Install VR Juggler</h1></a>
<p>
After successfully compiling VR Juggler, <tt>build_windows.py</tt> will ask
if you want to install VR Juggler. On Windows, you must install VR Juggler
to be able to build and run applications. Working out of the development
tree is not possible the way it is on other platforms. If you answer
"yes" to the question of installing VR Juggler, <tt>build_windows.py</tt> will
go through the full process of installing everything that was compiled.
</p>
<a name="install_deps"><h1>6. Install VR Juggler Dependencies</h1></a>
<p>
After VR Juggler is installed, you will be given the option to install
VR Juggler's C++ dependencies. This includes CppDOM, Boost, GMTL, and any
optional packages that were available for compiling additional features. If
you answer "yes" to this question, the dependencies will be installed to a
location of your choice (which can be the same as the VR Juggler installation
directory). This gives you a convenient, single location for referencing all
dependencies from application project files.
</p>
<blockquote>
<b>NOTE:</b> The sample and test applications reference the environment
variable <tt>%VJ_DEPS_DIR%</tt>, so it is highly recommended that you
install the dependencies to a single location unless you have already done
so.
</blockquote>
<p>
<font size="-1"><i>$Id$</i></font>
</p>
</body>