Migrating a plugin from version 0.15.0 to 0.16.0

This tutorial illustrates the migration of a processing plugin (box or algorithm) from the 0.15 codebase to the 0.16. For a larger overview of changes in 0.16.0 please look at our Migration guide.

Through the tutorial an OLD prefix indicates the 0.15.0 file structure, the NEW prefix is for 0.16.0.

Contributions that are not intended to be included in the core distribution should reside inside the /NEW/contrib/plugins folder instead of /NEW/plugins. Both of these folders follow the same rules and CMake files are analogous. The only visible change is the project name which should bear the contrib- prefix.

We are going to illustrate a migration to the /NEW/plugins folder on the example of the Stimulation plugin.

Copying the files

In the old version plugin source was stored in OLD/openvibe-plugins/stimulation/trunc

Here is the listing of all of the files

./bin:

./doc:

./etc:

./include:

./lib:

./share:
openvibe-plugins

./share/openvibe-plugins:
stimulation

./share/openvibe-plugins/stimulation:
graz_keyboard_to_stimulations.txt
graz_stimulation_scenario.xml
keyboard-stimulator.ui
lua-stimulator-legacy.lua
lua-stimulator-stim-codes.lua
ov_beep.wav
sample-lua-script.lua
simple-keyboard-to-stimulations.txt

./src:
box-algorithms
doc
ovpCBoxAlgorithmP300IdentifierStimulator.cpp
ovpCBoxAlgorithmP300IdentifierStimulator.h
ovpCBoxAlgorithmP300SpellerStimulator.cpp
ovpCBoxAlgorithmP300SpellerStimulator.h
ovpCKeyboardStimulator.cpp
ovpCKeyboardStimulator.h
ovpCSignChangeDetector.cpp
ovpCSignChangeDetector.h
ovpCXMLStimulationScenarioPlayer.cpp
ovpCXMLStimulationScenarioPlayer.h
ovp_defines.h
ovp_main.cpp

./src/box-algorithms:
stimulation

./src/box-algorithms/stimulation: 
adaptation 
ovpCBoxAlgorithmLuaStimulator.cpp 
ovpCBoxAlgorithmLuaStimulator.h 
ovpCBoxAlgorithmOpenALSoundPlayer.cpp 
ovpCBoxAlgorithmOpenALSoundPlayer.h 
ovpCBoxAlgorithmPlayerController.cpp 
ovpCBoxAlgorithmPlayerController.h 
ovpCBoxAlgorithmRunCommand.cpp 
ovpCBoxAlgorithmRunCommand.h 
ovpCBoxAlgorithmSoundPlayer.cpp 
ovpCBoxAlgorithmSoundPlayer.h 
ovpCBoxAlgorithmStimulationMultiplexer.cpp 
ovpCBoxAlgorithmStimulationMultiplexer.h 

./src/box-algorithms/stimulation/adaptation: 
ovpCBoxAlgorithmStimulationFilter.cpp 
ovpCBoxAlgorithmStimulationFilter.h 

./src/doc: 
Doc_BoxAlgorithm_KeyboardStimulator.dox-part 
Doc_BoxAlgorithm_LuaStimulator.dox-part 
Doc_BoxAlgorithm_P300IdentifierStimulator.dox-part 
Doc_BoxAlgorithm_P300SpellerStimulator.dox-part 
Doc_BoxAlgorithm_RunCommand.dox-part 
Doc_BoxAlgorithm_SignChangeDetector.dox-part 
Doc_BoxAlgorithm_SoundPlayerDeprecated.dox-part 
Doc_BoxAlgorithm_SoundPlayer.dox-part 
Doc_BoxAlgorithm_StimulationFilter.dox-part 
Doc_BoxAlgorithm_StimulationMultiplexer.dox-part 
Doc_BoxAlgorithm_XMLStimulationScenarioPlayer.dox-part

./test:

In addition to these files, there are several scenarios and data-files inside /OLD/openvibe-scenarios which are tied to the stimulation plugins.

All of the plugin files have now been centralized inside /NEW/plugins/processing.

Source code

First move the source code to the /NEW/plugins/processing/stimulation/src folder.

The structure has changed a little bit, all code related to box-algorithms should go to box-algorithms/ sub folder. All code concerning algorithms should go to algorithms/. The structure in these folders should be mostly flat.

In the end, in the case of stimulation plugins the code in /src looks like this:

