Installation Guide

The following installation guide assumes that user have not root privileges and the non-standard software may not be pre-installed on the given machine.

Following libraries are assumed to be installed in the system (with headers):

  • libpcre
  • libxml2
  • libjpeg (version 6.2)
  • liblua (version 5.1)
  • libgl1-mesa
  • libglu1-mesa
  • libssl

The guide will cover installation of following software packages:

  • Boost
  • Collada DOM
  • OpenVRML
  • OpenSceneGraph
  • Vitrall

In the scope of the following document, it is assumed that environment variable VITRALL_ROOT points to a directory where all software packages will be installed (including Vitrall itself), for example:

export VITRALL_ROOT=$HOME/vitrall

Create directory structure for locally installed software:

cd $VITRALL_ROOT
mkdir -p installs
mkdir -p local
cd local
mkdir -p lib
mkdir -p include
mkdir -p bin

Add $VITRALL_ROOT/local/bin to your PATH environment.

Vitrall does not support configuration of dynamically loaded external libraries yet. Because of this, it is needed to use LD_LIBRARY_PATH:

export LD_LIBRARY_PATH=$VITRALL_ROOT/local/lib:$VITRALL_ROOT/local/lib64:$LD_LIBRARY_PATH

Boost

Typically, Boost should be available through system repositories of your distribution. If version found there is too old or if you don't have root privileges to the system, then proceed with following:

Download and extract into directory:

$VITRALL_ROOT/installs

the newest version of  Boost libraries. After archive decompression export directory containing extracted Boost into environment variable BOOST_ROOT, for example:

export BOOST_ROOT=$VITRALL_ROOT/installs/boost_1_48_0

Then compile Boost (it may take a while).

cd $BOOST_ROOT
./bootstrap.sh --with-libraries=filesystem,thread,program_options,regex,python,system,random
./b2

If the compilation was successful:

