root/juggler/branches/2.2/README-WINDOWS.html

Revision 20693, 15.0 kB (checked in by patrick, 1 year ago)

Updated for the latest FTD2XX drivers which include 64-bit Windows support.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1 <head>
2 <title>Compiling the Juggler Suite Using Visual Studio</title>
3 </head>
4
5 <body>
6
7 <h1>Table of Contents</h1>
8
9 <ul>
10   <li><a href="#intro">Introduction</a></li>
11   <li><a href="#install_python">Install Python</a></li>
12   <li><a href="#run_build_windows_py">Run <tt>build_windows.py</tt></a></li>
13   <li><a href="#choose_configuration">Choose a Configuration to Build</a></li>
14   <li><a href="#install_vrj">Install VR Juggler</a></li>
15   <li><a href="#install_deps">Install VR Juggler Dependencies</a></li>
16 </ul>
17
18 <a name="intro"><h1>1. Introduction to Compiling and Installing VR
19 Juggler</h1></a>
20
21 <p>
22 Building VR Juggler (both the C++ and the Java code) on Windows is
23 straightforward.  A Visual Studio solution has been created that collects
24 each of the redistributable entities into Visual C++ projects.  An overview
25 of the steps for building and installing VR Juggler on Windows follow:
26 </p>
27
28 <ol>
29   <li>
30     Install <a href="http://www.python.org/">Python</a> 2.2 or newer. To build
31     a 64-bit version of VR Juggler on Windows, the 64-bit build of Python 2.5
32     is <i>required</i>.
33   </li>
34   <li>
35     Run <tt>build_windows.py</tt> and fill in at least the paths to the
36     required dependencies.
37   </li>
38   <li>
39     In Visual Studio, choose the configuration(s) to build.
40   </li>
41   <li>
42     Install the compiled libraries, tools, and (optionally) dependencies.
43   </li>
44 </ol>
45
46 <p>
47 Each of the above steps is described in more detail below.
48 </p>
49
50 <a name="install_python"><h1>2. Install Python</h1></a>
51
52 <p>
53 In order to <a href="#run_build_windows_py">run the helper script
54 <tt>build_windows.py</tt></a>, you must have
55 <a href="http://www.python.org/">Python</a> 2.2 or newer installed on your
56 system. (To build a 64-bit version of VR Juggler, the 64-bit version of
57 Python 2.5 <i>must</i> be installed.) Visit the Python website for
58 <a href="http://www.python.org/download/">download and install
59 instructions</a>.
60 </p>
61
62 <a name="run_build_windows_py"><h1>3. Run <tt>build_windows.py</tt></h1></a>
63
64 <p>
65 Once you have Python installed, you can open the folder containing the
66 Juggler Project source in Windows Explorer and double-click on the
67 icon for the script <tt>build_windows.py</tt>.  This script simplifies the
68 process of building VR Juggler on Windows by setting up paths and
69 environment variables based on input that you provide.  It then starts
70 Visual Studio for you, and when the build is complete, it will perform
71 all the necessary installation steps&mdash;including installation of
72 VR Juggler's C++ dependencies into a convenient, centralized location.
73 </p>
74
75 <blockquote>
76 <b>IMPORTANT:</b> To create a 64-bit build on Windows, the command line
77 option <b><tt>--64</tt></b> must be used, or the <q>64-bit Build</q> option
78 in the GUI must be selected.
79 </blockquote>
80
81 <blockquote>
82 <b>NOTE:</b> For the build to work correctly, you must use the
83 <tt>build_windows.py</tt> script.  It does more than just set environment
84 variables.
85 </blockquote>
86
87 <p>
88 Regarding the environment variables, the remainder of this
89 section describes each of the required and optional environment variables
90 used by the Visual Studio build.  You can read through them to get a
91 better understanding of what <tt>build_windows.py</tt> expects from your
92 answers to its questions, or you can
93 <a href="#choose_configuration">skip to the next section</a>.
94 </p>
95
96 <h2>3.1. Set Environment Variables</h2>
97
98 <p>
99 Prior to starting the Visual Studio GUI, several environment variables
100 must be set.  If you run the Python script <tt>build_windows.py</tt>, all of
101 the necessary environment variables will be set (and cached) based on
102 responses you provide to several questions.
103
104 These variables provide paths to external dependencies of the Juggler
105 source code.  There are some environment variables that are required for
106 successful compilation of the Juggler source, and there are some that are
107 optional for getting additional code to compile.
108 </p>
109
110 <h3>3.1.1. Required Environment Variables</h3>
111
112 <p>
113 The required environment variables are as follows:
114 </p>
115
116 <dl>
117   <dt><tt>BOOST_ROOT</tt></dt>
118   <dd>
119     The root directory of an installed copy of
120     <a href="http://www.boost.org/">Boost</a> 1.31.0 or newer.  This must
121     contain a directory named <tt>lib</tt> that contains <i>at least</i>
122     compiled versions of the Boost.Filesystem library.  Refer to the relevant
123     <a href="http://www.boost.org/more/getting_started.html#Build_Install">Boost
124     documentation</a> for instructions on how to get and install Boost.
125   </dd>
126   <dt><tt>BOOST_INCLUDES</tt></dt>
127   <dd>
128     The directory containing the root of the Boost header tree.  For a
129     Boost 1.31.0 installation, this will normally be set to the value of
130     <tt>%BOOST_ROOT%\include\boost-1_31</tt>.  The requirement here is
131     that the value of this environment variable must be the full path to
132     a directory that contains a sub-directory named <tt>boost</tt>, in
133     which the Boost headers will be found.
134   </dd>
135   <dt><tt>BOOST_VERSION</tt></dt>
136   <dd>
137     The version of Boost against which the Juggler code will be compiled.
138     However, this string must use underscores (<tt>_</tt>) instead of
139     periods (<tt>.</tt>), and it should only reference the major and
140     minor version number.  For example, if you are compiling against Boost
141     1.31.2, this environment variable would be set to <tt>1_31</tt>.
142   </dd>
143   <dt><tt>NSPR_ROOT</tt></dt>
144   <dd>
145     The root directory of an installed copy of
146     <a href="http://www.mozilla.org/projects/nspr/">NSPR</a> 4.2 or newer.
147     This must contain a directory named <tt>lib</tt> and a directory
148     named <tt>include</tt>.
149   </dd>
150   <dt><tt>NSPR_INCLUDES</tt></dt>
151   <dd>
152     The directory containing the root of the NSPR header tree. For some NSPR
153     installations, the NSPR headers are in a subdirectory of
154     <tt>%NSPR_ROOT%\include</tt> named <tt>nspr</tt>. In that case, this
155     environment variable must be set to <tt>%NSPR_ROOT%\include\nspr</tt>.
156     Otherwise, it should be set to <tt>%NSPR_ROOT%\include</tt>.
157   </dd>
158   <dt><tt>CPPDOM_ROOT</tt></dt>
159   <dd>
160     The root directory of an installed copy of
161     <a href="http://www.sourceforge.net/projects/xml-cppdom/">CppDOM</a>
162     0.7.8 or newer.  This must contain a directory named <tt>lib</tt> and a
163     directory named <tt>include</tt>.  Within <tt>lib</tt> (or <tt>lib64</tt>
164     for a 64-bit bit build), there must exist the different builds of CppDOM:
165     release DLL (<tt>cppdom-0_7_8.lib</tt> and <tt>cppdom-0_7_8.dll</tt>),
166     debug DLL (<tt>cppddom_d-0_7_8.lib</tt> and <tt>cppdom_d-0_7_8.dll</tt>),
167     static release (<tt>cppdom_s-0_7_8.lib</tt>), and static debug
168     (<tt>cppdom_s_d-0_7_8.lib</tt>).
169   </dd>
170   <dt><tt>CPPDOM_INCLUDES</tt></dt>
171   <dd>
172     The directory containing the root of the CppDOM header tree. For CppDOM
173     0.7.3 and newer, the header tree may be in a versioned sub-directory of
174     <tt>%CPPDOM_ROOT%\include</tt> such as
175     <tt>%CPPDOM_ROOT%\include\cppdom-0.7.3</tt>. The requirement here is
176     that the value of this environment variable must be the full path to
177     a directory that contains a sub-directory named <tt>cppdom</tt>, in
178     which the CppDOM headers will be found.
179   </dd>
180   <dt><tt>GMTL_ROOT</tt></dt>
181   <dd>
182     The root directory of an installed copy of
183     <a href="http://www.sourceforge.net/projects/ggt/">GMTL</a>
184     0.3.2 or newer.  This must contain a directory named <tt>include</tt>
185     which in turn has a subdirectory named <tt>gmtl</tt> containing the
186     GMTL header files.
187   </dd>
188   <dt><tt>GMTL_INCLUDES</tt></dt>
189   <dd>
190     The directory containing the root of the CppDOM header tree. For GMTL
191     0.5.0 and newer, the header tree may be in a versioned sub-directory of
192     <tt>%GMTL_ROOT%\include</tt> such as
193     <tt>%GMTL_ROOT%\include\gmtl-0.5.0</tt>. The requirement here is that the
194     value of this environment variable must be the full path to a directory
195     that contains a sub-directory named <tt>gmtl</tt>, in which the GMTL
196     headers will be found.
197   </dd>
198 </dl>
199
200 <a name="opt_env_vars"><h3>3.1.2. Optional Environment Variables</h3></a>
201
202 <p>
203 The optional environment variables are as follows:
204 </p>
205
206 <dl>
207   <dt><tt>JAVA_HOME</tt></dt>
208   <dd>
209     The root directory of a <a href="http://java.sun.com/j2se/">Java 2 SDK</a>
210     installation.  It is highly recommended that version 1.4.2 or newer be
211     installed.  Version 1.3.1 is the minimum required version.
212   </dd>
213   <dt><tt>JOGL_HOME</tt></dt>
214   <dd>
215     The root directory of a <a href="http://jogl.dev.java.net">Jogl</a>
216     installation.  This directory must contain two files: <tt>jogl.jar</tt>
217     and <tt>jogl-demos-util.jar</tt>.  The default value is
218     <tt>%JAVA_HOME%</tt>.  The minimum required version of Jogl is 1.0.
219   </dd>
220   <dt><tt>JAVA3D_HOME</tt></dt>
221   <dd>
222     The root directory of a
223     <a href="http://java.sun.com/products/java-media/3D/">Java 3D API</a>
224     installation.  Typically, this will be the same as <tt>%JAVA_HOME%</tt>,
225     but that may not always be the case.  The minimum required version of
226     the Java 3D API is 1.3.1.
227   </dd>
228   <dt><tt>PFROOT</tt></dt>
229   <dd>
230     The root directory of an
231     <a href="http://www.sgi.com/software/performer/">OpenGL Performer</a> 3.x
232     installation.  This directory must contain the sub-directories
233     <tt>Include</tt> and <tt>Lib</tt>.  This is the normal structure for a
234     standard OpenGL Performer installation.  This variable is normally set
235     automatically by the OpenGL Performer installation wizard.
236   </dd>
237   <dt><tt>OMNIORB_ROOT</tt></dt>
238   <dd>
239     The root directory of an
240     <a href="http://omniorb.sourceforge.net/">omniORB</a> 4.0.x installation.
241     This directory must contain the sub-directories <tt>bin</tt>,
242     <tt>include</tt>, and <tt>lib</tt>.
243   </dd>
244   <dt><tt>MS_SPEECH_SDK_ROOT</tt></dt>
245   <dd>
246     The root directory of a
247     <a href="http://www.microsoft.com/speech/download/sdk51/">Microsoft Speech
248     SDK</a> installation.  This directory must contain the sub-directories
249     <tt>include</tt> and <tt>lib\i386</tt>.
250   </dd>
251   <dt><tt>VRPN_ROOT</tt></dt>
252   <dd>
253     The root directory of a
254     <a href="http://www.cs.unc.edu/Research/vrpn/">VRPN</a> 6.04 or newer
255     tree.  This directory must contain the sub-directories <tt>quat</tt>
256     and <tt>vrpn</tt>.  In each of those, there must be a sub-directory
257     named <tt>pc_win32</tt>, and within it, there must be sub-directories
258     named <tt>Debug</tt> and <tt>Release</tt>.  These contain the compiled
259     version of the appropriate library.  This is the normal directory
260     structure seen after VRPN is compiled successfully.
261   </dd>
262   <dt><tt>AUDIERE_ROOT</tt></dt>
263   <dd>
264     The root directory of an
265     <a href="http://audiere.sourceforge.net/">Audiere</a> 1.9.3 or newer
266     installation.
267   </dd>
268   <dt><tt>OPENAL_ROOT</tt></dt>
269   <dd>
270     The root directory of an
271     <a href="http://www.openal.org/downloads.html">OpenAL SDK</a> 1.0 or newer
272     installation.
273   </dd>
274   <dt><tt>ALUT_ROOT</tt></dt>
275   <dd>
276     The root directory of an
277     <a href="http://www.openal.org/downloads.html">ALUT SDK</a> 1.0 or newer
278     installation. With OpenAL 1.1 and newer, ALUT is distributed as a
279     separate package with its own DLL.
280
281     <blockquote>
282       <b>NOTE:</b> Free ALUT 1.0 includes the OpenAL headers relative to
283       the <tt>AL</tt> directory, but the OpenAL 1.1 SDK on Windows does not
284       put its header files in the <tt>AL</tt> subdirectory of
285       <tt>%OPENAL_ROOT%\include</tt>. It appears that the usal workaround
286       for this is to move or copy the OpenAL 1.1 SDK header files into the
287       directory <tt>%OPENAL_ROOT%\include\AL</tt> or to change the Free ALUT
288       headers. The Juggler build will handle either of these workarounds.
289     </blockquote>
290   </dd>
291   <dt><tt>TRACKD_API_ROOT</tt></dt>
292   <dd>
293     The root directory of a Trackd API installation.
294   </dd>
295   <dt><tt>GADGET_TRACKD_API_H</tt></dt>
296   <dd>
297     The name of the Trackd API header file to be included by the Trackd API
298     driver. Different versions of the Trackd API have different names for the
299     header file that proides the type declarations needed to use the Trackd
300     API driver. The build script <tt>build_windows.py</tt> attempts to detect
301     automatically what value to use, but it has a finite number of choices
302     based on known possible values. The form for the value of this environment
303     variable must be either <tt>&lt;file.h&gt;</tt> or <tt>"file.h"</tt>
304     (including the quotes). For example, to compile against Trackd API 5.0,
305     set this environment variable to the value
306     <tt>&lt;trackdAPI_CC.h&gt;</tt>.
307   </dd>
308   <dt><tt>FTD2XX_ROOT</tt></dt>
309   <dd>
310     The root directory of an
311     <a href="http://www.ftdichip.com/Drivers/D2XX.htm">FTD2XX SDK</a>
312     installation. Version 2.02.04 or newer is required to build the driver
313     for the
314     <a href="http://www.x-ist.de/noDNA_X-IST.394.0.html?&L=1">noDNA X-IST</a>
315     data glove.
316   </dd>
317   <dt><tt>DOOZER_ROOT</tt></dt>
318   <dd>
319     The root directory of a <a href="http://">Doozer 2.1</a> installation.
320   </dd>
321 </dl>
322
323 <a name="choose_configuration"><h1>4. Choose a Configuration to Build</h1></a>
324
325 <p>
326 After you answer the questions asked by <tt>build_windows.py</tt>, the script
327 will start up the version of Visual Studio that you have in your path (or
328 that it detected on your system if your environment does not have the
329 <tt>devenv.exe</tt> command in your path).  Inside the Visual Studio GUI,
330 you must choose the configuration that you want to build.
331 </p>
332
333 <p>
334 The chosen target should be either "Debug" or "Release".  Otherwise, select
335 "Batch Build" under the "Build" menu and compile everything all at once.  If
336 you choose to build everything but do not have all the
337 <a href="#opt_env_vars">optional dependencies</a>, some optional targets
338 such as device drivers or Java features may fail to build.  If this is not
339 acceptable, you must <a href="#run_build_windows_py">go back to Step 3</a>
340 and run <tt>build_windows.py</tt> again.
341 </p>
342
343 <a name="install_vrj"><h1>5. Install VR Juggler</h1></a>
344
345 <p>
346 After successfully compiling VR Juggler, <tt>build_windows.py</tt> will ask
347 if you want to install VR Juggler.  On Windows, you must install VR Juggler
348 to be able to build and run applications.  Working out of the development
349 tree is not possible the way it is on other platforms.  If you answer
350 "yes" to the question of installing VR Juggler, <tt>build_windows.py</tt> will
351 go through the full process of installing everything that was compiled.
352 </p>
353
354 <a name="install_deps"><h1>6. Install VR Juggler Dependencies</h1></a>
355
356 <p>
357 After VR Juggler is installed, you will be given the option to install
358 VR Juggler's C++ dependencies.  This includes NSPR, CppDOM, Boost, GMTL,
359 and any optional packages that were available for compiling additional
360 features.  If you answer "yes" to this question, the dependencies will
361 be installed to a location of your choice (which can be the same as the
362 VR Juggler installation directory).  This gives you a convenient,
363 single location for referencing all dependencies from application project
364 files.
365 </p>
366
367 <blockquote>
368 <b>NOTE:</b> The sample and test applications reference the environment
369 variable <tt>%VJ_DEPS_DIR%</tt>, so it is highly recommended that you
370 install the dependencies to a single location unless you have already done
371 so.
372 </blockquote>
373
374 <p>
375 <font size="-1"><i>$Id$</i></font>
376 </p>
377
378 </body>
Note: See TracBrowser for help on using the browser.