Skip to content

Building

Jump to bottom Edit New page
Alessandro Febretti edited this page Mar 17, 2016 · 46 revisions

Building omegalib

✔️ Last revision: ver. 6.0-alpha2 - 27 June 2014

👾 DEPRECATED the information in this page refers to an old version of Omegalib and needs to be updated. To build omegalib, simply use the Maintenance Tools (see next note)

📝 NOTE: This page explains how to build omegalib manually, using CMake and your native build system. This may be needed if you want to fine-tune a build, but in most cases you can just use the Maintenance Tools

On most platforms, omegalib is distributed as a source-only project. Users are responsible for creating binaries for their operating system and architecture. The build process is kept as simple as possible and should require very little configuration effort by the user. Omegalib can build out-of-the-box and has no external dependencies, unless the user wants to activate advanced functionalities like vtk support and osgEarth.

The OMEGA_HOME environment variable

After downloading and extracting omegalib, you will probably want to create a new environment variable called OMEGA_HOME, and point it to the extraction directory. Omegalib uses this directory to find data, modules and other omegalib components. If you plan to launch applications directly from this directory, creating the environment variable is not needed, but won't hurt.

On windows, you also want to add the extracted directory bin folder to your PATH, or external omegalib applications will not be able to find the omegalib dlls.

Operating system support

This is the current supported status of omegalib:

  • Windows 7/8: VS2013, 32bit builds and is regularly tested. VS2012 32bit and lower deprecated and may not work. 64bit core builds might work but require cmake options tweaking and are not tested regularly. 64bit builds of third party modules not tested.
  • Linux: 64bit builds and is regularly tested (SUSE). 32bit tested and running on Ubuntu.
  • OSX, Intel: Works on Mac OSX 10.7 and higher.

Building on Windows

This section explains how to build omegalib on Windows. The basic procedure and requirements are similar for all supported operating systems, so you can use this as a general guideline.

Requirements

Step 1: Download and configure the build

  • clone the repository, in recursive mode (to make sure the omicron submodule is initialized): git clone https://github.com/febret/omegalib.git --recursive
  • Run cmake-gui.
  • In the where is the source code field, specify the directory where you checked out the source code.
  • In the where to build the binaries field, specify a directory you will want your project files and binaries to be generated.
  • Hit Configure: The option table will look simlar to the following figure:

*The Windows CMake GUI. Versions on other operating systems have a similar layout.*

- Enable and disable desired options. For a guide on options go to the bottom of this page. **Note:** omegalib should build just fine if you leave everything to their default values. - **Important!** hit **configure** again, **even if you didn't change anything**. You may have to repeat this process multiple times if you changed options and new options appear. - Once you are done configuring all build options, hit **Generate**. If the process ends without errors, you will have Visual Studio solution files under your build directory.

👉 SUGGESTION: Keep both directories under a single 'root' folder. For example you can have something like this

Step 2: building

You should now be able to open the generated Visual Studio solution and build everything. If you encounter any problem take a look at the How to guide.

Step 3: running a demo

You can run a demo by going on the output folder of your binary directory (bin/debug or bin/release depending on which configuration you built). A good basic demo to test is ohello.exe:

*If you see this, you have succesfully built omegalib. You deserve ice cream!* 🍦

Another way to run an application is to right click on it inside visual studio (all applications are in the apps solution folder), select Set as StartUp Project and click on the run button.

Building on Mac / Linux

As for windows, you will need git and cmake installed. Use the package manager that comes with your OS/Distro to find and install them. On linux, you will also need the following installed

  • OpenGL development libraries (freeglut3, freeglut3-dev)
  • Python development libraries (python-dev)
  • Flex and bison (flex and bison)
  • To install all of them on Ubunto do sudo apt-get install freeglut3 freeglut3-dev python-dev xorg-dev)

Together with other basic libraries and tool like the openGL developement libs and the g++ compiler

Fast install script

👾 DEPRECATED: The fast install script still exists but it is deprecated and has been substituted by cross-platform quick build scripts. Use them instead. This section will be removed when the fast install script is retired.

To perform a quick download and build of omegalib on Linux or OSX, you can use this script: http://uic-evl.github.io/omegalib/getomega

Just download the script somewhere, make it executable and run it:

> wget http://uic-evl.github.io/omegalib/getomega
> chmod +x getomega
> ./getomega

