Build Instructions

  • NB: Document last updated for OpenViBE 1.3.0 (last edit 03.Jan.2017).

Introduction

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

Then you need the OpenViBE source packages or a repository clone. These can be obtained via the downloads page.

Important: When extracting the source archive, the directory path must NOT contain any spaces or special characters such as &, |, (, ) etc.

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

On Windows, we recommend to keep the path as short as possible or you may run into compiling problems.

Building on Windows

Required third-party tools and components

To build OpenViBE on Windows you need the following installed,

  • Microsoft Visual Studio 2013 (or Microsoft Visual Studio 2010)
  • The latest service pack for that Visual Studio

Other versions of these compilers will not work easily. If you do not have either version, please install the MS Visual Studio Express 2013 which can be used for free. The community edition might work as well. Other compilers are not supported on Windows and porting OpenViBE to them may require significant amount of work, including recompiling all the third-party dependencies. Unless you have the time, the skill and the motivation, do not try that route.

The compilation also requires additional software components that we call dependencies. After installing Visual Studio, use a provided installation executable to download the dependencies:

  • Run win32-install_dependencies.exe located in the scripts folder of the source tree.

If the dependency installer repeatedly fails downloading something, this could be due to your net connection being too fast and the web host interpreting it as a DOS attack attempt. If you encounter this problem, please let us know.

The dependency installer will additionally generate a win32-dependencies.cmd file that sets up the paths to the downloaded dependencies (this script is called automatically by the build scripts).


By default, the installer will download dependencies compatible with Visual Studio 2013. If you use the 2010 version of the compiler, be sure to change the settings in a analoguous fashion as shown on this old screenshot.




After the dependencies have been installed, OpenViBE is ready to be compiled.

Windows compilation

On Windows, there are two alternative ways to build OpenViBE. Both are started from the scripts folder.

  • Faster and recommended way is to use Visual Studio IDE: To do an IDE build, launch win32-generate-vc-proj.cmd to create a Visual Studio .sln file, then followed by win32-launch-vc.cmd. You may have to tinker these scripts and win32-init_env_command.cmd to locate and use the correct Visual Studio executable. After the Visual Studio IDE has opened the solution, OpenViBE can be compiled by building the project INSTALL.
  • Classic way to build is the command-line build: run the win32-build.cmd script.

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

  • openvibe-[application-name].cmd script in the dist folder will launch the desired application.

Building on Linux

Required third-party components

On Linux, some additional third-party dependencies are required to build the software. These dependencies will be installed by running the provided linux-install_dependencies script while inside the scripts/ directory. This script will ask for root access (password) in order to use the native package manager to install such dependencies as are included in your Linux distribution.

As 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.

After the dependency installation, OpenViBE is ready to be built.

Linux compilation

  • Run linux-build script inside the scripts directory.

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

  • openvibe-[application-name].sh will launch the application you want.

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

All platforms: Tuning the build process

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 will 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 of skipping the module plugins/processing/classification:
    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. Normally the compilation should pass on all supported operating systems.

When building OpenViBE, you will get notifications that the build failed to find certain optional components, usually related to drivers. This is normal. In this case, the corresponding driver cannot be built. Some drivers require proprietary libraries from the corresponding hardware manufacturers. We cannot distribute such libraries. You can try to contact the company in question if you need to compile in support for such a driver.

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 (re-run dependency installer after).
  • 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 full rebuild by CMake.
  • Delete the folder dist if you want to be sure that no installed build results from the previous build remain

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)

Typically share and include directory contents are copied to the build target folder (dist/share/openvibe).

This entry was posted in Source code handling. Bookmark the permalink.