Changeset 19980

Show
Ignore:
Timestamp:
04/21/07 15:05:43 (2 years ago)
Author:
patrick
Message:

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.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • juggler/trunk/modules/vrjuggler/doc/getting.started.guide/getting.started.guide.xml

    r19952 r19980  
    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 
    …… 
    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 (Darwin/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> 
    712                </listitem> 
    713             </varlistentry> 
    714  
    715             <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> 
    723  
    724                <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> 
     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> 
    752729               </listitem> 
    753730            </varlistentry> 
    …… 
    759736 
    760737         <variablelist> 
     738            <varlistentry> 
     739               <term>VJ_BASE_DIR</term> 
     740 
     741               <listitem> 
     742                  <para>The environment variable <envar>VJ_BASE_DIR</envar> 
     743                  tells a VR Juggler application where to find important data 
     744                  files. As of VR Juggler 2.2, the need for 
     745                  <envar>VJ_BASE_DIR</envar> has been greatly diminished. When 
     746                  using a pre-packaged version of VR Juggler for 
     747                  non-<productname class="registered">Windows</productname> 
     748                  platforms, the installation path is known when the software 
     749                  was built. Therefore, there is no need for the software to 
     750                  be told at run time where it is installed. If VR Juggler is 
     751                  being used on a non-<productname 
     752                  class="registered">Windows</productname> platform and was 
     753                  <emphasis>not</emphasis> installed using packaging such as 
     754                  RPM or a Mac OS X package, then <envar>VJ_BASE_DIR</envar> 
     755                  may be necessary to execute applications 
     756                  successfully.</para> 
     757 
     758                  <para>On <productname 
     759                  class="registered">Windows</productname>, the DLLs determine 
     760                  on their own where they are installed when the are attached 
     761                  to the application process. As such, the <productname 
     762                  class="registered">Windows</productname> DLLs will 
     763                  automatically set the environment variables that they need 
     764                  to function properly on their own. If an environment 
     765                  variable is already set, then its setting will 
     766                  <emphasis>not</emphasis> be changed by the DLL when it is 
     767                  attached to the application process.</para> 
     768 
     769                  <tip> 
     770                     <para>If problems occur at run time with 
     771                     <filename>.jdef</filename> files or plug-ins failing to 
     772                     be found, then setting <envar>VJ_BASE_DIR</envar> will 
     773                     almost certainly fix the problems. If the Juggler 
     774                     installation is corrupted or non-standard (e.g., spread 
     775                     out across several directory trees), then using some of 
     776                     the environment variables described below will probably 
     777                     prove helpful.</para> 
     778                  </tip> 
     779 
     780                  <para>If <envar>VJ_BASE_DIR</envar> needs to be set, then it 
     781                  must be set to the base directory of the installed Juggler 
     782                  Suite. For example, if you downloaded a UNIX version of VR 
     783                  Juggler 2.2 and extracted it to the directory 
     784                  <filename>/home/software</filename>, you would set 
     785                  <envar>VJ_BASE_DIR</envar> with this command:</para> 
     786 
     787                  <screen>% VJ_BASE_DIR = /home/software/vrjuggler-2.2</screen> 
     788 
     789                  <para>The last component of the path depends on the 
     790                  particular version of Juggler you have downloaded.</para> 
     791 
     792                  <para>If you downloaded and built VR Juggler from the source 
     793                  code, the compilation creates a directory called 
     794                  <filename>instlinks</filename> which can be used as a VR 
     795                  Juggler base:</para> 
     796 
     797                  <screen>% VJ_BASE_DIR = $HOME/juggler/my_build_dir/instlinks</screen> 
     798 
     799                  <important> 
     800                     <para>When working from withing the build tree and using 
     801                     <filename>instlinks</filename>, 
     802                     <envar>VJ_BASE_DIR</envar> is 
     803                     <emphasis>required</emphasis>.</para> 
     804                  </important> 
     805               </listitem> 
     806            </varlistentry> 
     807 
    761808            <varlistentry> 
    762809               <term>VJ_CFG_PATH</term> 
    …… 
    823870                     interpreter.</para> 
    824871                  </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> 
    837872               </listitem> 
    838873            </varlistentry> 
    …… 
    924959                  cannot be used with SPROC threads. In that case, there will 
    925960                  not be a plug-in available to load, and setting this 
    926                   enviornment variable ultimately prevents the IRIX run-time 
     961                  environment variable ultimately prevents the IRIX run-time 
    927962                  loader from printing a nasty message saying as much. On Mac 
    928963                  OS X 10.3, static data initialization in omniORB fails when 
    …… 
    957992                  cannot be used with SPROC threads. In that case, there will 
    958993                  not be a plug-in available to load, and setting this 
    959                   enviornment variable ultimately prevents the IRIX run-time 
     994                  environment variable ultimately prevents the IRIX run-time 
    960995                  loader from printing a nasty message saying as much. On Mac 
    961996                  OS X 10.3, static data initialization in omniORB fails when 
    …… 
    11031138         application on the command line requires the use of GNU make (often 
    11041139         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> 
     1140         supported platforms. Using Microsoft Visual Studio will only work on 
     1141         <productname class="registered">Windows</productname>.</para> 
    11071142 
    11081143         <section> 
    …… 
    11321167            <screen>% gmake</screen> 
    11331168 
     1169            <para>On Mac OS X, enter the following:</para> 
     1170 
     1171            <screen>% make bundle</screen> 
     1172 
    11341173            <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 
     1174            of GNU make is required to use the distributed makefiles. Now that 
     1175            you have a program compiled, it is time to learn how to run it. 
     1176            (Readers who are not using Visual Studio can skip ahead to <xref 
    11421177            linkend="chapter.app.running" />.)</para> 
    11431178         </section> 
    …… 
    13911426               <filename>sim.wand.mixin.jconf</filename>. Note that it uses a 
    13921427               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> 
    14001428            </listitem> 
    14011429         </itemizedlist> 
    …… 
    14151443            <screen>% MPApp sim.base.jconf sim.wand.mixin.jconf</screen> 
    14161444 
    1417             <para>You will notice that no paths are specified for finding the 
     1445            <para>On Mac OS X, the command would be the following:</para> 
     1446 
     1447            <screen>% MPApp.app/Contents/MacOS/MPApp sim.base.jconf sim.wand.mixin.jconf</screen> 
     1448 
     1449            <para>Notice that no paths are specified for finding the 
    14181450            configuration files. The full paths to the configuration files is 
    14191451            not necessary because the default search path will correctly find 
    14201452            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> 
     1453            <filename>$VJ_BASE_DIR\share\vrjuggler\data\configFiles</filename> 
     1454            on Windows or 
     1455            <filename>$VJ_BASE_DIR/share/vrjuggler-2.2/data/configFiles</filename> 
     1456            on all other platforms. Beginning users will typically want to 
     1457            reference the example configuration files in that directory. As 
     1458            you get more comfortable with VR Juggler and its configuration 
     1459            system, you may want to make your own modified files and put them 
     1460            in the directory <filename>$HOME/.vrjconfig</filename>. The 
     1461            environment variable <envar>VJ_CFG_PATH</envar> is useful in 
     1462            providing a search path for finding your configuration files. 
     1463            (Refer to <xref linkend="section.envvars.optional" /> for more 
     1464            information on using <envar>VJ_CFG_PATH</envar>). To simplify 
     1465            running applications, you may want to make a shell script (or 
     1466            batch file as appropriate) that does all the work of passing 
     1467            configuration files and common command-line arguments.</para> 
    14341468 
    14351469            <para>As the application starts, you will see a status output 
    …… 
    14501484            head; and the pointer is the user's hand. In <xref 
    14511485            linkend="figure.MPApp.running" />, we show what this looks on a 
    1452             RedHat Linux 7.2 desktop for comparison with what you are seeing. 
     1486            Red Hat Linux 7.2 desktop for comparison with what you are seeing. 
    14531487            Note that the head and wand are only rendered in the simulator 
    14541488            windows. They are present because head and wand input are being 
    …… 
    14711505            </figure> 
    14721506 
    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> 
     1507            <para>With VR Juggler 2.0 and beyond, it is possible to use a 
     1508            single window for graphics and for input. To use such a 
     1509            configuration, execute MPApp as follows:</para> 
    14761510 
    14771511            <screen>% MPApp standalone.jconf</screen> 
     1512 
     1513            <para>On Mac OS X, execute it this way:</para> 
     1514 
     1515            <screen>% MPApp.app/Contents/MacOS/MPApp standalone.jconf</screen> 
    14781516 
    14791517            <para>This time, only a single window opens, as shown in <xref 
    …… 
    15501588 
    15511589            <section> 
     1590               <title>Running an Application on Mac OS X with Cocoa 
     1591               Windows</title> 
     1592 
     1593               <para>In VR juggler 2.2, Cocoa support has been added for Mac 
     1594               OS X usage. This gives much better results than the previous 
     1595               reliance upon the X Window System. The interface for VR Juggler 
     1596               applications on Mac OS X is noticeably different than other 
     1597               platforms, however. We will explore those differences in this 
     1598               section.</para> 
     1599 
     1600               <para>There are two key differences with VR Juggler on Mac OS X 
     1601               from other platforms:</para> 
     1602 
     1603               <orderedlist> 
     1604                  <listitem> 
     1605                     <para>Applications are constructed as bundles</para> 
     1606                  </listitem> 
     1607 
     1608                  <listitem> 
     1609                     <para>Every application has the usual Mac OS application 
     1610                     menu</para> 
     1611                  </listitem> 
     1612               </orderedlist> 
     1613 
     1614               <para>The use of application bundles is required for software 
     1615               based on Cocoa. The topic of application bundles is beyond the 
     1616               scope of this document, but Apple has extensive documentation 
     1617               available for perusal. For typical VR Juggler applications, the 
     1618               bundle data files that come with VR Juggler 2.2 will suffice. 
     1619               The application bundle is constructed automatically using these 
     1620               files when the <literal>bundle</literal> target is built for 
     1621               any VR Juggler application whose build is based on Doozer 2.1.4 
     1622               and newer. For builds that are not using Doozer, see the files 
     1623               in 
     1624               <filename>$VJ_BASE_DIR/share/vrjuggler-2.2/data/bundle</filename> 
     1625               for a starting point.</para> 
     1626 
     1627               <para>The use of application bundles offers several different 
     1628               ways of launching applications. They are as follows:</para> 
     1629 
     1630               <itemizedlist> 
     1631                  <listitem> 
     1632                     <para>Double-clicking on the application bundle icon in 
     1633                     the <application>Finder</application></para> 
     1634                  </listitem> 
     1635 
     1636                  <listitem> 
     1637                     <para>Opening the bundle (e.g., 
     1638                     <filename>MPApp.app</filename>) from the command line 
     1639                     using <command>open</command></para> 
     1640                  </listitem> 
     1641 
     1642                  <listitem> 
     1643                     <para>Executing the contained application directly from 
     1644                     the command line</para> 
     1645                  </listitem> 
     1646               </itemizedlist> 
     1647 
     1648               <para>We have seen an example of the third option above, and in 
     1649               this document, we will always show that approach whenever 
     1650               describing how to launch a VR juggler application from the 
     1651               command line.</para> 
     1652 
     1653               <para>Using the <command>open</command> command offers two 
     1654               different options of its own. It can be used to open the bundle 
     1655               in the same way as double-clicking on its icon in the 
     1656               <application>Finder</application> would work. This usage is 
     1657               shown below:</para> 
     1658 
     1659               <screen>% open MPApp.app</screen> 
     1660 
     1661               <para>The other usage is to open a <filename>.jconf</filename> 
     1662               file and tell the <command>open</command> command to use a VR 
     1663               Juggler application bundle to handle the file open operation. 
     1664               This is done as follows:</para> 
     1665 
     1666               <screen>% open -a MPApp.app $VJ_BASE_DIR/share/vrjuggler-2.2/data/configFiles/standalone.jconf</screen> 
     1667 
     1668               <para>Note that the paths given to the application bundle and 
     1669               to the <filename>.jconf</filename> file must resolve correctly. 
     1670               No path searching will be performed for either in this 
     1671               case.</para> 
     1672 
     1673               <para>The application menu is defined by the 
     1674               <filename>.nib</filename> contained in the application bundle. 
     1675               This is hooked up to classes in VR Juggler at run time. The 
     1676               application menu is defined with the usual operations for 
     1677               window management as well as the <menuchoice> 
     1678                     <shortcut> 
     1679                        <keycap>Cmd+O</keycap> 
     1680                     </shortcut> 
     1681 
     1682                     <guimenu>File</guimenu> 
     1683 
     1684                     <guimenuitem>Open...</guimenuitem> 
     1685                  </menuchoice> operation for loading 
     1686               <filename>.jconf</filename> files. This feature leverages the 
     1687               existing support for run-time reconfiguration of VR Juggler. 
     1688               Every time a <filename>.jconf</filename> file is opened using 
     1689               the <menuchoice> 
     1690                     <shortcut> 
     1691                        <keycap>Cmd+O</keycap> 
     1692                     </shortcut> 
     1693 
     1694                     <guimenu>File</guimenu> 
     1695 
     1696                     <guimenuitem>Open...</guimenuitem> 
     1697                  </menuchoice> operation, VR Juggler reconfigures itself. 
     1698               This is basically the same as what can be done with 
     1699               <application>VRJConfig</application> when adding new 
     1700               configuration information dynamically. It is not possible to 
     1701               remove configuration information through this interface; 
     1702               <application>VRJConfig</application> must be used for that 
     1703               purpose.</para> 
     1704 
     1705               <para>When a VR Juggler application bundle is opened by 
     1706               double-clicking on its icon in the 
     1707               <application>Finder</application> or by using the first usage 
     1708               of the <command>open</command> command described above, 
     1709               <emphasis>no configuration files are loaded</emphasis>. The 
     1710               <menuchoice> 
     1711                     <shortcut> 
     1712                        <keycap>Cmd+O</keycap> 
     1713                     </shortcut> 
     1714 
     1715                     <guimenu>File</guimenu> 
     1716 
     1717                     <guimenuitem>Open...</guimenuitem> 
     1718                  </menuchoice> operation must be used to load configuration 
     1719               files and configure VR Juggler. (Even remote run-time 
     1720               reconfiguration through <application>VRJConfig</application> 
     1721               may not be available at this point unless omniORB was 
     1722              &nbs