OpenSceneGraph/INSTALL
2002-04-18 16:08:36 +00:00

474 lines
17 KiB
Plaintext

The following is a very basic intro of how to get the OSG going under Linux,
FreeBSD, IRIX, Windows and Mac. Each intro mentions OpenSceneGraph-Data, it is
recommended that you also download it alongside this source distribution.
The scene graph depends upon Standard C++, STL and OpenGL so you need a C++
compiler up to the task and OpenGL or Mesa installed. The viewer depends upon
GLUT which you'll need to download and install from the GLUT website. The
OSG has it own native ascii file format, and .rgb image reader inbuilt which
allows you read the example data with any dependencies other than C++, STL and
OpenGL.
The new osgText library adds the dependency of the freetype library for support
of true type fonts, however it is not essential to the core library, so you can
comment it out from compilation by modifying the src/Makefile, and src/Demos/Makefile.
I you wish to use fonts then you can download freetype from www.freetype.org. The
osgText library also requires an up to date GLU implementation which supports
GLU1.2 tessellation routines. If you your current GLU is out of date you'll need
to download the latest, for instance the sgi's sample implementation for
GLU from the www.opengl.org website.
The OSG also has a set of plug-ins which support non-native 3d database and
image formats, several have no dependencies on external libraries (flt,3ds,obj,
lwo,dw, tga & pic), while others (pfb,jpeg,gif,tiff) require other libraries
to be installed to compile them. If you don't already have them installed then
don't worry, you'll still be able to use the OSG, just comment out the plugins
you can't compile from the src/osgPlugins/Makefile. The core osg library and
viewer has been designed to load the plug-ins at run-time only and if they
are required to load a specific data set. If you don't need them for your
datasets then it won't matter that you haven't been able to compile
all the plug-ins. A full list of dependencies and where to download the
required libraries are listed in the index.html.
If you're coming across the OSG for the first time and want to get started
quickly, go right ahead and follow the compilation instructions. You can
always later download the libraries which the plug-ins require if you
eventually need them.
If you haven't already checked it out, for a list of distribution contents,
contacts and links to documentation check out index.html.
Compiling under all (UNIX - including CYGWIN) Platforms
-------------------------------------------------------
Building the OSG requires 'gmake', due to the extensive use of gmake
directives in the Makefiles. You can get gmake from here if you don't
already have it installed:
http://www.gnu.org/software/make/
Compiling under Linux
---------------------
To compile, from the OSG root directory, type:
make
Note, make should automatically detect linux and build
optimized targets for your system.
And if you wish to install the OSG type:
make install
or
make instlinks
To get full details of make options, type:
make help
(highly recommended)
The osgText library now depends upon GLU1.3 functionality, and only
the recent Mesa version have this as stanadard. Unfortnately not all
Linux distribtions are upto date even recent ones. If you have problems
compiling osgText due to GLU problems then check out the details at the
bottom of this file, under the title RedHat7.1 & GLU1.3 for a quick
way of installing GLU1.3 in the right place.
Compiling under FreeBSD
-----------------------
To compile, from the OSG root directory, type:
make
Note, make should automatically detect your system and build
optimized targets for your system.
And if you wish to install the OSG type:
make install
or
make instlinks
To get full details of make options, type:
make help
(highly recommended)
Compiling under IRIX
--------------------
Since the OSG uses Standard C++ features such as STL it is important
to have an up to date version of the MIPSPro compilers, ie. 7.3 or later.
Support for MIPSPro7.2.1 has now been dropped since it was becoming to
unwildy to support and is very rarely used in the OSG commiunity.
It is recommended to use MIPSPro7.3.1.1m.
To compile, from the OSG root directory, type:
make
Note, make should automatically detect your system and build
optimized targets for your system.
And if you wish to install the OSG type:
make install
or
make instlinks
To get full details of make options, type:
make help
(highly recommended)
Compiling under Solaris
-----------------------
To compile, from the OSG root directory, type:
make
Note, make should automatically detect your system and build
optimized targets for your system.
And if you wish to install the OSG type:
make install
or
make instlinks
To get full details of make options, type:
make help
(highly recommended)
Compiling under Windows
-----------------------
The Microsoft Visual C++ 6.0 workspace file is VisualStudio.dsw located
in the VisualStudio\ below the OSG this root directory. The OSG will
compile with the basic VisualC++6.0, but its recommended that you use
Service Pack 4 to fix MS compiler bugs which affect the OSG. Even
Service Pack 4 does not completely fix MSVC bugs associated with STL, so
it is recommended that you also use STLPort which can be downloaded
from http://www.stlport.org since they actually know how to write a
STL library and have done a rather good job at it. Notes on using
STLport at the bottom of this file.
The OSG is composed of a number of libraries and executables, to get
running you'll need at least to compile osg,osgUtil,osgDB,osgGLUT,
dot_osg and sgv. The rest of the libraries and executables are
optional and can be compiled if you need them, however for simplicity
I would recommend doing a batch build of all the libraries and executables
in the distribution, some of the plug-ins which support non native file
formats may not compile due to dependencies on other libraries (such
as libpng), you can ignore these compilation errors unless you need
to load the related file types.
To execute the viewer the file path for the .dll's and .exe, both compiled
into the OSG's bin directory, need to be setup, such as by adding the PATH
to your autoexec.bat, its also useful to add the OSGFILEPATH to your
autoexec.bat to help the location of datafiles. For example :
SET OSGFILEPATH=D:\OpenSceneGraph-Data;D:\OpenSceneGraph-Data\Images
SET PATH=C:\WINDOWS;C:\WINDOWS\COMMAND;D:\osg-0.8.43\bin;
To help compilation of the image reader plugins, various image libraries
have been zipped up for your convienice, your find these on the OSG
release download directory.
Compiling under MacOS 9
-----------------------
The Microwerks Codewarrior workspace files can be found under the
Microwerks directory. Further details to be fleshed out since
Mac port is in its early stages and is not uptodate with the
current release. To get it compiling you will have to use these
Codewarrior files as a starting place. If you get it running and
have time to maintian the port please email robert@openscenegraph.org.
Compiling under MacOS X (instructions written by Phil Atkin)
------------------------------------------------------------
For anyone who's ever used a Unix box for development it really is so simple
it's insane.
You need to have installed the Developer tools from the CD that comes for
free with OS X. This gives you compilers, headers, frameworks - stuff like
GLUT and Carbon for developers.
Everything is done command-line, so you need to get to the underlying OS
rather than the Aqua gloss. The Mac comes with an app in
Applications/Utilities called Terminal - open up any Finder window (e.g
double-click on your hard disk icon), click on the Applications icon at the
top right of the window, then click on the Utilities folder to get access to
all the grubby apps which give away the real OS roots underneath the shiny
paintwork. Anyone developing will need Terminal so much they should put it
in their Dock. You do that by grabbing the icon of the app in the Utilities
folder and dragging it to the bottom of your screen, at which point the
other app icons in the Dock slide away to leave a gap which when you release
the mouse button leaves Terminal permanently available, just a mouse click
away on your desktop. When you start Terminal it brings you up a csh
running under Darwin (which is the BSD-with-knobs-on that underlies OS X),
and does a cd to ~ (otherwise /Users/username of whoever you are logged in
as, as far as the Finder in OS X is concerned you are in the Users/username
folder of the harddisk the machine booted from).
Then you are in Unix land, and it's all very familiar.
You will need a .cshrc file with $OSGHOME (as above), and
this is a filename that the Mac won't let you see from the Finder or in fact
generate from an app, so I used vi to create that. Then I just went
cd $OSGHOME
make clean
make
And it sounds too good to be true but it is that simple. It's worth doing
some editing on the Makefiles in the Plugins and Demos directories so that
it only tries to build a subset, otherwise the developer will have to dig
out the support projects like jpeg etc. I have only built up to now sgv,
hangglide, osgcube, osgreflect, osgviews and in the Plugins have built osg
rgb 3ds and a couple others - will check and get back to you.
Tricky bit -
Installing the libdl.a is more trouble, as you have to enable the root
account on the machine, which by default is switched off as the machines
ship for security reasons. Rather than typing in and risking error through
paraphrase, here is a link to a site which tells you how to do this -
http://www.macos.utah.edu/Documentation/macosx/security/enablerootuser.html
Or alternately
http://www.thinkmacintosh.com/osxfaq.html
One you have a root account enabled, you have to su root you cd to the
directory which the Fink installer generates, and it puts libdl.a and the
associated .h files in sensible system places so the compiler just finds
them.
There is one oddball problem - if you rely on Path to find the resulting
executables, a weird Core Graphics error occurs - so even though I set up my
path to include $(OSGHOME)/bin, and when I cd to $OSGHOME and type for
example hangglide, the application starts fine (so it is in the path), but
at the point it tries to use GLUT to open a window it falls over with a CGS
error (which is I think Core Graphics System). If you explicitly go
bin/hangglide it works fine. Weird, it may be an OS X 10.04 issue which is
gone in 10.1 or it may be a weirdy in the Mac GLUT implementation, but
forewarned is forearmed.
Compiling under Cygwin
----------------------
To compile, from the OSG root directory, type:
make
Note, make should automatically detect your system and build
optimized targets for your system.
And if you wish to install the OSG type:
make install
Note that make symbolic links don't seem to work under
cygwin, so a make instlinks will simply copy files just like
make install. 'make install' places all files in
/usr/local/OpenSceneGraph under appropriate subdirectories.
To get full details of make options, type:
make help
(highly recommended)
OSGFILEPATH environmental variable
----------------------------------
For the OSG to locate file data files easily an environmetal variable
OSGFILEPATH is used at run-time by the osgDB library. Note, for examples
below substitute in the ${OSGDATA} directory with your own path
where appropriate)
Add the following to your .cshrc (note paths seperated by colon's):
setenv OSGFILEPATH ./:${OSGDATA}:${OSGDATA}/Images
Or the following if you're using a sh compatible shell :
export OSGFILEPATH=./:${OSGDATA}:${OSGDATA}/Images:
Or under windows (note paths seperated by semi-colon's) :
SET OSGFILEPATH=./:${OSGDATA};${OSGDATA}/Images
Running the demos
-----------------
To run the viewer demo type (you made need to type rehash first under Unix) :
sgv cow.osg
sgv lz.rgb
or
sgv Spinnercar.flt
sgv Alley.3ds
sgv town_ogl_pfi.pfb
or
sgv -stereo cow.osg (see doc/stereo.html for further details)
or
sgv -stencil cow.osg (to turn on use of the stencil buffer and
enable the overdraw stats mode.)
or
sgv (with no arguments prints out usage to console.)
Other run other demos type
osgcube
or
hangglide
hangglide master.flt
or
osgreflect cow.osg
or
osgconv Alley.3ds Alley.osg
or
osgtexture lz.rgb tree.rgb
or
osgimpostor cow.osg
or
osgviews glider.osg
(Note: the file is picked up by checking the directories pointed to
by $OSGFILEPATH)
Plug-in dependencies
--------------------
You may have compile errors if you don't have all the required libraries,
especially for the plugins. As long as the core libraries osg, osgUtl,
osgGLUT and sgv have compiled you won't have any problems running the osg
itself but may not be able to use some non-native data formats. To get
the problematic plugins working you may need to download support libraries
such as libtiff, libjpeg etc. For further details see index.html.
Using STLport under Windows
---------------------------
The OSG has been tested under Windows with STLport-4.5, which allows
the users to configure the type of STL support required for STLport
itself. The key configuration that the OSG needs to do is to enable
the wrapping of MS's own iostreams, than using STLport's own
implementation. The later is not required because this has not be
problematic under Windows, it is only the container classes and
algorithms that need replacing (thanks to MS's utterly hopeless
implementation of these). Using the iostream wrappping option means
the STLport can just be used on your include path, there is no need to
compile STLport itself, or link into any special libraries.
To configure STLport simply comment IN (its commented out by default),
the follwing line from STLport-4.5/stlport/stl_user_config.h so it
should look:
# define _STLP_NO_OWN_IOSTREAMS 1
Then configure the includes path in Visual Studio to pick up on STLport:
Select the "Tools" menu.
Select "Options"
In the Options dialog, select the "Directories" tab
Under the "include" option, add the path to STLport4.5, something like:
D:/STLport4.5/stlport
Then press the up array to move the entry all the way to the top of the
list, thus overriding MS's own STL implementations.
RedHat 7.2 & GLU1.3
-------------------
I have posted a simple fix for those of us who have been unable to
correctly build OSG 0.8.43 on Redhat 7.2. You can download it at
http://www.openscenegraph.org/download/dependencies/ReadHat7.2_fixglu.tar.gz
To install it, follow these steps:
English
-----------
1) Untar the tarball. It will create a directory called fixosg/
2) Change to the ReadHat7.2_fixglu/ directory
3) Become root
4) Run the script called fixglu
Cmd line
-------------
tar xvzf ReadHat7.2_fixglu.tar.gz
cd ReadHat7.2_fixglu/
su
(your root password)
./fixglu
exit
You should then be able to do a "make" in your OSG directory and
everything will build as it should. Let me know if this doesn't
work and I will try to improve it. Email me directly for help instead of
posting here.
There's a README in the tarball with some info on what the script
actually does. There's nothing wrong with OSG itself; the
problem with Redhat 7.2 is that it doesn't have GLU 1.3 by default,
which OSG is now dependent on (for osgText.)
Good luck everyone.
- Clay
<clayfowler@earthlink.net>