Migrating your code from 0.15.0 to 0.16.0

The last release has introduced several changes to the build system and the folder structure.

This tutorial will walk you through of migrating your existing code to the new version depending of the type of extension you were working on.

Technicalities

First please take note of some important changes in the organization.

License

OpenViBE is now subject to the AGPLv3 license in its entirety. Previous code from LGPLv2+ and GPLv2+ was migrated to AGPLv3 as well.

Code repository

OpenViBE SVN trunk address changed for 0.16.0 (and later the repository changed to Git). If you’re using the repository, see here for the details. Please checkout/clone the new OpenViBE to a fresh directory and make any migration manually following these instructions.

Externals

If you have been using openvibe-externals/ for your codebase you can still do it (it is now called simply externals/). Its structure is identical to the contrib/ folder described later.

Contribution and licensing perimeters

There are two spaces inside openvibe code. The core and the contributions. By definition core is everything which is not a contribution. Contribution is anything inside the contrib/ folder. This change was made to clarify question about code ownership.

Contributions inside the contribution perimeter do not need to follow any special rules compared to the previously applied rules, but it would be preferable for them to follow the usual OpenViBE coding conventions as well.

Contributions to the core perimeter require you to sign and send to Inria a rights transfer document. You can find more about this on the contribution rules page.

Folder structure

We have created a new folder structure to address several technical issues that have accumulated over time. The new folder structure should be more understandable for developers new to OpenViBE. The most notable improvement is that the build process now never writes into the source tree (i.e. its an out-of-source build now). Here is a diagram showing you which folder moved where.

folder-structure-diagram Click to enlarge

 

There are several notable changes:

  • All of the public interface headers have moved to appropriate include/ folders in the source code.
  • The documentation sources are now directly in doc/ rather than in src/doc/.
  • Plugins have been re-classified as either processing plugins, server-drivers or server-extensions.
  • A new common/ folder was added to include headers that are shared among independent parts of the code (namely modules and kernel). This also eliminates the project-specific platform definitions through #defines (you can still do project-specific changes on the CMakeLists.txt level).
  • Folders branches, tags, and trunc no longer exist in the source tree.

Migration

The migration process of any existing code should be quite easy. In bullets, these are the things you should take care of:

  • Some folder names have changed, openvibe- prefixes have been removed and you should take this into account when #including openvibe headers.
  • The build system now uses pure CMake. It is thus necessary to make some adjustments of your CMake files.
  • We have a new class to identify installation folders (described below). You should update all places where you have been previously looking up a file inside the openvibe distribution (the share/ folder for example) using hardcoded strings.
  • There is a new convention for naming the files. The -dynamic suffix was removed.

Directories

There is a new mechanism for finding directories in the OpenViBE distribution. You can use OpenViBE::Directories class to find out where are the parts of OpenViBE installed. This replaces the usage of hardcoded path prefixes and alleviates the making of standard-conforming Linux binary packages.

You should only use these functions in situations where the ConfigurationManager is not present.

Paths

Several include paths have changed:

openvibe-toolkit has been renamed to toolkit

Change #include <openvibe-toolkit/...> to #include <toolkit/...>

The ovasIDriver.h is now in the include path

Change #include <../ovasIDriver.h> to #include <ovasIDriver.h>

share/ folder is not necessarily located at the same level as bin/

Replace all paths beginning with strings such as "../share.", "../bin" by the appropriate generic mechanism:

  • If config manager is available use ${Path_Data} and similar configuration tokens.
  • In absence of config manager use the member functions of the OpenViBE::Directories class

Defines

Macros such as OVP_OS_Windows or OVA_OS_Windows have given place to more generic and global TARGET_OS_Windows.

Examples

Several separate articles illustrate the migration of parts of software into the new system. All of the steps are quite straightforward and should not take more than a few minutes.

Migrating a plugin

If you have developed your plugin as a part of other plugins then you only have to move it to the new location inside plugins/processing/ and modify the appropriate plugin main files.

If you have developed a set of plugins then please follow the process on the page How to migrate a plugin from 0.15.0 to 0.16.0 which illustrates the migration of the Stimulation plugins.

Migrating an application

In order to migrate an application you will have to do several changes, I will illustrate them now on the external stimulation example application already available in OpenViBE. Look at the How to migrate an application from 0.15.0 to 0.16.0 knowledge base article.

Migrating a driver

Drivers made by third parties should go into the contrib/plugins/server-drivers/ folder. There are several files to modify in order to include such driver into the distribution.

An illustration on the example of the gtec-gusbam driver can be found in the article How to migrate a driver from 0.15.0 to 0.16.0.

This entry was posted in Development and tagged , , , . Bookmark the permalink.