/NEW/plugins/processing/stimulation/src:

ovpdefines.h
ovpmain.cpp

./box-algorithms:
adaptation
ovpCBoxAlgorithmLuaStimulator.cpp
ovpCBoxAlgorithmLuaStimulator.h
ovpCBoxAlgorithmOpenALSoundPlayer.cpp
ovpCBoxAlgorithmOpenALSoundPlayer.h
ovpCBoxAlgorithmP300IdentifierStimulator.cpp
ovpCBoxAlgorithmP300IdentifierStimulator.h
ovpCBoxAlgorithmP300SpellerStimulator.cpp
ovpCBoxAlgorithmP300SpellerStimulator.h
ovpCBoxAlgorithmPlayerController.cpp
ovpCBoxAlgorithmPlayerController.h
ovpCBoxAlgorithmRunCommand.cpp
ovpCBoxAlgorithmRunCommand.h
ovpCBoxAlgorithmSoundPlayer.cpp
ovpCBoxAlgorithmSoundPlayer.h
ovpCBoxAlgorithmStimulationMultiplexer.cpp
ovpCBoxAlgorithmStimulationMultiplexer.h
ovpCKeyboardStimulator.cpp
ovpCKeyboardStimulator.h
ovpCSignChangeDetector.cpp
ovpCSignChangeDetector.h
ovpCXMLStimulationScenarioPlayer.cpp
ovpCXMLStimulationScenarioPlayer.h

./box-algorithms/adaptation:
ovpCBoxAlgorithmStimulationFilter.cpp
ovpCBoxAlgorithmStimulationFilter.h

As for the CMakeLists.txt it goes directly into /NEW/plugins/processing/stimulation

Assets

The share/ folder now holds the assets directly and the destination is now handled by CMake.

Move all files from the /OLD/openvibe-plugins/stimulation/trunc/share/openvibe-plugins/stimulation to /NEW/plugins/processing/stimulation/share

Documentation

The documentation has been moved. Move the /OLD/openvibe-plugins/stimulation/trunc/srd/doc folder to /NEW/plugins/processing/stimulation/doc

Scenarios

If your plugin comes with additional data or scenarios that were previously stored inside /openvibe-scenarios subfolder, you’ll now need to locate them with the plugin in the source tree. All tutorials should be put directly into the plugin folder under the box-tutorials/. Data files should go to a signals/ subfolder.

In this case these are the concerned files are:

/OLD/openvibe-plugins/stimulation/trunc/share/openvibe-plugins/stimulation:
sample-lua-script.lua

/OLD/openvibe-scenarios/trunc/share/openvibe-scenarios/box-tutorials:
lua-stimulator.xml
run-command.xml
sign-change-detector.xml
sound-player.xml

We have decided to structure the things a bit and move all lua related stuff to its own subfolder. However you can organise the tutorials and scenarios in a way that you find the best.

Our current files are:

/NEW/plugins/processing/stimulation/box-tutorials:
run-command.xml
sign-change-detector.xml
sound-player.xml

./lua:
lua-stimulator.xml
scripts

./lua/scripts:
sample-lua-script.lua

That is it for the file movements. Several changes have to be made to the code as well.

Updating files

Several files will now need updating.

CMake file

Project names are now lower case

OLD:    PROJECT(OpenViBE-plugins-stimulation)
NEW:    PROJECT(openvibe-plugins-stimulation)

We have removed the -dynamic postfix to the library and executable names. Check your ADD_LIBRARY, SET_TARGET_PROPERTIES and TARGET_LINK_LIBRARIES functions.

OLD:    ADD_LIBRARY(${PROJECT_NAME}-dynamic SHARED ${source_files})
        SET_TARGET_PROPERTIES(${PROJECT_NAME}-dynamic PROPERTIES
NEW:    ADD_LIBRARY(${PROJECT_NAME} SHARED ${source_files})
        SET_TARGET_PROPERTIES(${PROJECT_NAME} PROPERTIES

Pre-compiler macros are now global

OLD:    COMPILE_FLAGS "-DOVP_Exports -DOVP_Shared")
NEW:    COMPILE_FLAGS "-DOV_Exports -DOV_Shared")

Boost includes have now been factorised. The boost_thread will not bring boost dependency in automatically, you’ll need to add it.

NEW:    INCLUDE("FindThirdPartyBoost")