cd $VITRALL_ROOT
ln -s $BOOST_ROOT/boost $VITRALL_ROOT/local/include/boost
cp $BOOST_ROOT/stage/lib/*.so* $VITRALL_ROOT/local/lib

Vitrall also uses following Boost libraries:

  • Asio,
  • Bind,
  • Function,
  • Optional,
  • Ref,
  • Property Tree,
  • Smart Ptr,
  • String Algo.

CMake

An exhaustive documentation of CMake is available  here.

In the following of the guide, source-dir will stand for the directory containing Vitrall server source code (usually repo/trunk/src/vitrall), and build-dir will stand for the directory, in which project tree will be created by CMake, and binaries will be built. It is strongly encouraged to build project in a directory separate to the repository directory.

CMake supports a variety of development environments, just substitute generator-name in command below with one of the generators listed in the end of:

$ cmake --help

For example, to create simple unix makefiles:

$ cd build-dir
$ cmake -G "Unix Makefiles" source-dir

CMake automatically searches for needed libraries. If CMake failed to create project tree, probably some needed libraries were not found in the system. Refer to library dependencies? for more information. If everything went ok, you can start to build Vitrall using IDE of your choosing, for example:

$ make

Collada DOM

The latest versions Collada Dom project (2.3 and 2.3.1) cause segmentation fault in both Vitrall and osgviewer applications.

The latest versions which runs correctly is 2.2, available here:  http://sourceforge.net/projects/collada-dom/files/Collada%20DOM/Collada%20DOM%202.2/. Download it and extract into:

$VITRALL_ROOT/installs

To install, execute below commands:

cd $VITRALL_ROOT/installs/collada-dom
cp Makefile.linux Makefile

Add following lines:

includeOpts += -I$(VITRALL_ROOT)/local/include
libOpts += -L$(VITRALL_ROOT)/local/lib

in file: ./dom/make/dom.mk before last line (containing include make/rules.mk).

Add following line:

prefix := $(VITRALL_ROOT)/local

in file ./dom/Makefile in line number 198 (just before .PHONY: uninstall).

mv dom/include/1.4/dom/domasset.h dom/include/1.4/dom/domAsset.h
make os=linux project=minizip -C dom
cp dom/build/linux-1.4/libminizip.so dom/build/linux-1.4/libminizip.a $VITRALL_ROOT/local/lib
make os=linux project=dom -C dom
make os=linux project=dom -C dom install

OpenVRML

The latest version of OpenVRML - 0.18.9 (the one available from debian repository) is not compatible with OpenSceneGraph?.  http://trac.openscenegraph.org/projects/osg/wiki/Support/PlatformSpecifics/Linux recommends 0.17.12 version, version 0.17.2 was also tested. Library is available at  http://sourceforge.net/projects/openvrml/files/openvrml/

After downloading the source package do the following

cd openvrml-0.17.2 
mkdir build
cd build
../configure --disable-script-node-java --disable-xembed --disable-player --disable-mozilla-plugin --disable-examples --disable-script-node-javascript
make
make install

OpenSceneGraph

Current downloads of OpenSceneGraph source code can be found here:  http://www.openscenegraph.org/projects/osg/wiki/Downloads. To get the svn address visit:  http://www.openscenegraph.org/index.php/community/news/130-new-svn-repository-url. Download latest release and extract into:

$VITRALL_ROOT/installs

Export extracted OSG directory into environment variable OSG_ROOT, for example:

export OSG_ROOT=$VITRALL_ROOT/installs/OpenSceneGraph-3.0.1

Do the following:

cd $VITRALL_ROOT/installs
mkdir -p osg-build
cd osg-build
cmake $OSG_ROOT
cmake -D CMAKE_INSTALL_PREFIX:STRING=$VITRALL_ROOT/local .
cmake -D CMAKE_PREFIX_PATH:PATH=$VITRALL_ROOT/local .

If you would like to build OSG examples:

cmake -D BUILD_OSG_EXAMPLES:BOOL=true .

It may happen that cmake will fail to find Collada DOM headers. To check if this is the case, run:

cmake -L .

and search for variable COLLADA_INCLUDE_DIR. If it is set to NOTFOUND, following command should fix the problem:

cmake -D COLLADA_INCLUDE_DIR:PATH=$VITRALL_ROOT/local/include/colladadom .

Finally, compile and install (it may take some time):

make
make install

You may check whether OSG is properly configured (especially library linking issues), by running:

osgviewer $VITRALL_ROOT/repo/trunk/resources/models/vitrall.dae

Luabind

Luabind can be downloaded from  here (version 0.9.1 is checked, headers from version 0.9.0 have a known bug?). Extract it into:

$VITRALL_ROOT/installs

and change directory to the luabind directory.

Create file CMakeLists.txt with following content:

cmake_minimum_required (VERSION 2.6)
project (LUABIND)

set(BUILD_SHARED_LIBS ON)
file(GLOB FILES src/*.cpp)

include_directories(. ${VITRALL_ROOT}/local/include /usr/include/lua5.1 /usr/include/lua)
 
add_library (luabind ${FILES} )

Execute:

cmake .
cmake -D VITRALL_ROOT:PATH=$VITRALL_ROOT .
make
ln -s `pwd`/luabind $VITRALL_ROOT/local/include/luabind
ln -s `pwd`/libluabind.so $VITRALL_ROOT/local/lib/libluabind.so

libjpeg-turbo

Library  libjpeg-turbo provides JPEG compression routines using vector processor instructions and implements API of libjpeg library, so it is a drop-in replacement of the latter.

 NASM is needed to compile this library.

To install libjpeg-turbo checkout from it's svn repository:

cd $VITRALL_ROOT/installs
svn co https://libjpeg-turbo.svn.sourceforge.net/svnroot/libjpeg-turbo/trunk libjpeg-turbo
cd libjpeg-turbo
autoreconf -fiv
./configure --prefix=$VITRALL_ROOT/local
make
make install

Vitrall

First, check out source from project repository.

cd $VITRALL_ROOT
svn checkout --username <name> https://apps.man.poznan.pl/svn/vitrall/trunk repo
mkdir build
cd build
cmake ../repo/server
cmake -D CMAKE_PREFIX_PATH=$VITRALL_ROOT/local .

You may now tailor Vitrall configuration of Vitrall build to your specific needs by running:

cmake -i .

When you are done, execute:

make

Remember to have LD_LIBRARY_PATH include $VITRALL_ROOT/lib and $VITRALL_ROOT/lib64.

Script ./element.sh is a convenience method for fast choosing which modules to build. You may use:

./element.sh xml echo.xml

to build all modules that are needed for this configuration.

You may run test Vitrall server with command:

./vitralld echo.xml

and:

You may run a testing rendering configuration:

./vitralld demonstration.xml

Add to the command line:

--var model=models/native/vitrall.ac

if you haven't compiled OSG with COLLADA support.