Changeset 19460

Show
Ignore:
Timestamp:
11/10/06 15:52:03 (2 years ago)
Author:
patrick
Message:

Updated for more information about the use of flagpoll and changes to the
minimum required version for various dependencies.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • juggler/trunk/doc/INSTALL.xml

    r19198 r19460  
    166166      url="https://realityforge.vrsource.org/view/FlagPoll/">Flagpoll</ulink> 
    167167      software tool. As of this writing, the minimum required version is 
    168       0.5.0. It is recommended that all of these tools be installed in either 
     168      0.8.1. It is recommended that all of these tools be installed in either 
    169169      the <filename>/usr</filename> or the <filename>/usr/local</filename> 
    170170      directory trees so that search paths do not have to be extended.</para> 
    …… 
    316316            <title>CppDOM</title> 
    317317 
    318             <para>For XML processing, we use CppDOM 0.3.2 or newer. The source 
     318            <para>For XML processing, we use CppDOM 0.6.5 or newer. The source 
    319319            and binary distributions for some platforms can be downloaded from 
    320320            <ulink 
    …… 
    330330            <title>GMTL</title> 
    331331 
    332             <para>For high-level mathematical operations, we use GMTL 0.3.2 or 
    333             newer. The source distribution can be downloaded from <ulink 
     332            <para>For high-level mathematical operations, we use GMTL 0.4.12 
     333            or newer. The source distribution can be downloaded from <ulink 
    334334            url="http://www.sf.net/projects/ggt/">http://www.sf.net/projects/ggt/</ulink>. 
    335335            Note that you need SCons (<ulink 
    …… 
    370370            in order to compile the Tweek C++ API. At this time, the Tweek C++ 
    371371            API is not required for VR Juggler, but this situation will change 
    372             in the near future. At this time, we primarily use omniORB 4.0.x. 
    373             omniORB can be downloaded from <ulink 
     372            in the near future. At this time, we primarily use omniORB 4.0.x; 
     373            omniORB 3.0 is not supported. omniORB can be downloaded from 
     374            <ulink 
    374375            url="http://omniorb.sourceforge.net/">http://omniorb.sourceforge.net/</ulink>.</para> 
    375  
    376             <para>omniORB 3.0 has strange conventions for how installations 
    377             are made. Within the <filename>bin</filename> and 
    378             <filename>lib</filename> directories, there are platform-specific 
    379             subdirectories that contain the actual binaries (except when 
    380             installed on FreeBSD via the Ports Collection). Because of this, 
    381             several extra options must be specified in order to tell the Tweek 
    382             configure script where to find everything. Please refer to <xref 
    383             linkend="tweek.build.section" /> for more details on this.</para> 
    384376         </section> 
    385377      </section> 
    …… 
    438430               <itemizedlist> 
    439431                  <listitem> 
    440                      <para>CppDOM 0.3.2</para> 
     432                     <para>CppDOM 0.6.5</para> 
    441433                  </listitem> 
    442434 
    …… 
    604596 
    605597                  <listitem> 
    606                      <para>GMTL 0.1.9</para> 
     598                     <para>GMTL 0.4.12</para> 
    607599                  </listitem> 
    608600               </itemizedlist> 
    …… 
    671663 
    672664                  <listitem> 
    673                      <para>GMTL 0.1.9</para> 
     665                     <para>GMTL 0.4.12</para> 
    674666                  </listitem> 
    675667 
    …… 
    694686 
    695687                  <listitem> 
    696                      <para>VRPN 06.06 for the VRPN driver plug-in</para> 
     688                     <para>VRPN 07.03 for the VRPN driver plug-in</para> 
    697689                  </listitem> 
    698690 
    …… 
    814806               </itemizedlist> 
    815807            </section> 
     808         </section> 
     809 
     810         <section> 
     811            <title>Preparing Flagpoll</title> 
     812 
     813            <para>The Flagpoll software has a default search path where it 
     814            looks for <filename>.pc</filename> and <filename>.fpc</filename> 
     815            package metadata files. It searchs 
     816            <filename>/usr/lib/pkgconfig</filename>, 
     817            <filename>/usr/lib/flagpoll</filename>, 
     818            <filename>/usr/lib64/pkgconfig</filename>, 
     819            <filename>/usr/lib64/flagpoll</filename>, 
     820            <filename>/usr/share/pkgconfig</filename>, and 
     821            <filename>/usr/share/flagpoll</filename>. If 
     822            <envar>LD_LIBRARY_PATH</envar> (or 
     823            <envar>DYLD_LIBRARY_PATH</envar> on Mac OS X) is set, Flagpoll 
     824            will search each of the directories in that environment variable 
     825            for subdirectories named <filename>pkgconfig</filename> and 
     826            <filename>flagpoll</filename>. Users can extend this search path 
     827            further by setting the environment variables 
     828            <envar>PKG_CONFIG_PATH</envar> and/or <envar>FLAGPOLL_PATH</envar> 
     829            to list more directories for Flagpoll to search. (All of the 
     830            environment variables mentioned here have as their value a 
     831            colon-separated list of directories.)</para> 
     832 
     833            <para>The Juggler build relies upon Flagpoll for getting compiler 
     834            and linker flags for the following packages:</para> 
     835 
     836            <itemizedlist> 
     837               <listitem> 
     838                  <para>CppDOM</para> 
     839               </listitem> 
     840 
     841               <listitem> 
     842                  <para>GMTL</para> 
     843               </listitem> 
     844 
     845               <listitem> 
     846                  <para>omniORB</para> 
     847               </listitem> 
     848            </itemizedlist> 
     849 
     850            <para>Therefore, it is critical that Flagpoll be able to find the 
     851            package metadata file for each. For CppDOM, the 
     852            <filename>.fpc</filename> file is under the CppDOM 
     853            <filename>lib</filename> (or <filename>lib64</filename>) directory 
     854            in the <filename>flagpoll</filename> subdirectory. For omniORB, 
     855            the <filename>.pc</filename> files (there are several) are under 
     856            the omniORB <filename>lib</filename> (or 
     857            <filename>lib64</filename>) directory in the 
     858            <filename>pkgconfig</filename> subdirectory. Finally, for GMTL, 
     859            the <filename>.pc</filename> file is under the GMTL 
     860            <filename>share</filename> directory in the 
     861            <filename>pkgconfig</filename> subdirectory. If these packages are 
     862            installed in <filename>/usr</filename>, then Flagpoll will be able 
     863            to find the information it needs with no extra work on the part of 
     864            the user.</para> 
     865 
     866            <important> 
     867               <para>If Flagpoll is not installed in a place where the 
     868               <command>aclocal</command> tool searches for 
     869               <filename>.m4</filename> files by default, then it is necessary 
     870               to extend <command>aclocal</command>'s search path. This is 
     871               done by setting the environment variable 
     872               <envar>ACLOCAL_FLAGS</envar> to <quote><literal>-I 
     873               .../share/alocal</literal></quote> where 
     874               <quote><literal>...</literal></quote> is the path to the 
     875               directory tree where Flagpoll is installed.</para> 
     876            </important> 
    816877         </section> 
    817878 
    …… 
    920981 
    921982                     <important> 
    922                         <para>You will probably have to specify the paths to 
    923                         your local CppDOM, GMTL, and Boost installations using 
    924                         the options <option>--with-cppdom</option>, 
    925                         <option>--with-gmtl</option>, and 
    926                         <option>--with-boost</option> unless they are 
    927                         installed in the default location 
     983                        <para>You will probably have to specify the path to 
     984                        your local Boost installation using the option 
     985                        <option>--with-boost</option> unless it is installed 
     986                        in the default location 
    928987                        (<filename>/usr/local</filename>). By default, Boost 
    929                         1.31 installs its header files in a subdirectory of 
    930                         <filename>include</filename> called 
    931                         <filename>boost-1_31</filename>. That is, if Boost is 
    932                         installed in 
     988                        1.31 and newer install the Boost header files in a 
     989                        subdirectory of <filename>include</filename> called 
     990                        <filename>boost-VERSION</filename> (where 
     991                        <filename>VERSION</filename> is the Boost version 
     992                        number with underscores instead of periods). That is, 
     993                        if Boost 1.34 is installed in 
    933994                        <filename>/home/user1/pkgs/boost</filename>, the 
    934995                        header files will be in 
    935                         <filename>/home/user1/pkgs/boost/include/boost-1_31</filename>. 
     996                        <filename>/home/user1/pkgs/boost/include/boost-1_34</filename>. 
    936997                        In this case, you must also specify the option 
    937                         <option>--with-boost-includes=/home/user1/pkgs/boost/include/boost-1_31</option> 
     998                        <option>--with-boost-includes=/home/user1/pkgs/boost/include/boost-1_34</option> 
    938999                        when running <command>configure.pl</command>.</para> 
    9391000                     </important> 
    940  
    941                      <important> 
    942                         <para>If Flagpoll is not installed in a place where 
    943                         the <command>aclocal</command> tool searches for 
    944                         <filename>.m4</filename> files by default, then it is 
    945                         necessary to extend <command>aclocal</command>'s 
    946                         search path. This is done by setting the environment 
    947                         variable <envar>ACLOCAL_FLAGS</envar> to 
    948                         <quote><literal>-I .../share/alocal</literal></quote> 
    949                         where <quote><literal>...</literal></quote> is the 
    950                         path to the directory tree where Flagpoll is 
    951                         installed.</para> 
    952                      </important> 
    9531001                  </listitem> 
    9541002               </orderedlist> 
    …… 
    9561004               <para>By default, the configuration process will configure VR 
    9571005               Juggler and all of its dependencies. This includes Sonix, which 
    958                is an interesting special case. Sonix can make use of Aaudiere, 
     1006               is an interesting special case. Sonix can make use of Audiere, 
    9591007               OpenAL, or AudioWorks to add sound to VR Juggler applications. 
    9601008               If none of those packages is found, Sonix will <quote>stub 
    …… 
    9821030               <para>As noted in <xref linkend="source.code.section" />, VR 
    9831031               Juggler depends on several external software packages. As an 
    984                example, consider the case where the GMTL library is installed 
    985                in <filename>/home/user1/pkgs/GMTL</filename> with the headers 
    986                in <filename>/home/user1/pkgs/GMTL/include</filename>. To use 
     1032               example, consider the case where the Boost libraries are 
     1033               installed in <filename>/home/user1/pkgs/boost</filename> with 
     1034               the headers in 
     1035               <filename>/home/user1/pkgs/boost/include</filename>. To use 
    9871036               this installation, run <command>configure.pl</command> as 
    9881037               follows:</para> 
    9891038 
    990                <screen>../configure.pl --with-gmtl=/home/user1/pkgs/GMTL</screen> 
    991  
    992                <para>The <option>--with-gmtl</option> option could of course 
    993                be mixed in with those shown in the previous section.</para> 
     1039               <screen>../configure.pl --with-boost=/home/user1/pkgs/boost</screen> 
    9941040            </section> 
    9951041         </section> 
    …… 
    10861132 
    10871133            <para>Tweek needs JDK 1.4 or newer and a C++ CORBA implementation. 
    1088             Currently, we primarily use omniORB 4.0, but omniORB 3.0 can be 
    1089             used. Visit the <ulink 
     1134            Currently, we primarily use omniORB 4.0. Visit the <ulink 
    10901135            url="http://omniorb.sourceforge.net/">omniORB website</ulink> to 
    10911136            download omniORB.</para> 
    …… 
    11101155../configure.pl --with-cxx-orb=omniORB4 --with-cxx-orb-root=&lt;OMNIORB_PATH&gt; --with-java-orb=JDK --module=Tweek 
    11111156gmake build install</screen> 
    1112  
    1113             <para>If you are using omniORB 3.x, pass 
    1114             <option>--with-cxx-orb=omniORB3</option> instead.</para> 
    1115  
    1116             <para>Depending on your omniORB installation, you may have to pass 
    1117             extra arguments to <command>configure.pl</command> so that the 
    1118             configuration process can find the <command>omniidl</command> 
    1119             binary and the omniORB libraries. For example, on Red Hat Linux 
    1120             7.2 with omniORB 3.0.x, the following arguments must be specified 
    1121             in addition to the above:</para> 
    1122  
    1123             <screen>--with-cxx-orb-bin=&lt;OMNIORB_PATH&gt;/bin/i586_linux_2.0_glibc --with-cxx-orb-lib=&lt;OMNIORB_PATH&gt;/lib/i586_linux_2.0_glibc</screen> 
    11241157         </section> 
    11251158      </section>