Changeset 19991

Show
Ignore:
Timestamp:
04/22/07 12:28:20 (2 years ago)
Author:
patrick
Message:

Merges from the trunk:

r19980: Get this almost entirely up to date for VR Juggler 2.2. This

includes new information about building and using VR Juggler
application bundles (using Cocoa) on Mac OS X. I also fixed a whole
bunch of typos.

r19984: Added a screen shot of the Cocoa version of MPApp running and made

a few more adjustments and additions to the document text.

r19989: More work on the description of the environment variables used by

VR Juggler and/or applicatioon build environments. I have changed
the flow of the document somewhat by grouping all the environment
variables together instead of separating them (rather artificially
in my opinion) into "required" and "optional" blocks. At this
point, all the environment variables are optional—with noted
exceptions depending on the context. I think it is important for
users to understand what all the environment variables do and when
their use matters. My hope is that by listing them all together,
readers will not be inclined to skip over those that they think
are unimportant because they are labeled as "optional."

r19990: Fixed a spelling error.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • juggler/branches/2.2/modules/vrjuggler/doc/getting.started.guide/getting.started.guide.xml

    r19951 r19991  
    9393         writing to a tape or for downloading. The format is a standard, and 
    9494         the <command>tar</command>(1) utility is available on every 
    95          UNIX-based platform and on Win32. A free version can be downloaded 
    96          from <ulink url="http://www.gnu.org/">the GNU Project</ulink>. A 
    97          compressed TAR file is made for each VR Juggler distribution, and 
    98          some distributions come in other formats as well. You can always 
    99          count on the availability of a TAR file, though. The TAR files are 
    100          compressed using either GZIP or BZIP2, both of which are standard 
    101          compression formats. The <command>gzip</command>(1) utility is freely 
    102          available from the GNU Project, and the <command>bzip2</command>(1) 
    103          utility can be downloaded for free from <ulink 
    104          url="http://sources.redhat.com/bzip2/">RedHat, Inc.</ulink>. The GNU 
    105          version of TAR has the GZIP and BZIP2 algorithms built in. The 
    106          compression algorithm used can be determined by the file extension. 
    107          Files compressed with GZIP end in <filename>.gz</filename>; files 
    108          compressed with BZIP2 end in <filename>.bz2</filename>.</para> 
     95         UNIX-based platform and on <productname 
     96         class="registered">Windows</productname>. A free version can be 
     97         downloaded from <ulink url="http://www.gnu.org/">the GNU 
     98         Project</ulink>. A compressed TAR file is made for each VR Juggler 
     99         distribution, and some distributions come in other formats as well. 
     100         You can always count on the availability of a TAR file, though. The 
     101         TAR files are compressed using either GZIP or BZIP2, both of which 
     102         are standard compression formats. The <command>gzip</command>(1) 
     103         utility is freely available from the GNU Project, and the 
     104         <command>bzip2</command>(1) utility can be downloaded for free from 
     105         <ulink url="http://sources.redhat.com/bzip2/">Red Hat, Inc.</ulink>. 
     106         The GNU version of TAR has the GZIP and BZIP2 algorithms built in. 
     107         The compression algorithm used can be determined by the file 
     108         extension. Files compressed with GZIP end in 
     109         <filename>.gz</filename>; files compressed with BZIP2 end in 
     110         <filename>.bz2</filename>.</para> 
    109111 
    110112         <para>Once you have downloaded a VR Juggler TAR distribution, you can 
    …… 
    167169 
    168170      <section> 
    169          <title>Installing from a ZIP File (Win32 only)</title> 
    170  
    171          <para>On the Win32 family of platforms, the ZIP format rules. In the 
    172          old days, you would use the PKZIP utility to uncompress and extract a 
    173          ZIP file. Nowadays, most people use <ulink 
    174          url="http://www.winzip.com/">WinZip</ulink> or some other comparable 
     171         <title>Installing from a ZIP File (<productname 
     172         class="registered">Windows</productname> only)</title> 
     173 
     174         <para>On the <productname class="registered">Windows</productname> 
     175         family of platforms, the ZIP format rules. In the old days, you would 
     176         use the PKZIP utility to decompress and extract a ZIP file. Nowadays, 
     177         most people use Windows Explorer, <ulink 
     178         url="http://www.winzip.com/">WinZip</ulink>, or some other comparable 
    175179         graphical interface. This documentation covers only the use of WinZip 
    176180         when extracting a ZIP file.</para> 
    …… 
    274278            terminal window will start those applications just as would be 
    275279            done on other operating systems. At some point, the command line 
    276             verrsions of these applications will probably be removed on Mac OS 
     280            versions of these applications will probably be removed on Mac OS 
    277281            X in favor of exclusive use of the application bundles.</para> 
    278282         </note> 
    …… 
    364368 
    365369            <para>For these types of shells, a <quote>permanent</quote> 
    366             setting for a given variable should usually be done in your .cshrc 
    367             file or in your <filename>.login</filename> file, both of which 
    368             should be in your home directory. In most cases, it is better to 
    369             use <filename>.cshrc</filename> because it is evaluated for every 
     370            setting for a given variable should usually be done in your 
     371            <filename>.cshrc</filename> file or in your 
     372            <filename>.login</filename> file, both of which should be in your 
     373            home directory. In most cases, it is better to use 
     374            <filename>.cshrc</filename> because it is evaluated for every 
    370375            shell instance.</para> 
    371376         </section> 
    …… 
    423428 
    424429            <para>The typical syntax for setting an environment variable from 
    425             the command line (in a DOS shell window) under Win32 is:</para> 
     430            the command line (in a DOS shell window) under <productname 
     431            class="registered">Windows</productname> is:</para> 
    426432 
    427433            <screen>C:\&gt; set &lt;VARIABLE_NAME&gt;=&lt;value&gt;</screen> 
    …… 
    450456C:\WINDOWS;C:\bin;C:\</screen> 
    451457 
    452             <para>For some versions of Windows, a <quote>permanent</quote> 
    453             setting for a given variable should usually be done in 
    454             <filename>C:\AUTOEXEC.BAT</filename>. In newer versions (Windows 
    455             ME in particular) and in the Windows NT line of operating systems, 
    456             the setting is done using the Control Panel. Please refer to the 
    457             next section for more information on that method.</para> 
     458            <para>For some versions of <productname 
     459            class="registered">Windows</productname>, a 
     460            <quote>permanent</quote> setting for a given variable should 
     461            usually be done in <filename>C:\AUTOEXEC.BAT</filename>. In newer 
     462            versions (<productname class="registered">Windows</productname> ME 
     463            in particular) and in the <productname 
     464            class="registered">Windows</productname> NT line of operating 
     465            systems, the setting is done using the Control Panel. Please refer 
     466            to the next section for more information on that method.</para> 
    458467         </section> 
    459468 
    460469         <section> 
    461             <title>Win 32 GUI</title> 
     470            <title><productname class="registered">Windows</productname> 
     471            GUI</title> 
    462472 
    463473            <para>Before reading this section, please be sure to have read 
    464474            <xref linkend="section.envvar.dos" />. This is necessary because 
    465             the Win32 GUI for setting environment variables is simply a 
    466             front-end to that older method and thus uses the same conventions 
    467             and syntax. The versions of Windows to which this subsection 
    468             applies are indicated individually since each is a little 
    469             different. For more detailed information, please refer to the 
    470             Windows online help system and search for <quote>environment 
     475            the <productname class="registered">Windows</productname> GUI for 
     476            setting environment variables is simply a front-end to that older 
     477            method and thus uses the same conventions and syntax. The versions 
     478            of <productname class="registered">Windows</productname> to which 
     479            this subsection applies are indicated individually since each is a 
     480            little different. For more detailed information, please refer to 
     481            the <productname class="registered">Windows</productname> online 
     482            help system and search for <quote>environment 
    471483            variables</quote>.</para> 
    472484 
    473485            <section> 
    474                <title>Windows 2000 and Windows XP</title> 
     486               <title><productname class="registered">Windows</productname> 
     487               2000 and <productname class="registered">Windows</productname> 
     488               XP</title> 
    475489 
    476490               <para>In the Control Panel, open the <guiicon>System</guiicon> 
    477491               icon. Under the <guilabel>Advanced</guilabel> tab, there is a 
    478492               button labeled <guibutton>Environment Variables</guibutton>, 
    479                shown in <xref linkend="figure.win2k.sysprops" /> (the Windows 
    480                XP version is shown in <xref 
    481                linkend="figure.winxp.sysprops" />). Clicking this button opens 
    482                the dialog box shown in <xref 
     493               shown in <xref linkend="figure.win2k.sysprops" /> (the 
     494               <productname class="registered">Windows</productname> XP 
     495               version is shown in <xref linkend="figure.winxp.sysprops" />). 
     496               Clicking this button opens the dialog box shown in <xref 
    483497               linkend="figure.win2k.envvars" />. Here, you can set variables 
    484498               for yourself and, if you have the access privileges, for all 
    …… 
    486500 
    487501               <figure id="figure.win2k.sysprops"> 
    488                   <title>Windows 2000 System Properties Dialog</title> 
     502                  <title><productname class="registered">Windows</productname> 
     503                  2000 System Properties Dialog</title> 
    489504 
    490505                  <mediaobject> 
    …… 
    498513 
    499514               <figure id="figure.winxp.sysprops"> 
    500                   <title>Windows XP System Properties Dialog</title> 
     515                  <title><productname class="registered">Windows</productname> 
     516                  XP System Properties Dialog</title> 
    501517 
    502518                  <mediaobject> 
    …… 
    510526 
    511527               <figure id="figure.win2k.envvars"> 
    512                   <title>Windows Environment Variable Editor Dialog</title> 
     528                  <title><productname class="registered">Windows</productname> 
     529                  Environment Variable Editor Dialog</title> 
    513530 
    514531                  <mediaobject> 
    …… 
    520537                  </mediaobject> 
    521538               </figure> 
    522  
    523                <para>To set up VR Juggler, the environment variable 
    524                <envar>VJ_BASE_DIR</envar> needs to be set, probably for all 
    525                users, though it depends very much on local system 
    526                requirements. For this example, let us say that the Win32 
    527                version of VR Juggler is installed in the 
    528                <filename>D:\</filename> directory. As such, we will set 
    529                <envar>VJ_BASE_DIR</envar> as shown in <xref 
    530                linkend="figure.win2k.envvar.set" />. 
    531                <envar>VJ_DEPS_DIR</envar> is set similarly.</para> 
    532  
    533                <figure id="figure.win2k.envvar.set"> 
    534                   <title>Setting <envar>VJ_BASE_DIR</envar> on Windows</title> 
    535  
    536                   <mediaobject> 
    537                      <imageobject> 
    538                         <imagedata align="center" 
    539                                    fileref="figures/Window.EnvironmentVariables.VJ_BASE_DIR.png" 
    540                                    format="PNG" /> 
    541                      </imageobject> 
    542                   </mediaobject> 
    543                </figure> 
    544539            </section> 
    545540 
    …… 
    552547               variables for yourself and, if you have the access privileges, 
    553548               for all users. The GUI is similar to that shown above for 
    554                Windows 2000.</para> 
     549               <productname class="registered">Windows</productname> 
     550               2000.</para> 
    555551            </section> 
    556552         </section> 
    …… 
    560556 
    561557            <para>On Mac OS X, environment variables can be set in two 
    562             different ways, just as on Windows. They can be set as 
     558            different ways, just as on <productname 
     559            class="registered">Windows</productname>. They can be set as 
    563560            <quote>global</quote> environment variables available to all 
    564561            applications launched from the Finder, or they can be set within a 
    …… 
    630627 
    631628      <section id="section.envvars.required"> 
    632          <title>Required Environment Variables</title> 
     629         <title>Relevant Environment Variables</title> 
    633630 
    634631         <variablelist> 
    635632            <varlistentry> 
    636                <term>VJ_BASE_DIR</term> 
     633               <term>LD_LIBRARY_PATH (UNIX/Linux only)</term> 
     634 
     635               <term>DYLD_LIBRARY_PATH (Mac OS X only)</term> 
    637636 
    638637               <listitem> 
    639                   <para>The environment variable <envar>VJ_BASE_DIR</envar> 
    640                   tells a VR Juggler application where to find important data 
    641                   files. It is required to compile and run any Juggler 
    642                   application. It should be set to the base directory of the 
    643                   installed VR Juggler library. For example, if you downloaded 
    644                   a UNIX version of VR Juggler 2.0 and extracted it to the 
    645                   directory <filename>/home/software</filename>, you would set 
    646                   <envar>VJ_BASE_DIR</envar> with this command:</para> 
    647  
    648                   <screen>% VJ_BASE_DIR = /home/software/vrjuggler-2.0</screen> 
    649  
    650                   <para>The last component of the path depends on the 
    651                   particular version of Juggler you have downloaded.</para> 
    652  
    653                   <para>If you downloaded and built VR Juggler from the source 
    654                   code, the compilation creates a directory called 
    655                   <filename>instlinks</filename> which can be used as a VR 
    656                   Juggler base:</para> 
    657  
    658                   <screen>% VJ_BASE_DIR = $HOME/juggler/my_build_dir/instlinks</screen> 
     638                  <para>UNIX/Linux systems use these environment variables to 
     639                  find dynamically loaded libraries, such as 
     640                  <filename>libvrj-2_2.so</filename>. Unless you are building 
     641                  everything with static libraries, you will need to set these 
     642                  to include the VR Juggler library directory. An example of 
     643                  setting the library path is as follows:</para> 
     644 
     645                  <screen>% LD_LIBRARY_PATH = $VJ_BASE_DIR/lib</screen> 
     646 
     647                  <para>This is only needed if the Juggler shared libraries 
     648                  are not found by the runtime loader by default. If the 
     649                  Juggler modules were installed using package management such 
     650                  as RPM, then it will not be necessary to set 
     651                  <envar>LD_LIBRARY_PATH</envar>. Setting 
     652                  <envar>DYLD_LIBRARY_PATH</envar> on Mac OS X will probably 
     653                  be necessary even when using the OS X installer 
     654                  package.</para> 
    659655               </listitem> 
    660656            </varlistentry> 
    661657 
    662658            <varlistentry> 
    663                <term>VJ_DEPS_DIR</term> 
     659               <term>PATH</term> 
    664660 
    665661               <listitem> 
    666                   <para>This variable provides the path to the complete set of 
    667                   bundled VR Juggler dependencies (Boost, CppDOM, OpenAL, 
    668                   etc.). It is used by scripts such as 
    669                   <command>vrjuggler-config</command> and by the Visual C++ 
    670                   project files that come with the sample applications. If you 
    671                   downloaded the dependencies as a separate package, set this 
    672                   environment variable to the path where that package was 
    673                   installed. If the dependencies are bundled in the same tree 
    674                   as VR Juggler, then this environment variable does not have 
    675                   to be set.</para> 
     662                  <para>On <productname 
     663                  class="registered">Windows</productname>, the 
     664                  <envar>PATH</envar> environment variable is used in the same 
     665                  way that <envar>LD_LIBRARY_PATH</envar> is used on platforms 
     666                  such as Linux. Thus, the <filename>bin</filename> and 
     667                  <filename>lib</filename> subdirectories of the VR Juggler 
     668                  installation need to be in your path in order for the 
     669                  Juggler DLLs and the <command>vrjconfig</command> command to 
     670                  be found. For non-Windows platforms, it is a good idea to 
     671                  have the Juggler <filename>bin</filename> directory in your 
     672                  path so that the <command>vrjconfig</command> command can be 
     673                  found from the command line.</para> 
    676674               </listitem> 
    677675            </varlistentry> 
    678676 
    679677            <varlistentry> 
    680                <term>PATH</term> 
     678               <term>FLAGPOLL_PATH</term> 
    681679 
    682680               <listitem> 
    683681                  <para>To compile any of the sample applications, the 
    684                   <envar>$VJ_BASE_DIR/bin</envar> directory must be added to 
    685                   your <envar>PATH</envar> as follows:</para> 
     682                  directory containing the Juggler <filename>.fpc</filename> 
     683                  files for <ulink 
     684                  url="https://realityforge.vrsource.org/view/FlagPoll/WebHome">Flagpoll</ulink> 
     685                  must be able to be found. By default, the 
     686                  <command>flagpoll</command> utility searches 
     687                  <filename>/usr/lib/flagpoll</filename>, 
     688                  <filename>/usr/lib64/flagpoll</filename>, 
     689                  <filename>/usr/share/flagpoll</filename>, 
     690                  <filename>/usr/lib/pkgconfig</filename>, 
     691                  <filename>/usr/lib64/pkgconfig</filename>, and 
     692                  <filename>/usr/share/pkgconfig</filename>. It also scans the 
     693                  directories listed in <envar>LD_LIBRARY_PATH</envar> 
     694                  (<envar>DYLD_LIBRARY_PATH</envar> on Mac OS X) for 
     695                  <filename>flagpoll</filename> and 
     696                  <filename>pkgconfig</filename> subdirectories. If you 
     697                  already have <envar>LD_LIBRARY_PATH</envar> (or 
     698                  <envar>DYLD_LIBRARY_PATH</envar>) set correctly or you have 
     699                  Juggler installed in <filename>/usr</filename>, then there 
     700                  is no need to set <envar>FLAGPOLL_PATH</envar>.</para> 
    686701 
    687702                  <screen>% PATH = $PATH:$VJ_BASE_DIR/bin</screen> 
    …… 
    706721               <listitem> 
    707722                  <para>The <envar>JDK_HOME</envar> environment variable is 
    708                   required by the script that starts VRJConfig, the VR Juggler 
    709                   configuration program. If Java is installed on your system, 
    710                   <envar>JDK_HOME</envar> may already be set. If not, it needs 
    711                   to be set to the base of the Java installation.</para> 
     723                  required by the script that starts 
     724                  <application>VRJConfig</application>, the VR Juggler 
     725                  configuration program. If <productname>Java</productname> is 
     726                  installed on your system, <envar>JDK_HOME</envar> may 
     727                  already be set. If not, it needs to be set to the base of 
     728                  the <productname>Java</productname> installation.</para> 
    712729               </listitem> 
    713730            </varlistentry> 
    714731 
    715732            <varlistentry> 
    716                <term>LD_LIBRARY_PATH (UNIX/Linux only)</term> 
    717  
    718                <term>DYLD_LIBRARY_PATH (Darwin/Mac OS X only)</term> 
    719  
    720                <term>LD_LIBRARYN32_PATH (IRIX only)</term> 
    721  
    722                <term>LD_LIBRARY64_PATH (IRIX only)</term> 
     733               <term>VJ_BASE_DIR</term> 
    723734 
    724735               <listitem> 
    725                   <para>UNIX/Linux systems use these environment variables to 
    726                   find dynamically loaded libraries, such as 
    727                   <filename>libvrj.so</filename>. Unless you are building 
    728                   everything with static libraries, you will need to set these 
    729                   to include the VR Juggler library directory (under 
    730                   <envar>VJ_BASE_DIR</envar>). IRIX supports several 
    731                   Application Binary Interfaces (ABIs). VR Juggler supports 
    732                   only the N32 and 64 formats, and there are different library 
    733                   path variables for each. The N32 ABI uses the 
    734                   <envar>LD_LIBRARYN32_PATH</envar> variable, and the 64 ABI 
    735                   uses <envar>LD_LIBRARY64_PATH</envar>. An example of setting 
    736                   the library path is as follows:</para> 
    737  
    738                   <screen>% LD_LIBRARY_PATH = $VJ_BASE_DIR/lib</screen> 
    739  
    740                   <para>If you have <envar>VJ_DEPS_DIR</envar> set and it is 
    741                   not the same as <envar>VJ_BASE_DIR</envar>, then 
    742                   <envar>$VJ_DEPS_DIR/lib</envar> also needs to be in 
    743                   <envar>LD_LIBRARY_PATH</envar>.</para> 
    744  
    745                   <note> 
    746                      <para>On some SGI systems running IRIX, users of the 
    747                      MIPSpro Compilers (version 7.3) may need to add another 
    748                      directory as follows:</para> 
    749  
    750                      <screen>% LD_LIBRARY_PATH = $LD_LIBRARY_PATH:/usr/lib32/cmplrs:$VJ_BASE_DIR/lib32</screen> 
    751                   </note> 
     736                  <para>The environment variable <envar>VJ_BASE_DIR</envar> 
     737                  plays identifiers where VR Juggler is installed. This 
     738                  information is used for the following purposes:</para> 
     739 
     740                  <itemizedlist> 
     741                     <listitem> 
     742                        <para>Visual C++ project files used for building VR 
     743                        Juggler sample applications on <productname 
     744                        class="registered">Windows</productname> reference 
     745                        <envar>VJ_BASE_DIR</envar> for the header and library 
     746                        search paths. In this context, 
     747                        <envar>VJ_BASE_DIR</envar> is 
     748                        <emphasis>required</emphasis>.</para> 
     749                     </listitem> 
     750 
     751                     <listitem> 
     752                        <para>Important data files and plug-ins needed for 
     753                        proper execution are searched for at run time relative 
     754                        to the path identified by <envar>VJ_BASE_DIR</envar>. 
     755                        As of VR Juggler 2.2, this usage of 
     756                        <envar>VJ_BASE_DIR</envar> has been diminished 
     757                        greatly. The remainder of the description of 
     758                        <envar>Vj_BASE_DIR</envar> explains when it may need 
     759                        to be set and when the default will be more than 
     760                        sufficient.</para> 
     761                     </listitem> 
     762                  </itemizedlist> 
     763 
     764                  <para>When using a pre-packaged version of VR Juggler for 
     765                  non-<productname class="registered">Windows</productname> 
     766                  platforms, the installation path is at the time of package 
     767                  construction. Therefore, there is no need for the Juggler 
     768                  libraries to be told at run time where they are installed. 
     769                  If VR Juggler is being used on a non-<productname 
     770                  class="registered">Windows</productname> platform and was 
     771                  <emphasis>not</emphasis> installed using packaging such as 
     772                  RPM or a Mac OS X package, then <envar>VJ_BASE_DIR</envar> 
     773                  may be necessary to execute applications 
     774                  successfully.</para> 
     775 
     776                  <para>On <productname 
     777                  class="registered">Windows</productname>, the Juggler DLLs 
     778                  (<filename>vpr-2_0.dll</filename>, 
     779                  <filename>jccl-1_2.dll</filename>, 
     780                  <filename>vrj-2_2.dll</filename>, etc.) determine on their 
     781                  own where they are installed when they are attached to the 
     782                  application process. As such, the <productname 
     783                  class="registered">Windows</productname> DLLs will 
     784                  automatically set the environment variable(s) that they need 
     785                  to function properly. If an environment variable is already 
     786                  set, then its setting will <emphasis>not</emphasis> be 
     787                  changed by the DLL when it is attached to the application 
     788                  process.</para> 
     789 
     790                  <tip> 
     791                     <para>If problems occur at run time with 
     792                     <filename>.jdef</filename> files or plug-ins failing to 
     793                     be found, then setting <envar>VJ_BASE_DIR</envar> will 
     794                     almost certainly fix the problems. If the Juggler 
     795                     installation is corrupted or non-standard (e.g., spread 
     796                     out across several directory trees), then using 
     797                     <envar>VJ_BASE_DIR</envar> in conjunction with some of 
     798                     the environment variables described below will probably 
     799                     prove helpful.</para> 
     800                  </tip> 
     801 
     802                  <para>If <envar>VJ_BASE_DIR</envar> needs to be set, then it 
     803                  must be set to the base directory of the installed Juggler 
     804                  Suite. For example, if you downloaded a UNIX version of VR 
     805                  Juggler 2.2 and extracted it to the directory 
     806                  <filename>/home/software</filename>, you would set 
     807                  <envar>VJ_BASE_DIR</envar> with this command:</para> 
     808 
     809                  <screen>% VJ_BASE_DIR = /home/software/vrjuggler-2.2</screen> 
     810 
     811                  <para>The last component of the path depends on the 
     812                  particular version of Juggler you have downloaded.</para> 
     813 
     814                  <para>If you downloaded and built VR Juggler from the source 
     815                  code, the compilation creates a directory called 
     816                  <filename>instlinks</filename> which can be used as a VR 
     817                  Juggler base:</para> 
     818 
     819                  <screen>% VJ_BASE_DIR = $HOME/juggler/my_build_dir/instlinks</screen> 
     820 
     821                  <important> 
     822                     <para>When working from withing the build tree and using 
     823                     <filename>instlinks</filename>, 
     824                     <envar>VJ_BASE_DIR</envar> is 
     825                     <emphasis>required</emphasis>.</para> 
     826                  </important> 
    752827               </listitem> 
    753828            </varlistentry> 
    754          </variablelist> 
    755       </section> 
    756  
    757       <section id="section.envvars.optional"> 
    758          <title>Optional Related Environment Variables</title> 
    759  
    760          <variablelist> 
     829 
     830            <varlistentry> 
     831               <term>VJ_DEPS_DIR</term> 
     832 
     833               <listitem> 
     834                  <para>In VR Juggler 2.0, the <envar>VJ_DEPS_DIR</envar> 
     835                  environment variable was introduced as a crutch for finding 
     836                  dependencies such as Boost and CppDOM when building and 
     837                  running VR Juggler applications. That was before 
     838                  <application>Flagpoll</application> and RPMs, however. Now, 
     839                  the recommended usage of VR Juggler is to use 
     840                  <application>Flagpoll</application> for compiling 
     841                  applications and to install everything needed using package 
     842                  management. <application>Flagpoll</application> can find 
     843                  dependencies on its own, and the 
     844                  <envar>FLAGPOLL_PATH</envar> environment variable (see 
     845                  above) extends the search path when necessary. Thus, on 
     846                  platforms where <application>Flagpoll</application> is being 
     847                  used, <envar>VJ_DEPS_DIR</envar> plays no role.</para> 
     848 
     849                  <para>This does not currently apply to <productname 
     850                  class="registered">Windows</productname>, unfortunately. 
     851                  Until <application>Flagpoll</application> is ready for usage 
     852                  on <productname class="registered">Windows</productname>, 
     853                  the primary build mechanism will continue to be Visual 
     854                  Studio<footnote> 
     855                        <para>Visual Studio will probably always be the 
     856                        recommended tool for compiling VR Juggler applications 
     857                        on <productname 
     858                        class="registered">Windows</productname> even after 
     859                        <application>Flagpoll</application> has <productname 
     860                        class="registered">Windows</productname> support. The 
     861                        idea is to support <emphasis>both</emphasis> Visual 
     862                        Studio and <application>Flagpoll</application> on 
     863                        <productname 
     864                        class="registered">Windows</productname>.</para> 
     865                     </footnote>. To make things simple in Visual C++ project 
     866                  files, environment variables can hide path details. The 
     867                  <envar>VJ_DEPS_DIR</envar> environment variable provides the 
     868                  path to the complete set of bundled VR Juggler dependencies 
     869                  (Boost, CppDOM, OpenAL, etc.). It is used by the Visual C++ 
     870                  project files that come with the sample applications. If you 
     871                  downloaded the dependencies as a separate package, set this 
     872                  environment variable to the path where that package was 
     873                  installed. If the dependencies are bundled in the same tree 
     874                  as VR Juggler, then this environment variable does not have 
     875                  to be set.</para> 
     876               </listitem> 
     877            </varlistentry> 
     878 
    761879            <varlistentry> 
    762880               <term>VJ_CFG_PATH</term> 
    …… 
    823941                     interpreter.</para> 
    824942                  </sidebar> 
    825                </listitem> 
    826             </varlistentry> 
    827  
    828             <varlistentry> 
    829                <term>SNX_BASE_DIR</term> 
    830  
    831                <listitem> 
    832                   <para>The environment variable that defines the root 
    833                   directory of a Sonix installation. At run time, Sonix uses 
    834                   this variable to search for plug-ins. If it is not set, 
    835                   Sonix plug-in loading may fail. In genereal, it will be set 
    836                   to the same value as <envar>VJ_BASE_DIR</envar>.</para> 
    837943               </listitem> 
    838944            </varlistentry> 
    …… 
    9241030                  cannot be used with SPROC threads. In that case, there will 
    9251031                  not be a plug-in available to load, and setting this 
    926                   enviornment variable ultimately prevents the IRIX run-time 
     1032                  environment variable ultimately prevents the IRIX run-time 
    9271033                  loader from printing a nasty message saying as much. On Mac 
    9281034                  OS X 10.3, static data initialization in omniORB fails when 
    …… 
    9571063                  cannot be used with SPROC threads. In that case, there will 
    9581064                  not be a plug-in available to load, and setting this 
    959                   enviornment variable ultimately prevents the IRIX run-time 
     1065                  environment variable ultimately prevents the IRIX run-time 
    9601066                  loader from printing a nasty message saying as much. On Mac 
    9611067                  OS X 10.3, static data initialization in omniORB fails when 
    …… 
    11031209         application on the command line requires the use of GNU make (often 
    11041210         installed as <command>gmake</command>) so that it will work on all 
    1105          supported platforms including Win32. Using Microsoft Visual Studio 
    1106          will only work on Win32.</para> 
     1211         supported platforms. Using Microsoft Visual Studio will only work on 
     1212         <productname class="registered">Windows</productname>.</para> 
    11071213 
    11081214         <section> 
    …… 
    11321238            <screen>% gmake</screen> 
    11331239 
     1240            <para>On Mac OS X, enter the following:</para> 
     1241 
     1242            <screen>% make bundle</screen> 
     1243 
    11341244            <para>The compile process will then begin. As noted above, the use 
    1135             of GNU make is required to use the distributed makefiles. With 
    1136             Cygwin, GNU make is simply <command>make</command>. If you have 
    1137             your system set up properly, it will complete with an executable 
    1138             <filename>MPApp</filename> file (or <filename>MPApp.exe</filename> 
    1139             on Win32) in the directory. Now that you have a program compiled, 
    1140             it is time to learn how to run it. (Readers who are not using 
    1141             Visual Studio can skip ahead to <xref 
     1245            of GNU make is required to use the distributed makefiles. Now that 
     1246            you have a program compiled, it is time to learn how to run it. 
     1247            (Readers who are not using Visual Studio can skip ahead to <xref 
    11421248            linkend="chapter.app.running" />.)</para> 
    11431249         </section> 
    …… 
    13911497               <filename>sim.wand.mixin.jconf</filename>. Note that it uses a 
    13921498               single display window for all input.</para> 
    1393  
    1394                <note> 
    1395                   <para>At the time of this writing, this configuration file 
    1396                   only works with OpenGL, OpenSG, and Open Scene Graph 
    1397                   applications on UNIX, Win32, and Mac OS X. It will not work 
    1398                   with OpenGL Performer.</para> 
    1399                </note> 
    14001499            </listitem> 
    14011500         </itemizedlist> 
    …… 
    14151514            <screen>% MPApp sim.base.jconf sim.wand.mixin.jconf</screen> 
    14161515 
    1417             <para>You will notice that no paths are specified for finding the 
     1516            <para>On Mac OS X, the command would be the following:</para> 
     1517 
     1518            <screen>% MPApp.app/Contents/MacOS/MPApp sim.base.jconf sim.wand.mixin.jconf</screen> 
     1519 
     1520            <para>Notice that no paths are specified for finding the 
    14181521            configuration files. The full paths to the configuration files is 
    14191522            not necessary because the default search path will correctly find 
    14201523            these files in 
    1421             <filename>$VJ_BASE_DIR/share/vrjuggler/data/configFiles</filename>. 
    1422             Beginning users will typically want to reference the example 
    1423             configuration files in that directory. As you get more comfortable 
    1424             with VR Juggler and its configuration system, you may want to make 
    1425             your own modified files and put them in the directory 
    1426             <filename>$HOME/.vjconfig</filename>. The environment variable 
    1427             <envar>VJ_CFG_PATH</envar> is useful in providing a search path 
    1428             for finding your configuration files. (Refer to <xref 
    1429             linkend="section.envvars.optional" /> for more information on 
    1430             using <envar>VJ_CFG_PATH</envar>). To simplify running 
    1431             applications, you may want to make a shell script (or batch file 
    1432             as appropriate) that does all the work of passing configuration 
    1433             files and common command-line arguments.</para> 
     1524            <filename>$VJ_BASE_DIR\share\vrjuggler\data\configFiles</filename> 
     1525            on Windows or 
     1526            <filename>$VJ_BASE_DIR/share/vrjuggler-2.2/data/configFiles</filename> 
     1527            on all other platforms. Beginning users will typically want to 
     1528            reference the example configuration files in that directory. As 
     1529            you get more comfortable with VR Juggler and its configuration 
     1530            system, you may want to make your own modified files and put them 
     1531            in the directory <filename>$HOME/.vrjconfig</filename>. The 
     1532            environment variable <envar>VJ_CFG_PATH</envar> is useful in 
     1533            providing a search path for finding your configuration files. 
     1534            (Refer to <xref linkend="section.envvars.optional" /> for more 
     1535            information on using <envar>VJ_CFG_PATH</envar>). To simplify 
     1536            running applications, you may want to make a shell script (or 
     1537            batch file as appropriate) that does all the work of passing 
     1538            configuration files and common command-line arguments.</para> 
    14341539 
    14351540            <para>As the application starts, you will see a status output 
    …… 
    14501555            head; and the pointer is the user's hand. In <xref 
    14511556            linkend="figure.MPApp.running" />, we show what this looks on a 
    1452             RedHat Linux 7.2 desktop for comparison with what you are seeing. 
     1557            Red Hat Linux 7.2 desktop for comparison with what you are seeing. 
    14531558            Note that the head and wand are only rendered in the simulator 
    14541559            windows. They are present because head and wand input are being 
    …… 
    14591564 
    14601565            <figure id="figure.MPApp.running"> 
    1461                <title>MPApp running on a Linux desktop with multiple input 
    1462                windows</title> 
     1566               <title>MPApp Running on a Linux Desktop with Multiple Input 
     1567               Windows</title> 
    14631568 
    14641569               <mediaobject> 
    …… 
    14711576            </figure> 
    14721577 
    1473             <para>With VR Juggler 1.1/2.0, it is possible to use a single 
    1474             window for graphics and for input. To use such a configuration, 
    1475             execute MPApp as follows:</para> 
     1578            <para>With VR Juggler 2.0 and beyond, it is possible to use a 
     1579            single window for graphics and for input. To use such a 
     1580            configuration, execute MPApp as follows:</para> 
    14761581 
    14771582            <screen>% MPApp standalone.jconf</screen> 
     1583 
     1584            <para>On Mac OS X, execute it this way:</para> 
     1585 
     1586            <screen>% MPApp.app/Contents/MacOS/MPApp standalone.jconf</screen> 
    14781587 
    14791588            <para>This time, only a single window opens, as shown in <xref 
    …… 
    14841593 
    14851594            <figure id="figure.MPApp.running.single"> 
    1486                <title>MPApp running on a Linux desktop with one window</title> 
     1595               <title>MPApp Running on a Linux Desktop with One Window</title> 
    14871596 
    14881597               <mediaobject> 
    …… 
    15501659 
    15511660            <section> 
     1661               <title>Running an Application on Mac OS X with Cocoa 
     1662               Windows</title> 
     1663 
     1664               <para>In VR juggler 2.2, Cocoa support has been added for Mac 
     1665               OS X usage. This gives much better results than the previous 
     1666               reliance upon the X Window System. The interface for VR Juggler 
     1667               applications on Mac OS X is noticeably different than other 
     1668               platforms, however. We will explore those differences in this 
     1669               section.</para> 
     1670 
     1671               <para>There are two key differences with VR Juggler on Mac OS X 
     1672               from other platforms:</para> 
     1673 
     1674               <orderedlist> 
     1675                  <listitem> 
     1676                     <para>Applications are constructed as bundles</para> 
     1677                  </listitem> 
     1678 
     1679                  <listitem> 
     1680                     <para>Every application has the usual Mac OS application 
     1681                     menu</para> 
     1682                  </listitem> 
     1683