Build Instructions

  • NB: Document last updated for OpenViBE 2.0.0 (last edit 22.Nov.2017). OpenViBE 1.3.0 compliant version

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
├── designer (Designer based on SDK folder)
├── extras (OpenViBE base on SDK folder)
├── install_dependencies.cmd
├── launchvc.cmd
├── launchvc_debug.cmd
├── README.md
└── sdk (OpenViBE SDK folder)

Building on Windows

Required third-party tools and components

To build OpenViBE on Windows you need the following installed,

  • Microsoft Visual Studio 2013 (as C++11 is now used, MS Visual Studio 2010 is not supported any more).
  • It’s latest service pack (if exists)

Other versions of VS will not work easily. If you do not have a commercial VS 2013, please install the MS Visual Studio Express 2013 which can be used for free (the next best). The community edition might work as well but some issues have been reported. 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 called dependencies. After installing Visual Studio, use a provided installation executable to download 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. The installer will download dependencies compatible with Visual Studio 2013

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/extras-Release/.
  • build.cmd --debug will build a debug build. The binaries will be in dist/extras-Debug/.

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

  • Merge the three projects (SDK, Designer, Extras) into one monolithic VS solution. The build script does this automatically but to do so, it requires python3 and jinja2. If you use stock python3, you can install jinja2 like this: c:\python3X\Scripts\pip.exe install jinja2
  • Generate Visual Studio .sln for both Debug and Release builds by running build --vsbuild-all option. Then, open build/openvibe-meta.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/.

If you do not wish to install python, you can also use the launchvc.cmd or launchvc_debug.cmd scripts (Legacy).

In all cases the intermediate build artifacts will be under build/ in separate folders. The directories correspond to the three subprojects. The command line builds can be differentiated from the IDE builds by the dash (-) in the folder name.

The build 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 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 (except eigen library which is especially compiled and part of /usr/local/ for Ubuntu 16.04 compatibility) 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/. The script also supports a parameter --debug and then the result directories will have a Debug postfix.

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

If you want to customize the build process, modify the CMakeLists.txt file of 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).

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