Build Instructions

NB: Document last updated for OpenViBE 3.4.0.
Older versions:

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 whitespace, &, |, (, ) 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.

Here what you should find in the root folder:

.
├── build.cmd
├── build.sh
├── CMakeLists.txt
├── designer (Designer based on SDK folder)
├── extras (Extras functionalities based on SDK folder)
├── install_dependencies.cmd
├── README.md
└── sdk (OpenViBE SDK folder)
└── ...

Building on Windows

Required third-party tools and components

OpenViBE requires Microsoft Visual Studio for its compilation.

Here is the list of compatible versions:

From OpenViBE 3.4.0:
- Microsoft Visual Studio 2019 Community
- Microsoft Visual Studio 2017 Community
- Microsoft Visual Studio 2013 Express with Update 5
Prior to OpenViBE 3.4.0 :
- Microsoft Visual Studio 2013 Express with Update 5

Other versions or compilers will not work for OpenViBE prior to 3.4.0. If you do not have a VS 2013 professional, please install the MS Visual Studio Express 2013 which can be used for free (the next best).
For OpenViBE 3.4.0 and after, you can try to compile with newer versions of MSVC but you may encounter issues requiring code update or worse, the need to recompile some dependencies. Unless you don’t have other options, we therefore recommend using one of the versions listed above.

The compilation requires additional software components called dependencies. After installing Visual Studio, use the provided installation script to download and compile the dependencies:

Launch install_dependencies.cmd located in the root folder of the source tree.

It will create dependencies folder and will download and copy all dependencies required by the three projects (SDK, Designer and OpenViBE extras) folders.

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

Windows compilation

The easiest way to compile on Windows is to launch build.cmd located in the root folder of the source tree. This makes a command line build without using an IDE.

build.cmd will build a release build. The binaries will be in dist/x64/Release/.
build.cmd --debug will build a debug build. The binaries will be in dist/x64/Debug/.

Alternatively, to get an IDE build with the usual VS develop/launch/debug experience,

Generate Visual Studio .sln for both Debug and Release builds by running build.cmd with --vsbuild option.
Then, open build-vs/x64/OpenViBE.sln in VS. Note that if you make modifications to code belonging to one of sdk/designer/extras, you may need to build that specific subproject manually. By building the INSTALL target of extras, OpenViBE will be installed to dist/Extras/.

The build generates several launch scripts for you:

openvibe-[application-name].cmd script will launch the desired application.

Windows 32bit compilation

Since OpenViBE 3.0.0, the 32bit build on Windows is not the default option. If you wish to build the 32bit version, the following command flags are needed,

> install_dependencies.cmd --platform-target x86> build.cmd --platform-target x86

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 install_dependencies.sh located in the root folder of the source tree.

This script will ask for root access (password) in order to use the native package manager to install such dependencies that are provided by your Linux distribution.

As some of the dependencies will be compiled from sources, this may take some time. All compiled dependencies are installed by default 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 build.sh located in the root folder of the source tree to get a release build

The build artifacts will be located under folder build/ and the compiled binaries can be found under dist/Release. The script also supports a parameter --debug.

The build also generates several launch scripts for you:

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

Ready to launch OpenViBE

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

For all platforms, OpenViBE will be installed under the folder dist/.

All platforms: Tuning the build process

Underneath the build scripts, the build generator CMake is used. Tuning the build process can be done in the CMakeLists.txt file in the root directory and in each project root folder.

In SDK project, skipping components compilation, except plugins components, is not recommended as OpenViBE software is based on modules and kernel provided by SDK.
In Designer project, skipping components compilation, except plugins components, is not recommended.
In Extras project, the script will build all components (acquisition server, plugins,demos application,contributions applications and plugins) by default, 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 sub-components, 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 (some building logs are available on linux platform: look in dependencies/log folder)?
Delete the folder dependencies to force a complete re-installation of the dependencies (re-run dependency installer after).
CMake cache : the folder ./build/${project} contains all the build artifacts, which may be outdated without CMake always realizing this. Delete its content 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