Target folders are now specified by variables rather than hardcoded, replace all instances of bin, lib, doc, etc, include. Also empty directories in plugins and applications such as bin were removed if they do not contain files. You installs should only install folders which are necessary.

OLD:    INSTALL(TARGETS ${PROJECT_NAME}-dynamic
            RUNTIME DESTINATION bin
            LIBRARY DESTINATION lib
            ARCHIVE DESTINATION lib)
        INSTALL(DIRECTORY bin/   DESTINATION bin     PATTERN ".svn" EXCLUDE)
        INSTALL(DIRECTORY doc/   DESTINATION doc     PATTERN ".svn" EXCLUDE)
        INSTALL(DIRECTORY etc/   DESTINATION etc     PATTERN ".svn" EXCLUDE)
        INSTALL(DIRECTORY lib/   DESTINATION lib     PATTERN ".svn" EXCLUDE)
NEW:    INSTALL(TARGETS ${PROJECT_NAME}
        RUNTIME DESTINATION ${CMAKE_INSTALL_FULL_BINDIR}
        LIBRARY DESTINATION ${CMAKE_INSTALL_FULL_LIBDIR}
        ARCHIVE DESTINATION ${CMAKE_INSTALL_FULL_LIBDIR})

You should now handle the install destinations of share, box-tutorials and other installable folders yourself.

NEW:    INSTALL(DIRECTORY share/ DESTINATION ${CMAKE_INSTALL_FULL_DATADIR}/openvibe/plugins/stimulation PATTERN ".svn" EXCLUDE)
        INSTALL(DIRECTORY box-tutorials DESTINATION ${CMAKE_INSTALL_FULL_DATADIR}/openvibe/scenarios/   PATTERN ".svn" EXCLUDE)

Note: documentation will be installed in another step and you do not need to handle it. All files inside doc/ will be copied to the appropriate documentation folder.

Fixing includes

The ovp_defines.h file is not at the same place as before, some places will need fixing this, such as (the final path is variable):

OLD:    #include "../../../ovp_defines.h"
NEW:    #include "../../ovp_defines.h"

openvibe-toolkit was renamed:

OLD:    #include <openvibe-toolkit/ovtk_all.h>
NEW:    #include <toolkit/ovtk_all.h>

Project specific macros have been replaced by one global name:

OLD:    #if defined OVP_OS_Windows
NEW:    #if defined TARGET_OS_Windows

Use the configuration tokens instead of hardcoded paths.

OLD:    "../share/openvibe-plugins/..."
NEW:    "${Path_Data}/plugins/..."

Remove the project specific definitions from ovp_defines.h header:

OLD:    // Operating System identification (whole section)
OLD:    // Hardware Architecture identification (whole section)
OLD:    // Compilator software identification (whole section)
OLD:    // API Definition (whole section)
OLD:    // NULL Definition

Fix the includes inside ovp_main.cpp file:

OLD:    #include "box-algorithms/stimulation/ovpCBoxAlgorithmPlayerController.h"
NEW:    #include "box-algorithms/ovpCBoxAlgorithmPlayerController.h"

etc…

Script files

There were some specific changes for lua in the release so let’s update the scripts as well.

In order to get the stimulation codes move the dofile(…) into initialize() and use it as this:

dofile(box:get_config("${Path_Data}") .. "/plugins/stimulation/lua-stimulator-stim-codes.lua")

Instead of infinite loops use box:keep_processing() as a condition

OLD:    while true do
NEW:    while box:keep_processing() do

Scenarios

If you are configuring your boxes by files or do any file manipulation in the boxes (trainers, classifiers, file readers) then update the links to the destination folders in these manners:

Link to the share folder via a configuration token:

OLD:    ../share/openvibe-plugins/stimulation/simple-keyboard-to-stimulations.txt
NEW:    ${Path_Data}/plugins/stimulation/simple-keyboard-to-stimulations.txt

If your scenario comes with bundled scripts or configuration files you can refer to these by using the ${_volatileScenarioDir} variable which points to the scenario folder when the scenario is running.

OLD:    ../share/openvibe-plugins/stimulation/sample-lua-script.lua
NEW:    ${__volatile_ScenarioDir}/scripts/sample-lua-script.lua

Done

Your plugin should now work like before.

This entry was posted in Version migration instructions and tagged , , , . Bookmark the permalink.