Build Instructions

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

Prerequisite dependencies

Building OpenViBE requires additional software components. These dependencies can be pulled by the provided installation scripts which will also automatically set up your environment. You will find these scripts in the scripts folder of the repository.

Windows

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, the dependencies will be installed by running the provided linux-install_dependencies script while inside the scripts directory. This script will ask you for your password in order to use the native package manager to install such dependencies as are included in your Linux distribution.

Some of the dependencies will be compiled from sources, this may take some time. All compiled dependencies are installed to the dependencies 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

After you have installed the required dependencies, there are a few ways to build OpenViBE.

To do a command-line build, run linux-build or win32-build script (depending on your platform) inside the scripts directory.
Visual Studio IDE: To do an IDE build, launch win32-generate-vc-proj followed by win32-launch-vc. You may have to tinker the latter script to use the correct VS devenv executable. On Visual Studio IDE, OpenViBE is compiled by building the project INSTALL.

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: openvibe-[application-name].cmd script in the dist folder will launch the desired application.
On Linux: openvibe-[application-name].sh will launch the application you want.

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 are looking for instructions for earlier OpenViBE versions (0.16.0 and later have CMakeLists.txt file in the project root.) please refer to the page describing the build 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.
If you want to skip building of a component and its subcomponents, set a variable with prefix SKIP_ and the postfix made from the path of the component. Example:
```
SET(SKIP_PLUGINS_PROCESSING_CLASSIFICATION "1")
```

The build attempts to be platform-agnostic where possible.

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 dependencies/log folder)?
Delete the folder dependencies to force a complete reinstallation of the dependencies.
CMake cache : the folder local-tmp contains all the build artifacts, which may be outdated without CMake always realizing this. 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

Source code organization

In order to troubleshoot the build process it may be useful to understand the underlying structure of the code. The project repository is composed of several software modules. The repository basically looks like this :

root of the repository
+ <applications> (OpenViBE user applications)
   + <platform>
      + <acquisition-server>
      + <designer>
   + ... 
+ <contrib> (contributions from third parties)
+ <kernel> (kernel implementation)
+ <modules> (abstraction and portability components)
   + <ebml>
   + <socket>
   + ...
+ <openvibe> (API / specifications)
+ <plugins> (OpenViBE plugin collections)
   + <processing>
      + <samples>
      + <acquisition>
      + ...
   + <server-drivers>
   + ...
+ <toolkit> (development help components)
+ ...

Each software module has its own subtree which resembles an UNIX-like tree :

root of the module
+ <bin> (any pre-compiled binaries of the module)
+ <doc> (documentation)
+ <include> (public API headers of the module)
+ <share> (shared file folder for all data)
+ <src> (source code and private headers of 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. Typically share and include contents are copied to the build target folder (dist/share/openvibe).