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.