That's it! The script will clone the git repository, generate a makefile for your platform and start a build. Go get a ☕. This will take a bit 😄

By default the command builds the master version of omegalib. If you want to build a specific tagged version, add its name as a command line argument, like ./getomega v4.1. The script will create a separate directory for every version you build, so you can have more than one side-by-side.

If you want to see a list of available versions type ./getomega versions.

Step-by-step instructions

The basic instructions are the same as for the Windows guide. Under linux, you will use make as your build system. To summarize, the process will be:

  • create a new directory for omegalib:
  • mkdir omegalib
  • cd omegalib
  • Download the omegalib source code:
  • git clone https://github.com/uic-evl/omegalib.git --recursive
  • create a build directory
  • mkdir build
  • cd build
  • run cmake using one of the following commands:
  • cmake -i ../source
  • ccmake ../source
  • cmake-gui.
  • (The commands will respectively run an interactive shell version of cmake, a curses based version, and a gui version similar to the windows one)
  • Follow the same steps as the one in windows to generate a makefile
  • run make
  • if the build succeeds, get in the build/bin directory and you should find your libraries and compiled demo applications.

Running on Mac

To run any omegalib app, you initially need to have X11 running. Go to /Applications/Utilities/ and run X11. If X11 is not running, you will get an error that the display cannot be initialized and see nothing!

Environment variables on mac

If you want to run omegalib applications from any directory, you will need to set some environment variables. What follows is an example of environment variables you should set on your system, where <OMEGA_BUILD_DIR> should be substituted to the path of your omegalib build directory.

setenv PATH $PATH:<OMEGA_BUILD_DIR>/bin
setenv DYLD_LIBRARY_PATH <OMEGA_BUILD_DIR>/bin:<OMEGA_BUILD_DIR>/bin/osg:<OMEGA_BUILD_DIR>/bin/osg/osgPlugins-3.3.0

Installing modules

Starting form version 5.0, omegalib features a fully modular design. This new design allows users to start with a very lightweight version of omegalib, and customize it with the modules they need. Modules are kept in separate repositories so each revision history is separate, and development by different users is easier. Modules can be installed at configuration time in CMake, either by clicking on the checkboxes for modules you want to install, or by listing the desired module names in the MODULES cmake variable.

*How to install omegalib modules using the CMake GUI*

Due to its new modular design, a few modules that were previously included in the omegalib core are now offered as separate modules. In particular these modules are cyclops, omegaOsg, omegaVtk, rift, mvi, caveutil, cavevoc, sprite, pointCloud.

If you want to create a cmake build that contains all the modules previously offered with omegalib 4.x (and a few more), simply use this cmake command:

build> cmake <path-to-omega-source> -DMODULES="common-modules"

The common-modules module (you can see it here: https://github.com/omega-hub/common-modules/blob/master/CMakeLists.txt) is a simple, empty bundle module that just installs all the previously listed modules as its dependencies.

General troubleshooting

Configuration errors

At startup, omegalib looks for a file named default.cfg to configure the system and application. This file can be in your current working directory or, if one is not found there, omegalib will look in up in the omegalib source directory under data. You can see the content of this file here: https://github.com/febret/omegalib/blob/master/data/default.cfg

By default, this file just redirects omegalib to the right system configuration file. If you are running on your laptop, you want to make sure systemConfig="system/desktop.cfg is the only uncommented line in the file.

For a full reference on configuration files check the [ConfigReference] page.

CMake options

This section is a quick guide to some build options offered in cmake.

  • OMEGA_ENABLE_VLD: WIndows only, enabled a memory leak detector for debug builds of the library. Will significantly slow down omegalib applications.
  • OMEGA_USE_DISPLAY_EQUALIZER: Enables Equalizer display system support. You should leave this turned on.
  • OMEGA_USE_DISPLAY_GLUT: Enables GLUT display system support. GLUT support is not really tested and may be broken. By default, omegalib uses the Equalizer display system even if you leave this option on, so you should not need to change it.
  • OMEGA-ENABLE-AUTO-UPDATE: WIndows only, enables the omegalib auto-updater in orun
  • OMEGA-HUB-URL: The url of the github repository containing the module list
  • MODULES: A space-separated list of modules to install. Alternative to checking modules in the MODULES_ section of the CMake configuration.
Add a custom footer
Add a custom sidebar
Clone this wiki locally