OpenViBE project is now divided into three parts organized in sub-modules in the OpenViBE-meta repository:

SDK, that contains the certifiable core and plugins of OpenViBE.
Designer, the graphical interface for OpenViBE
Extras, for acquisition server, community plugins and contributions

You can find information about how to contribute and the rules to follow here.

In order to troubleshoot the build process it may be useful to understand the underlying structure of the code.

openvibe-meta

.
├── dependencies
│   ├── arch
│   ├── boost
│   ├── cegui
│   ├── cmake
│   ├── ...  
├── designer
│   ├── applications
│   ├── cmake-modules
│   ├── dependencies-source
│   ├── libraries
│   ├── plugins
│   ├── scripts
│   └── visualization-toolkit
├── extras
│   ├── applications
│   ├── build-tool
│   ├── cmake-modules
│   ├── contrib
│   ├── debian
│   ├── documentation
│   ├── externals
│   ├── modules
│   ├── plugins
│   ├── scripts
│   └── test
└── sdk
    ├── applications
    ├── build-tool
    ├── cmake-modules
    ├── common
    ├── dependencies
    ├── dependencies-source
    ├── documentation
    ├── externals
    ├── kernel
    ├── modules
    ├── openvibe
    ├── plugins
    ├── scripts
    ├── toolkit
    ├── unit-test
    └── validation-test

OpenViBE SDK

.
├── applications
│   └── developer-tools
│       ├── id-generator
│       └── scenario-player
├── build-tool
├── cmake-modules
├── common
├── dependencies
│   ├── arch
│   ├── eigen-build  
│   ├── gtest-build
│   ├── libgtest
│   └── test-input
├── dependencies-source
│   ├── dsp-filters
│   ├── lepton
│   └── r8brain
├── documentation
├── externals
├── kernel
├── modules
│   ├── csv
│   ├── date
│   ├── ebml
│   ├── fs
│   ├── socket
│   ├── system
│   └── xml
├── openvibe
├── plugins
│   └── processing
│       ├── classification
│       ├── data-generation
│       ├── feature-extraction
│       ├── file-io
│       ├── signal-processing
│       ├── stimulation
│       ├── stream-codecs
│       ├── streaming
│       └── tools
├── scripts
├── toolkit
├── unit-test
└── validation-test

Designer

.
├── applications
│   └── platform
│       └── designer
├── cmake-modules
│   └── launchers
├── dependencies-source
│   └── json
├── libraries
│   └── lib-advanced-visualization
│       ├── include
│       └── src
├── plugins
│   ├── examples
│   │   ├── box-tutorials
│   │   ├── doc
│   │   └── src
│   └── visualization
│       ├── ovp-advanced-visualization
│       └── simple-visualization
├── scripts
│   └── icons
└── visualization-toolkit
    ├── include
    │   └── visualization-toolkit
    └── src

OpenViBE extras

.
├── applications
│   ├── demos
│   │   ├── erp-recording
│   │   ├── motor-imagery
│   │   ├── neurofeedback
│   │   ├── p300
│   │   ├── ssvep-demo
│   │   ├── ssvep-mind-shooter
│   │   └── vr-demo
│   ├── developer-tools
│   │   ├── plugin-inspector
│   │   ├── skeleton-generator
│   │   └── vrpn-simulator
│   ├── examples
│   │   ├── convert
│   │   ├── external-stimulation-connection
│   │   ├── openvibe-to-tcpip
│   │   ├── openvibe-to-vrpn
│   │   └── vrpn-to-openvibe
│   └── platform
│       └── acquisition-server
├── build-tool
│   └── stimulation-generator
├── cmake-modules
│   └── launchers
├── contrib
│   ├── applications
│   ├── cmake-modules
│   ├── common
│   ├── packages
│   └── plugins
├── debian
│   └── source
├── documentation
│   ├── doc
│   └── src
├── externals
├── modules
│   └── tcptagging
├── plugins
│   ├── processing
│   ├── server-drivers
│   └── server-extensions
├── scripts
└── test

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