Changeset 19730

Show
Ignore:
Timestamp:
01/01/07 10:37:40 (2 years ago)
Author:
patrick
Message:

Copyright update.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • PyJuggler/trunk/Jamfile

    r18525 r19730  
    1 # PyJuggler is (C) Copyright 2002-2006 by Patrick Hartling 
     1# PyJuggler is (C) Copyright 2002-2007 by Patrick Hartling 
    22# Distributed under the GNU Lesser General Public License 2.1.  (See 
    33# accompanying file COPYING.txt or http://www.gnu.org/copyleft/lesser.txt) 

  • PyJuggler/trunk/Makefile.in

    r19432 r19730  
    1 # PyJuggler is (C) Copyright 2002-2006 by Patrick Hartling 
     1# PyJuggler is (C) Copyright 2002-2007 by Patrick Hartling 
    22# Distributed under the GNU Lesser General Public License 2.1.  (See 
    33# accompanying file COPYING.txt or http://www.gnu.org/copyleft/lesser.txt) 

  • PyJuggler/trunk/VARS.pl.in

    r18525 r19730  
    1 # PyJuggler is (C) Copyright 2002-2006 by Patrick Hartling 
     1# PyJuggler is (C) Copyright 2002-2007 by Patrick Hartling 
    22# Distributed under the GNU Lesser General Public License 2.1.  (See 
    33# accompanying file COPYING.txt or http://www.gnu.org/copyleft/lesser.txt) 

  • PyJuggler/trunk/buildwin32.py

    r19638 r19730  
    11#python 
    22 
    3 # PyJuggler is (C) Copyright 2002-2006 by Patrick Hartling 
     3# PyJuggler is (C) Copyright 2002-2007 by Patrick Hartling 
    44# Distributed under the GNU Lesser General Public License 2.1.  (See 
    55# accompanying file COPYING.txt or http://www.gnu.org/copyleft/lesser.txt) 

  • PyJuggler/trunk/configure.ac

    r19652 r19730  
    1 # PyJuggler is (C) Copyright 2002-2006 by Patrick Hartling 
     1# PyJuggler is (C) Copyright 2002-2007 by Patrick Hartling 
    22# Distributed under the GNU Lesser General Public License 2.1.  (See 
    33# accompanying file COPYING.txt or http://www.gnu.org/copyleft/lesser.txt) 

  • PyJuggler/trunk/dist/__init__.py

    r19693 r19730  
    1 # PyJuggler is (C) Copyright 2002-2006 by Patrick Hartling 
     1# PyJuggler is (C) Copyright 2002-2007 by Patrick Hartling 
    22# Distributed under the GNU Lesser General Public License 2.1.  (See 
    33# accompanying file COPYING.txt or http://www.gnu.org/copyleft/lesser.txt) 

  • PyJuggler/trunk/dist/vrj.py

    r19613 r19730  
    1 # PyJuggler is (C) Copyright 2002-2006 by Patrick Hartling 
     1# PyJuggler is (C) Copyright 2002-2007 by Patrick Hartling 
    22# Distributed under the GNU Lesser General Public License 2.1.  (See 
    33# accompanying file COPYING.txt or http://www.gnu.org/copyleft/lesser.txt) 

  • PyJuggler/trunk/doc/getting.started.guide/Makefile

    r18525 r19730  
    1 # PyJuggler is (C) Copyright 2002-2006 by Patrick Hartling 
     1# PyJuggler is (C) Copyright 2002-2007 by Patrick Hartling 
    22# Distributed under the GNU Lesser General Public License 2.1.  (See 
    33# accompanying file COPYING.txt or http://www.gnu.org/copyleft/lesser.txt) 

  • PyJuggler/trunk/doc/getting.started.guide/getting.started.guide.xml

    r18332 r19730  
    33"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 
    44<book> 
    5   <bookinfo> 
    6     <title>PyJuggler</title> 
    7  
    8     <subtitle>Getting Started Guide</subtitle> 
    9  
    10     <authorgroup> 
    11       <author> 
    12         <firstname>Patrick</firstname> 
    13  
    14         <surname>Hartling</surname> 
    15       </author> 
    16     </authorgroup> 
    17  
    18     <copyright> 
    19       <year>2003–2006</year> 
    20  
    21       <holder>Patrick Hartling</holder> 
    22     </copyright> 
    23  
    24     <legalnotice> 
    25       <para>Permission is granted to copy, distribute and/or modify this 
    26       document under the terms of the GNU Free Documentation License, Version 
    27       1.2 or any later version published by the Free Software Foundation; with 
    28       the Invariant Sections being <xref linkend="appendix.gfdl" />, with no 
    29       Front-Cover Texts, and with no Back-Cover Texts. A copy of the license 
    30       is included in <xref linkend="appendix.gfdl" />.</para> 
    31     </legalnotice> 
    32  
    33     <date>$Date$</date> 
    34   </bookinfo> 
    35  
    36   <preface> 
    37     <title>What is PyJuggler?</title> 
    38  
    39     <para>PyJuggler is a collection of Python bindings for the VR Juggler C++ 
    40     application development framework. With PyJuggler, VR Juggler application 
    41     objects can be written in Python and loaded into the VR Juggler C++ 
    42     microkernel. Python application objects can even be intermingled with C++ 
    43     application objects to allow for multi-language switching between virtual 
    44     worlds.</para> 
    45  
    46     <para>The Python bindings that make up PyJuggler are written as C++ 
    47     modules that the Python interpreter can load at runtime just as it would 
    48     any other Python module. There are several Python modules, each 
    49     corresponding to one of the software modules that comprise the larger 
    50     Juggler framework. For example, the module 
    51     <classname>PyJuggler.gadget</classname> contains bindings for the 
    52     Gadgeteer C++ library.</para> 
    53   </preface> 
    54  
    55   <chapter> 
    56     <title>Getting the Software</title> 
    57  
    58     <para>Because PyJuggler follows the well-known layered architecture for 
    59     software, it is built on top of other tools. These must be downloaded and 
    60     installed prior to installing PyJuggler to ensure that dependencies are 
    61     satisfied correctly.</para> 
    62  
    63     <section> 
    64       <title>Additional Software</title> 
    65  
    66       <para>The following is a list of software that is required to utilize 
    67       PyJuggler, regardless of the type of VR Juggler application that will be 
    68       written. In other words, these software packages are 
    69       <emphasis>required</emphasis> to use PyJuggler.</para> 
    70  
    71       <itemizedlist> 
    72         <listitem> 
    73           <para><ulink url="http://www.python.org/">Python</ulink>: The 
    74           dynamically typed object-oriented scripting language. The version of 
    75           Python required depends on the requirements of Boost.Python (see the 
    76           next bullet item), but as of this writing, Python 2.2 or newer is 
    77           necessary.</para> 
    78         </listitem> 
    79  
    80         <listitem> 
    81           <para><ulink 
    82           url="http://www.boost.org/libs/python/doc/">Boost.Python</ulink>: 
    83           The high-level glue between C++ and Python code. PyJuggler requires 
    84           Boost.Python v2 from Boost 1.32.0 or newer. The version of 
    85           Boost.Python used must come from the Boost same version against 
    86           which VR Juggler was compiled to avoid load- or run-time shared 
    87           library conflicts.</para> 
    88         </listitem> 
    89  
    90         <listitem> 
    91           <para><ulink url="http://www.vrjuggler.org/">VR Juggler</ulink>: The 
    92           cross-platform, cross-VR system virtual platform for which PyJuggler 
    93           provides Python bindings. Without VR Juggler, PyJuggler has no 
    94           purpose. Releases of PyJuggler come shortly after VR Juggler 
    95           releases. Hence, the latest version of PyJuggler requires the latest 
    96           version of VR Juggler (2.0 or newer).</para> 
    97         </listitem> 
    98  
    99         <listitem> 
    100           <para><ulink url="http://ggt.sourceforge.net/">PyGMTL</ulink>: 
    101           Python bindings for the Generic Math Template Library (GMTL). These 
    102           are required for proper acquisition of GMTL-based data from VR 
    103           Juggler classes. For example, the transformation matrix for a 
    104           <classname>gadget.PositionInterface</classname> object will be 
    105           returned as a <classname>gmtl.Matrix44f</classname> object. PyGMTL 
    106           is developed independently of VR Juggler and PyJuggler, but the 
    107           version of PyGMTL used must be the same as the version of GMTL that 
    108           comes with a VR Juggler release.</para> 
    109         </listitem> 
    110       </itemizedlist> 
    111  
    112       <para>With those packages installed, one or more of the following will 
    113       be needed in order to render graphics from the VR Juggler application 
    114       object:</para> 
    115  
    116       <itemizedlist> 
    117         <listitem> 
    118           <para><ulink 
    119           url="http://pyopengl.sourceforge.net/">PyOpenGL</ulink>: Python 
    120           bindings for the <ulink url="http://www.opengl.org/">OpenGL</ulink> 
    121           graphics API. OpenGL-based VR Juggler applications written in Python 
    122           use PyOpenGL to make calls into the natively compiled OpenGL 
    123           libraries on the local system. We have tested with PyOpenGL 
    124           2.0.</para> 
    125         </listitem> 
    126  
    127         <listitem> 
    128           <para><ulink 
    129           url="http://sourceforge.net/projects/pyosg">PyOSG</ulink>: Python 
    130           bindings for the <ulink url="http://www.openscenegraph.org/">Open 
    131           Scene Graph</ulink> (OSG). OSG-based VR Juggler applications written 
    132           in Python use PyOSG to make calls to the natively compiled OSG 
    133           libraries on the local system. If direct OpenGL calls must also be 
    134           made, then PyOpenGL will be needed (see above). We have tested with 
    135           PyOSG 0.4.5.</para> 
    136         </listitem> 
    137       </itemizedlist> 
    138     </section> 
    139  
    140     <section> 
    141       <title>Downloading</title> 
    142  
    143       <para>PyJuggler is distributed from the VR Juggler SourceForge.net 
    144       <ulink url="http://www.sourceforge.net/projects/vrjuggler/">project 
    145       site</ulink>. Because PyJuggler is still in the developmental stages, it 
    146       is recommended that users keep up to date with the latest version at all 
    147       times. PyJuggler will always keep up to date with the VR Juggler API, 
    148       and because it provides a one-to-one mapping of C++ to Python, the API 
    149       will be identical except for slight differences based on Python 
    150       syntax.</para> 
    151  
    152       <para>PyJuggler is an open source software library, and as such, its 
    153       source code is available. Users are free to download the source, look at 
    154       it, and modify it (keeping in mind the requirements of the license, of 
    155       course). For the most part, the PyJuggler source code is pretty dull; 
    156       the interesting aspect is what developers can do to write VR Juggler 
    157       application objects in Python. As such, the source is provided primarily 
    158       so that people can compile it for their local hardware and operating 
    159       system. Some pre-compiled binary versions will exist, but the 
    160       requirements of those binaries may not satisfy every single user's 
    161       needs.</para> 
    162     </section> 
    163  
    164     <section> 
    165       <title>Extracting</title> 
    166  
    167       <para>PyJuggler comes in a compressed archive format. For UNIX-based 
    168       environments, we use the well-known <command>tar</command>(1) format for 
    169       the archive and either <command>gzip</command>(1) 
    170       (<filename>.gz</filename> file extension) or <command>bzip2</command>(1) 
    171       (<filename>.bz2</filename> file extension) for the compression. Because 
    172       pre-compiled versions of PyJuggler are quite large, we normally use the 
    173       BZIP2 format because it gives a better compression ratio than GZIP. To 
    174       extract the contents of a BZIP2-compressed TAR file, use the following 
    175       if GNU <command>tar</command>(1) is not available:</para> 
    176  
    177       <screen>% bzip2 -cd pyjuggler.tar.bz2 | tar -xvf -</screen> 
    178  
    179       <para>If GNU <command>tar</command>(1) is installed (it may be installed 
    180       as <command>gtar</command> on some systems), use the following simpler 
    181       command:</para> 
    182  
    183       <screen>% tar -xjvf pyjuggler.tar.bz2</screen> 
    184  
    185       <para>For Win32 environments, we use PKZIP compression (files have a 
    186       <filename>.zip</filename> extension). The typical way to extract such an 
    187       archive is to use the <ulink url="http://www.winzip.com/">WinZip</ulink> 
    188       software. We will not show its use here since it offers a fairly 
    189       straightforward GUI.</para> 
    190     </section> 
    191   </chapter> 
    192  
    193   <chapter> 
    194     <title>Configuring the Environment</title> 
    195  
    196     <para>PyJuggler needs all the environment variables required for execution 
    197     of normal C++ VR Juggler applications. Additionally, the PyJuggler 
    198     <filename>lib</filename> directory must be included in the shared library 
    199     (DLL) search path so that the library <filename>libpyjutil.so</filename> 
    200     (or <filename>pyjutil.dll</filename> or 
    201     <filename>libpyjutil.dylib</filename>) can be found at module load time. 
    202     This is normally accomplished by modifying the environment variable 
    203     <envar>LD_LIBRARY_PATH</envar>, <envar>PATH</envar>, or 
    204     <envar>DYLD_LIBRARY_PATH</envar>, depending on the operating system. If 
    205     PyJuggler is installed so that its <filename>lib</filename> directory is 
    206     already in the shared library search path, then the library search path 
    207     does not have to be changed.</para> 
    208  
    209     <para>With the addition of Python into the mix, it may be necessary to set 
    210     the <varname>PYTHONPATH</varname> environment variable. This environment 
    211     variable tells Python where to look for modules outside of its default 
    212     path. In other words, it <emphasis>augments</emphasis> the Python module 
    213     search path to use the directories listed therein.</para> 
    214  
    215     <para>The need for <varname>PYTHONPATH</varname> depends on where 
    216     PyJuggler is installed. If PyJuggler is installed where Python modules are 
    217     installed by default, then Python will not need any help to find the 
    218     PyJuggler modules. However, a pre-compiled version of PyJuggler can be 
    219     installed anywhere (which is good for people who do not have 
    220     administrative rights on their local system and thus cannot perform 
    221     system-wide installations). For example, on a UNIX-based system, PyJuggler 
    222     could be unpacked into <filename>$HOME/pyjuggler</filename>. If PyJuggler 
    223     was compiled against Python 2.2, <varname>PYTHONPATH</varname> would be 
    224     set as follows (assuming the use of either csh or tcsh as the user's 
    225     shell):</para> 
    226  
    227     <screen>% setenv PYTHONPATH $HOME/pyjuggler/lib/python2.2/site-packages</screen> 
    228  
    229     <para>For more information about Python, Python modules, and environment 
    230     variables utilized by the Python interpreter, refer to the <ulink 
    231     url="http://www.python.org/doc/">on-line Python 
    232     documentation</ulink>.</para> 
    233  
    234     <tip> 
    235       <para>PyOpenGL and PyGMTL may have to be handled similarly to PyJuggler 
    236       as far as <varname>PYTHONPATH</varname> is concerned. It may be 
    237       convenient to install all three in the same place so that only one 
    238       directory must be specified in <varname>PYTHONPATH</varname>. Of course, 
    239       one or both of PyOpenGL or PyGMTL may be installed in the default Python 
    240       module directory, so this may not be a concern at all.</para> 
    241     </tip> 
    242  
    243     <para>On Mac OS X, problems have been encountered with the <ulink 
    244     url="http://omniorb.sourceforge.net/">omniORB</ulink>-based plug-ins that 
    245     are loaded by the JCCL Config Manager and by the VR Juggler Performance 
    246     Mediator. Loading of these plug-ins can be disabled by setting the 
    247     environment variables <envar>NO_RTRC_PLUGIN</envar> and 
    248     <envar>NO_PERF_PLUGIN</envar> respectively. They may be set to any value. 
    249     Setting these environment variables will prevent a crash inside the 
    250     omniORB libraries due to static initializatoin problems.</para> 
    251  
    252     <note> 
    253       <para>According to users of omniORBpy, setting 
    254       <envar>DYLD_BIND_AT_LAUNCH</envar> should be sufficient to fix the 
    255       static initialization problems within the omniORB C++ libraries when 
    256       they are loaded into the Python interpreter application space on Mac OS 
    257       X. Thus far, this has not proven to fix the problem when running a 
    258       PyJuggler Python application, but there may be something else going 
    259       wrong. For now, setting the two environment variables described above 
    260       gets around the omniORB problems within the scope of PyJuggler.</para> 
    261     </note> 
    262   </chapter> 
    263  
    264   <chapter> 
    265     <title>Running Example Applications</title> 
    266  
    267     <para>Executing the example PyJuggler applications works very similarly to 
    268     C++ VR Juggler applications. This is done on purpose to make it easier for 
    269     people with C++ VR Juggler experience to get started with PyJuggler. Of 
    270     course, how any given application is written is entirely up to the author; 
    271     these are simply examples.</para> 
    272  
    273     <section> 
    274       <title>simpleGL</title> 
    275  
    276       <para>In the PyJuggler installation directory, a very simple <quote>pure 
    277       Python</quote> application can be found under 
    278       <filename>share/pyjuggler/examples/python/simpleGL</filename>. The 
    279       directory contains a single file <filename>simpleGL.py</filename>. To 
    280       execute this application, the following will work in a UNIX-based 
    281       environment:</para> 
    282  
    283       <screen>% ./simpleGL.py standalone.jconf</screen> 
    284  
    285       <para>For a DOS/Win32 environment, the command is similar:</para> 
    286  
    287       <screen>&gt; python simpleGL.py standalone.jconf</screen> 
     5   <bookinfo> 
     6      <title>PyJuggler</title> 
     7 
     8      <subtitle>Getting Started Guide</subtitle> 
     9 
     10      <authorgroup> 
     11         <author> 
     12            <firstname>Patrick</firstname> 
     13 
     14            <surname>Hartling</surname> 
     15         </author> 
     16      </authorgroup> 
     17 
     18      <copyright> 
     19         <year>2003–2007</year> 
     20 
     21         <holder>Patrick Hartling</holder> 
     22      </copyright> 
     23 
     24      <legalnotice> 
     25         <para>Permission is granted to copy, distribute and/or modify this 
     26         document under the terms of the GNU Free Documentation License, 
     27         Version 1.2 or any later version published by the Free Software 
     28         Foundation; with the Invariant Sections being <xref 
     29         linkend="appendix.gfdl" />, with no Front-Cover Texts, and with no 
     30         Back-Cover Texts. A copy of the license is included in <xref 
     31         linkend="appendix.gfdl" />.</para> 
     32      </legalnotice> 
     33 
     34      <date>$Date$</date> 
     35   </bookinfo> 
     36 
     37   <preface> 
     38      <title>What is PyJuggler?</title> 
     39 
     40      <para>PyJuggler is a collection of Python bindings for the VR Juggler 
     41      C++ application development framework. With PyJuggler, VR Juggler 
     42      application objects can be written in Python and loaded into the VR 
     43      Juggler C++ microkernel. Python application objects can even be 
     44      intermingled with C++ application objects to allow for multi-language 
     45      switching between virtual worlds.</para> 
     46 
     47      <para>The Python bindings that make up PyJuggler are written as C++ 
     48      modules that the Python interpreter can load at runtime just as it would 
     49      any other Python module. There are several Python modules, each 
     50      corresponding to one of the software modules that comprise the larger 
     51      Juggler framework. For example, the module 
     52      <classname>PyJuggler.gadget</classname> contains bindings for the 
     53      Gadgeteer C++ library.</para> 
     54   </preface> 
     55 
     56   <chapter> 
     57      <title>Getting the Software</title> 
     58 
     59      <para>Because PyJuggler follows the well-known layered architecture for 
     60      software, it is built on top of other tools. These must be downloaded 
     61      and installed prior to installing PyJuggler to ensure that dependencies 
     62      are satisfied correctly.</para> 
     63 
     64      <section> 
     65         <title>Additional Software</title> 
     66 
     67         <para>The following is a list of software that is required to utilize 
     68         PyJuggler, regardless of the type of VR Juggler application that will 
     69         be written. In other words, these software packages are 
     70         <emphasis>required</emphasis> to use PyJuggler.</para> 
     71 
     72         <itemizedlist> 
     73            <listitem> 
     74               <para><ulink url="http://www.python.org/">Python</ulink>: The 
     75               dynamically typed object-oriented scripting language. The 
     76               version of Python required depends on the requirements of 
     77               Boost.Python (see the next bullet item), but as of this 
     78               writing, Python 2.2 or newer is necessary.</para> 
     79            </listitem> 
     80 
     81            <listitem> 
     82               <para><ulink 
     83               url="http://www.boost.org/libs/python/doc/">Boost.Python</ulink>: 
     84               The high-level glue between C++ and Python code. PyJuggler 
     85               requires Boost.Python v2 from Boost 1.32.0 or newer. The 
     86               version of Boost.Python used must come from the Boost same 
     87               version against which VR Juggler was compiled to avoid load- or 
     88               run-time shared library conflicts.</para> 
     89            </listitem> 
     90 
     91            <listitem> 
     92               <para><ulink url="http://www.vrjuggler.org/">VR 
     93               Juggler</ulink>: The cross-platform, cross-VR system virtual 
     94               platform for which PyJuggler provides Python bindings. Without 
     95               VR Juggler, PyJuggler has no purpose. Releases of PyJuggler 
     96               come shortly after VR Juggler releases. Hence, the latest 
     97               version of PyJuggler requires the latest version of VR Juggler 
     98               (2.0 or newer).</para> 
     99            </listitem> 
     100 
     101            <listitem> 
     102               <para><ulink url="http://ggt.sourceforge.net/">PyGMTL</ulink>: 
     103               Python bindings for the Generic Math Template Library (GMTL). 
     104               These are required for proper acquisition of GMTL-based data 
     105               from VR Juggler classes. For example, the transformation matrix 
     106               for a <classname>gadget.PositionInterface</classname> object 
     107               will be returned as a <classname>gmtl.Matrix44f</classname> 
     108               object. PyGMTL is developed independently of VR Juggler and 
     109               PyJuggler, but the version of PyGMTL used must be the same as 
     110               the version of GMTL that comes with a VR Juggler 
     111               release.</para> 
     112            </listitem> 
     113         </itemizedlist> 
     114 
     115         <para>With those packages installed, one or more of the following 
     116         will be needed in order to render graphics from the VR Juggler 
     117         application object:</para> 
     118 
     119         <itemizedlist> 
     120            <listitem> 
     121               <para><ulink 
     122               url="http://pyopengl.sourceforge.net/">PyOpenGL</ulink>: Python 
     123               bindings for the <ulink 
     124               url="http://www.opengl.org/">OpenGL</ulink> graphics API. 
     125               OpenGL-based VR Juggler applications written in Python use 
     126               PyOpenGL to make calls into the natively compiled OpenGL 
     127               libraries on the local system. We have tested with PyOpenGL 
     128               2.0.</para> 
     129            </listitem> 
     130 
     131            <listitem> 
     132               <para><ulink 
     133               url="http://sourceforge.net/projects/pyosg">PyOSG</ulink>: 
     134               Python bindings for the <ulink 
     135               url="http://www.openscenegraph.org/">Open Scene Graph</ulink> 
     136               (OSG). OSG-based VR Juggler applications written in Python use 
     137               PyOSG to make calls to the natively compiled OSG libraries on 
     138               the local system. If direct OpenGL calls must also be made, 
     139               then PyOpenGL will be needed (see above). We have tested with 
     140               PyOSG 0.4.5.</para> 
     141            </listitem> 
     142         </itemizedlist> 
     143      </section> 
     144 
     145      <section> 
     146         <title>Downloading</title> 
     147 
     148         <para>PyJuggler is distributed from the VR Juggler SourceForge.net 
     149         <ulink url="http://www.sourceforge.net/projects/vrjuggler/">project 
     150         site</ulink>. Because PyJuggler is still in the developmental stages, 
     151         it is recommended that users keep up to date with the latest version 
     152         at all times. PyJuggler will always keep up to date with the VR 
     153         Juggler API, and because it provides a one-to-one mapping of C++ to 
     154         Python, the API will be identical except for slight differences based 
     155         on Python syntax.</para> 
     156 
     157         <para>PyJuggler is an open source software library, and as such, its 
     158         source code is available. Users are free to download the source, look 
     159         at it, and modify it (keeping in mind the requirements of the 
     160         license, of course). For the most part, the PyJuggler source code is 
     161         pretty dull; the interesting aspect is what developers can do to 
     162         write VR Juggler application objects in Python. As such, the source 
     163         is provided primarily so that people can compile it for their local 
     164         hardware and operating system. Some pre-compiled binary versions will 
     165         exist, but the requirements of those binaries may not satisfy every 
     166         single user's needs.</para> 
     167      </section> 
     168 
     169      <section> 
     170         <title>Extracting</title> 
     171 
     172         <para>PyJuggler comes in a compressed archive format. For UNIX-based 
     173         environments, we use the well-known <command>tar</command>(1) format 
     174         for the archive and either <command>gzip</command>(1) 
     175         (<filename>.gz</filename> file extension) or 
     176         <command>bzip2</command>(1) (<filename>.bz2</filename> file 
     177         extension) for the compression. Because pre-compiled versions of 
     178         PyJuggler are quite large, we normally use the BZIP2 format because 
     179         it gives a better compression ratio than GZIP. To extract the 
     180         contents of a BZIP2-compressed TAR file, use the following if GNU 
     181         <command>tar</command>(1) is not available:</para> 
     182 
     183         <screen>% bzip2 -cd pyjuggler.tar.bz2 | tar -xvf -</screen> 
     184 
     185         <para>If GNU <command>tar</command>(1) is installed (it may be 
     186         installed as <command>gtar</command> on some systems), use the 
     187         following simpler command:</para> 
     188 
     189         <screen>% tar -xjvf pyjuggler.tar.bz2</screen> 
     190 
     191         <para>For Win32 environments, we use PKZIP compression (files have a 
     192         <filename>.zip</filename> extension). The typical way to extract such 
     193         an archive is to use the <ulink 
     194         url="http://www.winzip.com/">WinZip</ulink> software. We will not 
     195         show its use here since it offers a fairly straightforward 
     196         GUI.</para> 
     197      </section> 
     198   </chapter> 
     199 
     200   <chapter> 
     201      <title>Configuring the Environment</title> 
     202 
     203      <para>PyJuggler needs all the environment variables required for 
     204      execution of normal C++ VR Juggler applications. Additionally, the 
     205      PyJuggler <filename>lib</filename> directory must be included in the 
     206      shared library (DLL) search path so that the library 
     207      <filename>libpyjutil.so</filename> (or <filename>pyjutil.dll</filename> 
     208      or <filename>libpyjutil.dylib</filename>) can be found at module load 
     209      time. This is normally accomplished by modifying the environment 
     210      variable <envar>LD_LIBRARY_PATH</envar>, <envar>PATH</envar>, or 
     211      <envar>DYLD_LIBRARY_PATH</envar>, depending on the operating system. If 
     212      PyJuggler is installed so that its <filename>lib</filename> directory is 
     213      already in the shared library search path, then the library search path 
     214      does not have to be changed.</para> 
     215 
     216      <para>With the addition of Python into the mix, it may be necessary to 
     217      set the <varname>PYTHONPATH</varname> environment variable. This 
     218      environment variable tells Python where to look for modules outside of 
     219      its default path. In other words, it <emphasis>augments</emphasis> the 
     220      Python module search path to use the directories listed therein.</para> 
     221 
     222      <para>The need for <varname>PYTHONPATH</varname> depends on where 
     223      PyJuggler is installed. If PyJuggler is installed where Python modules 
     224      are installed by default, then Python will not need any help to find the 
     225      PyJuggler modules. However, a pre-compiled version of PyJuggler can be 
     226      installed anywhere (which is good for people who do not have 
     227      administrative rights on their local system and thus cannot perform 
     228      system-wide installations). For example, on a UNIX-based system, 
     229      PyJuggler could be unpacked into <filename>$HOME/pyjuggler</filename>. 
     230      If PyJuggler was compiled against Python 2.2, 
     231      <varname>PYTHONPATH</varname> would be set as follows (assuming the use 
     232      of either csh or tcsh as the user's shell):</para> 
     233 
     234      <screen>% setenv PYTHONPATH $HOME/pyjuggler/lib/python2.2/site-packages</screen> 
     235 
     236      <para>For more information about Python, Python modules, and environment 
     237      variables utilized by the Python interpreter, refer to the <ulink 
     238      url="http://www.python.org/doc/">on-line Python 
     239      documentation</ulink>.</para> 
     240 
     241      <tip> 
     242         <para>PyOpenGL and PyGMTL may have to be handled similarly to 
     243         PyJuggler as far as <varname>PYTHONPATH</varname> is concerned. It 
     244         may be convenient to install all three in the same place so that only 
     245         one directory must be specified in <varname>PYTHONPATH</varname>. Of 
     246         course, one or both of PyOpenGL or PyGMTL may be installed in the 
     247         default Python module directory, so this may not be a concern at 
     248         all.</para> 
     249      </tip> 
     250 
     251      <para>On Mac OS X, problems have been encountered with the <ulink 
     252      url="http://omniorb.sourceforge.net/">omniORB</ulink>-based plug-ins 
     253      that are loaded by the JCCL Config Manager and by the VR Juggler 
     254      Performance Mediator. Loading of these plug-ins can be disabled by 
     255      setting the environment variables <envar>NO_RTRC_PLUGIN</envar> and 
     256      <envar>NO_PERF_PLUGIN</envar> respectively. They may be set to any 
     257      value. Setting these environment variables will prevent a crash inside 
     258      the omniORB libraries due to static initializatoin problems.</para> 
    288259 
    289260      <note> 
    290         <para>For VR Juggler 2.0 Alpha 4 and beyond, the full path to the 
    291