Build Instructions

Posted on August 30, 2011 by Admin

Note: this documentation page is based on version 0.16.0 (not out yet) of OpenViBE

Introduction

Before building the software be sure to check the list of compatible systems and architectures.

To obtain the source code packages of OpenViBE visit our downloads page. The source code repository is hosted on the Inria gForge.


In order to build OpenViBE correctly, the source code must be in a path containing no spaces and no special characters such as &, |, (, ) etc.

  • Good example : C:\work\openvibe\repository
  • Bad example (blanks) : C:\Program Files\openvibe

Source code organization

Before you build the software it is a good idea to understand the underlying structure of the code. The project repository is composed of several software modules. Each software module can have its own branches and tags and is compiled separately from other modules. The repository basically looks like this :

root of the repository
 + <tags>
    + <0.1.0>
    + <0.2.0>
    + ...
 + <trunk>
    + <openvibe> (API / specifications)
    + <openvibe-kernel> (kernel implementation)
    + <openvibe-toolkit> (development help components)
    + <openvibe-applications> (OpenViBE user applications)
       + <acquisition-server>
       + <designer>
       + ...
    + <openvibe-plugins> (OpenViBE plugin collections)
       + <samples>
       + <acquisition>
       + ...
    + <openvibe-modules> (abstraction and portability components)
       + <ebml>
       + <socket>
       + ...

Each software module has its own subtree which looks like the following:

root of the module
 + <trunc> (current stable version)
 + <branches> (work in progress, probably very unstable)
    + wip-developer1-feature
    + wip-...

Finally, in each branch, each software module is divided in the following UNIX-like tree :

+ <bin> (target folder for compiled binaries)
+ <doc> (target folder for compiled documentation)
+ <etc> (target folder for configuration files)
+ <include> (target folder for API headers)
+ <lib> (target folder for compiled libraries)
+ <share> (shared file folder for all data)
+ <src> (source code of the module)
   + <doc> (documentation files for the module)
+ <test> (unit test source code for the module)

After a successful build, the result can be found in the dist directory created by the build process. All the share folders and subfolders of the compiled modules are copied in the build target folder (dist/share).

Prerequisite dependencies

In order to build the software, one must install several dependencies. This should be done using the provided installation scripts which will automatically set up your environment. You will find these scripts in the scripts folder of the repository.

Windows

In order to build OpenViBE on Windows you have to have either Microsoft Visual Studio 2010 or Microsoft Visual Studio 2008 installed. If you do not, please install the MS Visual Studio Express 2010 which can be downloaded for free.

Once you have the compiler installed run the win32-install_dependencies.exe located in the scripts folder.


By default, this script will install dependencies compatible with Visual Studio 2010. If you use the 2008 version be sure to change the settings as shown on this screenshot.




Linux

On Linux, all of the dependencies will be installed by running (while inside the scripts directory) the provided linux-install_dependencies.  This script will ask you for your password in order to use the native package manager for most of the dependencies.

Some of the dependencies will be compiled from sources, this may take some time. All compiled dependencies are installed to the scripts/software folder, thus they do not clash with your own installed software.

Visit our FAQ to see the list of dependencies on Linux.

Building the software

In order to build OpenViBE platform run (in scripts directory) linux-build or win32-build script, depending on your platform.

Once the build is done, all generated files are stored in the dist folder. The build also generates several launch scripts for you:

  • On Windows each of the ov-[application-name].cmd scripts in the dist folder will launch the desired application.
  • On Linux ov-[application-name].sh will launch the application you want. The linux-test script will launch all OpenViBE applications.

If you made it this far, congratulations : you should now have OpenViBE working!

Tuning the build process

In openvibe 0.16.0 the build process was modified in order to use CMake for building, exclusively. This modification changed the way the build process is controlled. If you are using openvibe from before this change (The new version has CMakeLists.txt file in the project root.) please refer to the page describing the process before the switch: Tuning the build process – pre 0.16.0.

If you want to customize the build process, modify the CMakeLists.txt file in the project root.

  • Default behaviour: The script will build all the modules, except the documentation (that you find on the website anyway). After a fresh checkout, please build the software like this once.
  • To build a branch instead of module’s trunk, create a CMake variable starting with OV_BRANCH and then following the path to the project replacing / by _. For your convenience all of the default projects’ paths have been created and commented out in the CMakeLists.txt file already. As an example, if you want to build your branch called wip-myname-mybranch in the openvibe-plugins/signal-processing project you will have to enter this like to the CMakeLists.txt file: 
    SET(OV_BRANCH_PLUGINS_SIGNAL-PROCESSING "branches/wip-myname-mybranch")
  • If you want to skip building of a project just set the branch name to __SKIPME 
    SET(OV_BRANCH_PLUGINS_SIGNAL-PROCESSING "__SKIPME")

This process is platform-agnostic.

Troubleshooting

When developing new plugins, updating the software manually, or using an unsupported architecture; the build process can fail.

Here is the first thing to try when having build failure:

  • Dependencies : are they successfully downloaded? are they built correctly if required (look in scripts/software/log folder)?
  • Delete the folder scripts/software on Linux or dependencies on Windows to force a complete reinstallation of the dependencies.
  • CMake cache : the folder local-tmp contains all the temporary cache file of CMake, maybe outdated. Delete local-tmp to force a complete build by CMake.
  • Delete the folder dist if you want to be sure that nothing from the previous build remains
This entry was posted in Source code handling. Bookmark the permalink.