root/OpenSceneGraph/trunk/doc/install.html @ 1912

Revision 1912, 17.3 kB (checked in by robert, 10 years ago)

Updates to docs.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
RevLine 
[603]1<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
2<html>
3<head>
4   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
[659]5   <meta name="GENERATOR" content="Mozilla/4.77 [en] (X11; U; Linux 2.4.3-20mdk i686) [Netscape]">
[651]6   <title>Installation instructions</title>
[603]7</head>
[604]8<body text="#000000" bgcolor="#FFFFFF" link="#0000FF" vlink="#990066" alink="#FF0000">
[1912]9<img SRC="images/OpenSceneGraphBanner_Distribution.jpg">
[637]10<table>
[659]11<tr>
12<td><a href="index.html">Index</a></td>
[604]13
[659]14<td><a href="introduction.html">Introduction</a></td>
[604]15
[659]16<td><a href="contents.html">Contents</a></td>
[637]17
[659]18<td><a href="install.html">Install</a></td>
[604]19
[659]20<td><a href="dependencies.html">Dependencies</a></td>
21
[1862]22<td><a href="examples.html">examples</a></td>
[659]23
24<td><a href="data.html">Data</a></td>
25
[1862]26<td><a href="osgviewer.html">Viewer</a></td>
[659]27
28<td><a href="stereo.html">Stereo</a></td>
29
30<td><a href="plan.html">Plan</a></td>
31
32<td><a href="documentation.html">Reference Guides</a></td>
33</tr>
34</table>
35
36<h2>
37<u>Compiling and installing the OpenSceneGraph</u></h2>
38The scene graph depends upon Standard C++, STL and OpenGL so you need a
[1868]39C++ compiler up to the task and OpenGL or Mesa installed. The example applications depend
40upon Open Producer which you'll need to download and install from the Producer website.
41The OSG has it own native ascii file format, and .rgb image reader
[659]42which allows you read the example data with any dependencies other than
43C++, STL and OpenGL.
44<p>The OSG also has a set of plug-ins which support non-native 3d database
[603]45and image formats, several have no dependencies on external libraries (flt,3ds,obj,
46lwo,dw, tga &amp; pic), while others (pfb,jpeg,gif,tiff) require other
47libraries to be installed to compile them. If you don't already have them
48installed then don't worry, you'll still be able to use the OSG, just comment
49out the plugins you can't compile from the src/osgPlugins/Makefile. The
50core osg library and viewer has been designed to load the plug-ins at run-time
51only and if they are required to load a specific data set. If you don't
52need them for your datasets then it won't matter that you haven't been
53able to compile all the plug-ins. A full list of dependencies and where
[605]54to download the required libraries are listed in the
[659]55<i><a href="dependencies.html">dependencies.html</a></i>
56<p>If you're coming across the OSG for the first time and want to get started
[603]57quickly, go right ahead and follow the compilation instructions. You can
58always later download the libraries which the plug-ins require if you eventually
[605]59need them.
[659]60<ul>
61<li>
62<a href="#Compiling under Windows with Visual Studio">Compiling under Windows
63with Visual Studio</a></li>
[604]64
[659]65<li>
66Compiling under Unix (including Mac OSX and Cygwin)</li>
67
68<p><br>Building the OSG requires 'gmake', due to the extensive use of gmake
69directives in the Makefiles. You can get gmake from here if you don't already
70have it installed: http://www.gnu.org/software/make/
71<p>Almost all of the unix compiling is done simply with <b>make; make install</b>
72with <b>make help</b> to bring up help. For platform specific details:
[605]73<ul>
[659]74<li>
75<a href="#Cygwin">Cygwin</a></li>
[605]76
[659]77<li>
78<a href="#Linux">Linux</a></li>
[605]79
[659]80<li>
81<a href="#Free BSD">Free BSD</a></li>
[605]82
[659]83<li>
84<a href="#Mac OSX">Mac OSX</a></li>
85
86<li>
87<a href="#IRIX">IRIX</a></li>
88
89<li>
90<a href="#Solaris">Solaris</a></li>
[605]91</ul>
92</ul>
[604]93
[659]94<hr>
[637]95<h3>
[659]96<a NAME="Compiling under Windows with Visual Studio"></a><u>Compiling under
97Windows with Visual Studio.</u></h3>
[1115]98
99<p>The Microsoft Visual C++ 6.0 workspace file is VisualStudio.dsw located
100in the VisualStudio below the OSG this root directory.  VC++6.0 workspace
101files can also be used in VisualStudio7.0 without problem.
102
103<p><b>IMPORTANT NOTE:</b> Whilst the OSG will compile cleanly with the basic VC++6.0 and
104its own STL implementation, the OSG will crash regularily due to bugs in VC++6.0's
105STL.  VC++6.0's STL is horribly broken and therefore is <b>*NOT*</b> supported.  Do not
106attempt to use the OSG in conjunction with native VC++6.0 STL implemention.
107<p>The supported combinations are:
[633]108<ol>
109
[659]110<li>
[1115]111Visual Studio7.0 .NET </li>
112<li>
113Visual Studio6.0 + Dinkumware's STL bug fix patches (see details below).</li>
[633]114
[659]115<li>
[1115]116Visual Studio6.0 + STLport  (see details below)</li>
[659]117</ol>
[1115]118<p>The OSG is composed of a number of scene graph libraries (with Core in
[1862]119front of the project names), executables (with examples in front of the project
[1127]120names), and plugins which read and write 3D data formats and 2D image formats
[1115]121(with osgPlugins in front of the project names).
[1862]122To get the OSG running you'll need at least to compile Core osg,osgUtil,osgDB,osgProducer,
123osgPlugin dot_osg and Demo osgviewer. The rest of the libraries and executables
[659]124are optional and can be compiled if you need them, however for simplicity
125I would recommend doing a batch build of all the libraries and executables
126in the distribution, some of the plug-ins which support non native file
127formats may not compile due to dependencies on other libraries (such as
128libpng), you can ignore these compilation errors unless you need to load
[1862]129the related file types. To help the compilation the plugins, osgProducer and
[659]130osgText one can download .zip archive will all the dependencies in it.
131Further details on this .zip file can be found in <i><a href="dependencies.html">dependencies.html</a></i>
[1115]132
[604]133<p>To execute the viewer the file path for the .dll's and .exe, both compiled
134into the OSG's bin directory, need to be setup, such as by adding the PATH
135to your autoexec.bat, its also useful to add the OSGFILEPATH to your autoexec.bat
136to help the location of datafiles. For example :
[659]137<p>SET OSGFILEPATH=D:\OpenSceneGraph-Data;D:\OpenSceneGraph-Data\Images
[604]138<br>SET PATH=C:\WINDOWS;C:\WINDOWS\COMMAND;D:\osg-0.8.43\bin;
139<p>To help compilation of the image reader plugins, various image libraries
[659]140have been zipped up for your convenience, your find these on the OSG release
[1127]141download directory
142
[637]143<h3>
144Using Visual Studio .NET</h3>
[1127]145Visual Studio 7.0 .MET has a solid STL implementation and improve standard C++ complient
146and works with the OpenSceneGraph without problems.  This is the recommended route.
[637]147<h3>
148Using Dinkumware STL</h3>
[659]149The basic jist is that you'll need to download their STL implementation,
150and follow their instructions of how to force VisualStudio to pick up the
151new STL implementation. More details at <a href="http://www.dinkumware.com/vc_fixes.html">http://www.dinkumware.com/vc_fixes.html</a>.
152<p>Once it is installed everything should compile fine and not crash, but
153you won't be running at full speed since the build #ifdef's out some important
154state optimizations since the basic VisualStudio can't handle it. You can
155safely remove the #ifdef from src/osgUtil/Otimizer.cpp, Line 44. The #ifdef
156is smart enough to do this automatically when using VisualStudio .NET and
157STLport so that modification by hand won't be required. Unfortunately there
158doesn't seem to be a special define associated with the Dinkumware STL
159for the #ifdef to pick up on.
160<h3>
161Using STLport</h3>
[1127]162
163<p>A very good HOWTO for installing and making the STLPort libs on MSVC6
164can be found at <a href="http://www.softadvances.com/articles/stlportusing.html">http://www.softadvances.com/articles/stlportusing.html</a>
165
166
167<p>The OSG has been tested under Windows with STLport-4.5, which allows the
[604]168users to configure the type of STL support required for STLport itself.
169The key configuration that the OSG needs to do is to enable the wrapping
170of MS's own iostreams, than using STLport's own implementation. The later
171is not required because this has not be problematic under Windows, it is
[1127]172only the container classes and algorithms that need replacing. Using the iostream wrapping
[604]173option means the STLport can just be used on your include path, there is
174no need to compile STLport itself, or link into any special libraries.
175To configure STLport simply comment IN (its commented out by default),
[659]176the following line from STLport-4.5/stlport/stl_user_config.h so it should
[1127]177look:
178<ul>
179# define _STLP_NO_OWN_IOSTREAMS 1
180</ul>
181<p>Then configure the includes path in Visual Studio to pick up on STLport: Select the "Tools" menu. Select
[604]182"Options" In the Options dialog, select the "Directories" tab Under the
183"include" option, add the path to STLport4.5, something like: D:/STLport4.5/stlport
184Then press the up array to move the entry all the way to the top of the
185list, thus overriding MS's own STL implementations.
[1127]186
187<h3>Linking your own apps to the OpenSceneGraph</h3>
188<p>All OpenSceneGraph libraries, plugins and executables are compiled with
189the multi-threaded dll option turned ON, and with RTTI turned ON.  Your own
190projects which link to the OpenSceneGraph must uses these same options or
191your application will crash or produce unpredicatable behavior.
192
193
194<h3>Syntax highlight + OpenScenegraph Standard C++ style headers</h3>
195<p>The OpenSceneGraph uses Standard C++ style extensionless headers, which
196poor VisualStudio doesn't automatically recognize as suitable for
197syntax highlighting (compile works fine though), even the StandardC++
198header themselves require a hack to get VisualStudio to highlight them
199properly.  The easy answer is to use that same hack to get it to recognize
200the OpenSceneGraph headers too.  To make easy a modified header listing file
201can be found in the VisualStudio/LANDEXT.DAT.  First copy the original
202LANDEXT.DAT file (located in C:\Progam Files\Microsoft Visual Studio\Common\MSDev98\Bin)
203to LANDEXT.DAT.BKP, and then copy over the OpenSceneGraph one.  Once you have
204done this VisualStudio will syntax highlight them without problem.
[604]205<hr>
[659]206<h3>
207<a NAME="Linux"></a><u>Compiling under Linux</u></h3>
[603]208Compile, from the OSG root directory, ('%' is UNIX csh prompt) type:
209<blockquote><tt>% make</tt></blockquote>
210Note, make should automatically detect linux and build optimized targets
211for your system. And if you wish to install the OSG type:
[659]212<blockquote><tt>% make install</tt></blockquote>
[603]213or
[659]214<blockquote><tt>% make instlinks</tt></blockquote>
[603]215To get full details of make options, type:
[659]216<blockquote><tt>% make help</tt></blockquote>
[603]217(highly recommended)
218<p>The osgText library now depends upon GLU1.3 functionality, and only
[659]219the recent Mesa version have this as standard. Unfortunately not all Linux
220distributions are up to date even recent ones. If you have problems compiling
[603]221osgText due to GLU problems then check out the details at the bottom of
222this file, under the title RedHat7.1 &amp; GLU1.3 for a quick way of installing
223GLU1.3 in the right place.
[637]224<h3>
225RedHat 7.2 &amp; GLU1.3</h3>
[604]226I have posted a simple fix for those of us who have been unable to correctly
227build OSG 0.8.43 on Redhat 7.2. You can download it at http://www.openscenegraph.org/download/dependencies/ReadHat7.2_fixglu.tar.gz
228To install it, follow these steps:
229<p>English
230<blockquote>1) Untar the tarball. It will create a directory called fixosg/
231<br>2) Change to the ReadHat7.2_fixglu/ directory
232<br>3) Become root
233<br>4) Run the script called fixglu</blockquote>
234Cmd line
235<blockquote>tar xvzf ReadHat7.2_fixglu.tar.gz
236<br>cd ReadHat7.2_fixglu/
237<br>su (your root password)
238<br>./fixglu
239<br>exit</blockquote>
240You should then be able to do a "make" in your OSG directory and everything
241will build as it should. Let me know if this doesn't work and I will try
242to improve it. Email me directly for help instead of posting here. There's
243a README in the tarball with some info on what the script actually does.
244There's nothing wrong with OSG itself; the problem with Redhat 7.2 is that
245it doesn't have GLU 1.3 by default, which OSG is now dependent on (for
246osgText.) Good luck everyone. - Clay
[659]247<p>
[604]248<hr>
[659]249<h3>
250<a NAME="Free BSD"></a><u>Compiling under FreeBSD</u></h3>
[603]251Compile, from the OSG root directory, ('%' is UNIX csh prompt) type:
252<blockquote><tt>% make</tt></blockquote>
253Note, make should automatically detect linux and build optimized targets
254for your system. And if you wish to install the OSG type:
[659]255<blockquote><tt>% make install</tt></blockquote>
[603]256or
[659]257<blockquote><tt>% make instlinks</tt></blockquote>
[603]258To get full details of make options, type:
[659]259<blockquote><tt>% make help</tt></blockquote>
[603]260(highly recommended)
[659]261<p>
[604]262<hr>
[659]263<h3>
264<a NAME="IRIX"></a><u>Compiling under IRIX</u></h3>
[603]265Since the OSG uses Standard C++ features such as STL it is important to
266have an up to date version of the MIPSPro compilers, ie. 7.3 or later.
267Support for MIPSPro7.2.1 has now been dropped since it was becoming to
[659]268unwildy to support and is very rarely used in the OSG community. It is
[603]269recommended to use MIPSPro7.3.1.1m.
270<p>Compile, from the OSG root directory, ('%' is UNIX csh prompt) type:
271<blockquote><tt>% make</tt></blockquote>
272Note, make should automatically detect linux and build optimized targets
273for your system. And if you wish to install the OSG type:
[659]274<blockquote><tt>% make install</tt></blockquote>
[603]275or
[659]276<blockquote><tt>% make instlinks</tt></blockquote>
[603]277To get full details of make options, type:
[659]278<blockquote><tt>% make help</tt></blockquote>
[603]279(highly recommended)
[604]280<br>
281<hr>
[659]282<h3>
283<a NAME="Solaris"></a><u>Compiling under Solaris</u></h3>
[603]284Compile, from the OSG root directory, ('%' is UNIX csh prompt) type:
285<blockquote><tt>% make</tt></blockquote>
286Note, make should automatically detect linux and build optimized targets
287for your system. And if you wish to install the OSG type:
[659]288<blockquote><tt>% make install</tt></blockquote>
[603]289or
[659]290<blockquote><tt>% make instlinks</tt></blockquote>
[603]291To get full details of make options, type:
[659]292<blockquote><tt>% make help</tt></blockquote>
[603]293(highly recommended)
[604]294<br>
295<hr>
[659]296<h3>
[914]297<a NAME="Mac OSX"></a><u>Compiling under MacOS X</u></h3>
298For anyone who's ever used a Unix box for development, well, the mac
299<i>is</i> a Unix box. It's very simple to get OpenSceneGraph building
300and running under Mac OS X. The main requirement is that you need to have
301installed the Developer tools from the CD that comes
[603]302for free with OS X. This gives you compilers, headers, frameworks - stuff
[1862]303like Producer and Carbon for developers. Get those here:
[914]304
305<ul>
306<li> The Apple <a href="http://developer.apple.com/tools/macosxtools.html">
307    developer tools website</a>.
308</ul>
309
310<p>Everything is done command-line, so you need to get to a shell before
311proceeding. The Mac comes with an app in Applications/Utilities
[603]312called Terminal - open up any Finder window (e.g double-click on your hard
313disk icon), click on the Applications icon at the top right of the window,
[914]314then click on the Utilities folder to get access to the Terminal.
315When you start Terminal it brings you up a csh running from your ~/ directory.
316Now, go to your OpenSceneGraph directory, and simply type:
317<p>
318<blockquote>
319<tt>make -j2</tt>
320</blockquote>
[603]321
[914]322And some time later you'll be rewarded with a lovely set of binaries and
323libraries. The Mac OSX build currently only builds a subset of the total
324functionality in OpenSceneGraph, but a large subset at that. Some of
325the remaining projects are known to build as well, but have external
326dependencies on libraries such as libtiff, libjpg, libpng, etc. and
327so are not included in the default build. However, if you examine
328the file <tt>OpenSceneGraph/Make/makedefs</tt> you will find which extra
329projects build for the mac, provided you have the external libraries
330required. Details
331on how to install these external libraries are outside the scope of
332this document, but for starting points, see one of:
333<ul>
334<li> The <a href="http://fink.sourceforge.net">fink project</a>.
335<li> The <a href="http://gnu-darwin.sourceforge.net/">GNU-Darwin project</a>.
336</ul>
337<h4> Running the examples </h4>
338Once you've got OpenSceneGraph built, you're ready to run your examples.
339As with other builds on other platforms, OpenSceneGraph requires
340you to set a few environment variables which describe your installation. These
341environment variables should be full-path, not relative, and a list
342of these for a csh-derived environment follow:
[603]343
[914]344<blockquote>
345<tt>
346setenv OSGHOME              `pwd`/OpenSceneGraph <br>
347setenv OSGFILEPATH          `pwd`/OpenSceneGraph-Data <br>
348setenv OSG_LD_LIBRARY_PATH  ${OSGHOME}/lib <br>
349setenv DYLD_LIBRARY_PATH    ${OSG_LD_LIBRARY_PATH} <br>
350</tt>
351</blockquote>
352
353<h4> Notes </h4>
354
355<ul>
356<li> <b>Input Focus</b>: Many OSG examples have keyboard commands, however, when launching
357apps from the Mac Terminal, the focus seems to remain in the Terminal. Option-Clicking on
358the graphics window focuses it as the recipient of events, and allows these keyboard commands
359to then function properly.
360<li> <b>Known Bugs</b>:
361<li> <b>Installation</b>: No package based version of an OS X installer yet exists.
362</ul>
363
[659]364<h3>
365<a NAME="Cygwin"></a><u>Compiling under Cygwin</u></h3>
[603]366To compile, from the OSG root directory, type: make Note, make should automatically
367detect your system and build optimized targets for your system. And if
368you wish to install the OSG type: make install Note that make symbolic
369links don't seem to work under cygwin, so a make instlinks will simply
370copy files just like make install. 'make install' places all files in /usr/local/OpenSceneGraph
[659]371under appropriate sub directories. To get full details of make options,
[603]372type: make help (highly recommended)
[659]373<p>OSG_FILE_PATH environmental variable
374<p>For the OSG to locate file data files easily an environmental variable
375OSG_FILE_PATH is used at run-time by the osgDB library. Note, for examples
[603]376below substitute in the ${OSGDATA} directory with your own path where appropriate)
[659]377Add the following to your .cshrc (note paths separated by colon's): setenv&nbsp;
378OSG_FILE_PATH ./:${OSGDATA}:${OSGDATA}/Images Or the following if you're
379using a sh compatible shell : export&nbsp; OSG_FILE_PATH=./:${OSGDATA}:${OSGDATA}/Images:
380Or under windows (note paths seperated by semi-colon's) : SET&nbsp; OSG_FILE_PATH=./:${OSGDATA};${OSGDATA}/Images
[603]381</body>
382</html>
Note: See TracBrowser for help on using the browser.