Install

• NB: Document based on OpenViBE 0.8.0 (31-sept-2010).

Source code acess

The source code of the project can be found on the INRIA gForge : (https://gforge.inria.fr/projects/openvibe)

Getting the latest (unstable) version of the source code from the forge can be done thanks to the following commands :

• Registered developer (with read/write rights):

  svn checkout svn+ssh://developername@scm.gforge.inria.fr/svn/openvibe/trunk
  

• Anonymous (with only 'read' rights):

  svn checkout svn://scm.gforge.inria.fr/svn/openvibe/trunk
  

If you want to use the source code from a specific tag, you can use the following command, where version is the tag version (0.1.0, 0.2.0, etc.)

svn checkout svn://scm.gforge.inria.fr/svn/openvibe/trunk/tags/version

Windows users will prefer a GUI for subversion (SVN). We recommand TortoiseSVN which can be downloaded from http://tortoisesvn.tigris.org

Please avoid any special caracters such as &, |, !, ?, spaces etc in the path where you download and build the sources. This would break some of the build scripts (especially with Windows).

• Good example : C:\work\openvibe\repository
• Bad example (blanks) : C:\my working directory\openvibe

Repository organisation

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 unstable version)
 + <tags> (tagged versions)
    + 0.0.1
    + ...
 + <branches> (work in progress, probably very unstable)
    + wip-developer1
    + 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 successfull build, all the share folders of the compiled modules are copied in the build result.

Build target

OpenViBE should compile on x86 and x86_64 architectures running Microsoft Windows 2k/XP/Vista/7 with Visual C++ 2008 and 2010.

OpenViBE should compile on x86 and x86_64 architectures running Linux with gcc.

See What kind of computer / operating system do I need to run OpenViBE ? in for a detailed table of what target has been tested.

Please consider that trying to compile OpenViBE on other hardware/OS/compiler is experimental and has not been tested. If you wish to try and get OpenViBE to run on other hardware/OS/compilers, your efforts are welcome but you should not expect to get support on the short term.

Prerequesite dependencies

In order to build the software, one must install several dependencies. This may 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.

• win32-install_dependencies.exe installs dependencies under Windows.
• linux-install_dependencies installs them under Linux.

The Windows installer processes prebuilt packages and therefore is quite fast. If you are using this installer, please check what compiler you will be using. You can choose during the installation which version you need : Visual Studio 2008 or Visual Studio 2010. Please use VS2010 if it is available on your computer, as the build process checks for the most recent compiler. A mismatch between dependencies and build won't please the linker.

The Linux installer processes some prebuilt packages using the native disto tools (e.g. apt-get or yum). It also processes some some source packages for some of the dependencies that vary too much from a distro to another. Therefore, the Linux dependencies installation can be a little longer than on Windows.

Building the platform

Please avoid any special caracters such as &, |, !, ?, spaces etc in the path where you download and build the sources. This would break some of the build scripts (especially with Windows).

Before tuning the build script, we strongly advise you to build once all the software as it is delivered in the sources repository, only with the trunk modules.

If you want to build all projects at once, you can use the linux-build or win32-build scripts provided. Both scripts call the appropriate init_env_command, which by default build everything you need.

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

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

The applications available can be divided in two sets. The user applications are:

• Designer : the main application to design your BCI scenarios
• Acquisition Server : to acquire EEG signal from a device
• Tie-Fighter demo : the Ogre VR demonstrator to be used with the tie-fighter scenario.
• handball demo : the Ogre VR demonstrator to be used with the handball scenario.

The developer applications are:

• Skeleton-generator : generates skeletons to develop new drivers and boxes.
• Plugin-inspector : creates documentation skeleton for new boxes.
• id-generator : a simple tool to generate random identifiers to be used in the OpenViBE code.

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

Tuning the build process

If you want to customize the build process, modify the int_env_command script. In case you have trouble using your modified script, the skeletons may represent useful backups. Here is some tips for common developer needs :

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

• Build a branch instead of module's trunk: Modify the init_env_command script by specifying the branch path. For example, if you want to try a specific - unstable - driver located in a branch on Windows:

  SET OpenViBE_application_acquisition_server_branch=
  

  will become :

  SET OpenViBE_application_acquisition_server_branch=branches/wip-unstable-driver
  

  if you want to try a specific - unstable - driver located in a branch on Linux:

  OpenViBE_application_acquisition_server_branch=
  

  will become :

  OpenViBE_application_acquisition_server_branch=branches/wip-unstable-driver
  

• Build only few modules (will work only if all modules have been compiled at least once): Modify the init_env_command script by choosing the project to be added in the build order. For example if you accept to rebuild the signal processing plugin on Windows:

  echo %OpenViBE_plugin_signal_processing% >> %OpenViBE_build_order%
  

  If you want to avoid building the signal processing plugin on Windows, just remove the line or comment it like this:

  REM echo %OpenViBE_plugin_signal_processing% >> %OpenViBE_build_order%
  

  Similarly, if you accept to rebuild the signal processing plugin on Linux:

  $OpenViBE_plugin_signal_processing
  

  If you want to avoid building the signal processing plugin on Linux, just remove the line or comment it like this:

  #$OpenViBE_plugin_signal_processing
  

Contribute

If you want to contribute to the OpenViBE open-source project, you are warmly welcomed ! Here are the most useful links :

• This dedicated webpage explains on which part of the project you can contribute and how the integration process is organised.
• The Contribution Rules are coding rules you must follow if you want your work to be integrated in the main trunk.
• The Developer Documentation contains various tutorials and code examples.
• The forum to ask your questions to experienced developers

Welcome on board and thank you for using OpenViBE !