OpenViBE Documentation

Install

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 this command :

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

Windows users will prefer a GUI for subversion. 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).

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
 + <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)

Build target

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

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. win32-install_dependencies installs dependencies under Windows and linux-install_dependencies installs them under Linux.

The Windows installer processes prebuilt packages and therefore is quite fast.

The Linux installer processes source packages and builds them from scratch, assuming almost no pre-requisite dependencies. One should be able to install each dependency in a local directory without requiring root access and without using any package manager such as apt-get or yum. The build process takes quite a long time, typically 2 to 3 hours on recent computers.

Preparing environment

The build process uses many environment variables. The 'script' directory contains the necessary files to build the whole platform and plugins. However, the script initializing the environment variables is missing because it must be tuned according to each local installation and usage. However, the linux-init_env_command-skeleton and win32-init_env_command-skeleton files may be used as a basis to create such scripts. Most Linux users will simply want to copy the linux-init_env_command-skeleton to linux-init_env_command. Similarly, most Windows users will simply want to copy win32-init_env_command.cmd-skeleton to win32-init_env_command.cmd.

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

If you want to build all projects at once, you can use the linux-build or win32-build scripts. Both scripts call the appropriate init_env_command, which must have been properly configured.

For Linux, the linux-test script will launch the most interesting softwares for you.

For Windows, each of the test-* scripts in the dist folder will launch the desired applciation.

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

Contribution rules

Developers wishing to contribute to OpenViBE should be aware that several coding rules have been fixed to ensure homogeneous source code. These rules are as follows :

  • namings :
    • English is used for all names (class, function, variable...)
    • Abreviations are not tolerated anywhere in the code. All names must be as explicit as possible (makes it a bit longer to write code when automatic completion is not available, but in turn it is much easier to read for people who did not write this code!)
    • class names start with C
    • template names start with T
    • interface names start with I (as with pure abstract classes of an API)
    • members start with m_
    • local variables start with l_
    • global variables are prohibited (please contact the dev coordinator if this is necessary in your case)
    • function parameter names do not have a specific prefix
    • variable names are prefixed with their type : b for boolean, s for string, r for references, o for objects, i16 for signed 16 bits integers, uint64 for unsigned 64 bits integers or float80 for 80 bits floats...
    • function names do not have a prefix, start with a lowercase character and use upper case characters for each new word
    • curly brackets always stand alone on new lines
    • if / else blocks always have curly brackets, even if only one call is to be done
  • English is used in all code documentation
  • Code documentation is done with doxygen (http://www.stack.nl/~dimitri/doxygen/)
  • Implementation is documented for complex things with or without doxygen
  • non portable libraries (should it be software or hardware compatibility) are isolated in separate modules (such as EBML, XML, FS etc...)
  • every class is constituted by a pair of files : header (definition) and source (implementation)
  • redundant includes should be avoided thanks to ifndef define endif directives at the begining and end of header files
  • API header files should be stored in a folder named after the module name
  • At least one namespace should be used per module so to avoid symbol name collisions
  • 'using namespace' directives must not be used in header files
  • generalized use of basic types provided by modules (float32, uint32 and so on) is strongly encouraged so that type sizes are explicit throughout the code and thus at any time, a developer knows what can be done with the values being manipulated.

This is a sample of OpenViBE-compliant code illustrating these rules :

/**
  * \file SampleFile.h
  * \author me
  * \date today
  * \erief a sample file containing TSample template
  *
  * This sample file contains the definition of the
  * TSample template blah blah more details...
  */
namespace SampleNamespace
{
        /**
         * \class Tsample
         * \author me
         * \date today
         * \erief short-blah
         *
         * Detailed blah blah
         */
        template <class T>
        class TSample : public T
        {
        public:
                /**
                 * \function sampleFunction
                 * \param rInputValue[in] : blah
                 * \param rOutputValue[out] : blah
                 * \return blah blah
                 * \erief short-blah
                 *
                 * Detailed blah blah
                 */
                virtual SampleNamespace::boolean sampleFunction(
                        SampleNamespace::boolean bInputValue,
                        SampleNamespace::boolean& rOutputValue)
                {
                        SampleNamespace::boolean l_bCondition=true;
                        if(l_bCondition)
                        {
                                rOutputValue=bInputValue;
                                return true;
                        }
                        return false;
                }
        };
};

Contribution HOWTO

Contributions integration is done at several different levels.

  • First, core developers have full access to the forge. This means they can modify any file, including trunc branches (unstable version of the software) and tags.
  • A second level includes restricted write access to the forge. People working in this configuration work in their own branches. It is up to core developers to decide whether or not a branch is ready for integration to the mainstream version.
  • A third and last level concerns people with read-only access to the forge. Such users may produce patches and develop custom functionalities locally, which only developers with write access will be able to integrate to the forge. Creating such patches may be done easily by dumping the output of a svn diff.