Using the OpenViBE build scripts in Visual Studio

Hello  !

This article present a new tip for those who are using Visual Studio as their primary development tool for OpenViBE.
If you try to install OpenViBE from the source code on the SVN repository, then you have to use the provided scripts for nearly everything… And Visual Studio will only be a C++ code editor. No “build project” command, no debug/release configurations, etc. I felt this frustrating as I had always used VS in the past as my “all-in-one” developer tool.

A previous article on this blog described how to use the Visual Studio debugger when developing a new plugin or driver.
This time I will focus on using the scripts provided with OpenViBE right inside Visual Studio.

This article is based on Jay Smith blog post here.

What we need:

Let’s list what we may want to integrate in the IDE. First, the build scripts:

1. win32-build.cmd: builds every project of the software platform (applications, plugins, etc.)
2. win32-clean.cmd: cleanup the CMake cache directory, thus when building again everything will be compiled and installed from scratch.

Then some launchers for the main applications:

1. ov-designer.cmd
2. ov-acquisition-server.cmd
3. ov-skeleton-generator.cmd

Add new menu contents :

Open Visual Studio and your openvibe solution, then go in Tools > External Tools. You should have something like this :

Let’s add the win32-build.cmd script. Add a new content and fill it with the following information:

Title:                   Build OpenViBE
Command:                 C:\[path-to-repository]\scripts\win32-build.cmd
Arguments:               [NO ARGUMENT]
Initial directory:       C:\[path-to-repository]\scripts\
Use Output Window:       YES
Prompt for arguments:    NO
Treat output as Unicode: NO

With Use Output Window checked, the build log will be directly printed in the “output” console of Visual Studio. I didn’t find how to redirect the output with the color information, so the log is just printed black on white in Visual Studio. Uncheck this option if you still want the CMD terminal popping up when building the software.

You can do exactly the same for win32-clean.cmd if you’d like to.

For the application launchers, add new content with the following information:

Title:                   ov-designer
Command:                 C:\[path-to-repository]\dist\test-designer.cmd
Arguments:               [NO ARGUMENT]
Initial directory:       C:\[path-to-repository]\dist\
Use Output Window:       NO
Prompt for arguments:    NO
Treat output as Unicode: NO

This time I don’t want to print the output console in Visual Studio.

You can do the same for the acquisition-server and/or the skeleton-generator for example.

Now that you defined all your personal the menu contents, note their indexes in the list of External Tools, starting at 1.
Why that ?! because Visual Studio doesn’t seem to be capable of referencing these new menu contents by their names… instead you will have something like “External Command 4“, “External Command 5“, etc.
Nevermind… :s

Access the new commands:

Now that we defined some new commands, let’s use them. In my case, I want to be able to run the build process in the context menu of the editor (right click in the main edition panel) or with a dedicated button in the toolbar.
Right click somewhere in the toolbar and select Customize. You have 2 panels, one for the toolbars and one for the commands that appears in the toolbars and menus.

In Toolbars you can add a new group named “OpenViBE”. We will add new buttons in it for our new commands.
Go in the Commands tab.

In the Toolbar selection box, search for “OpenViBE”. You should see in the Controls panel… nothing at all. Click on the Add Command… button.
You will find your new menu content in the category Tool, under the name “External Command #”. I hope your remember the indexes 🙂
Add the external commands corresponding to the build script and the launchers, you should see them in the Visual studio toolbar.

In the Context menus selection box, search for Project and Solution Context Menus |Item. This correspond to the context menu that pops up when right-clicking somewhere in the editor main panel.
As I want to be able to launch the build from there, I also add the corresponding external command.

Want more ?

As we already discussed in a previous article how to customize the build process, it is possible to have more than one build script. For example I personaly have 3 of them:

• One in Release, that builds every project.
• 2 others in Debug and Release, that rely on a specific win32-init_env_command script that only select for build the project I’m currently working on (e.g. work-in-progress branches)

Thus I added 3 commands in Visual Studio: “OpenViBE build (wip/release)”, “OpenViBE build (wip/debug)”,“OpenViBE build (all/release)”.

I hope this article will give you some new ideas to improve your development environment, not only for OpenViBE of course 🙂

Cheers !

Debugging in OpenViBE with Visual Studio

Hello openvibe developers !

For those who develop new plugins for openvibe on windows, this article will describe a simple procedure in order to be able to debug inside openvibe using the Visual Studio C++ editor.
This works exactly the same on Visual 2008 and 2010.

Compiling OpenViBE in Debug

Take a look at the build script win32-build.cmd.

Basically, the script loops on every projects (every applications and plugins) and build each one with this nice (who said ugly ?) CMake commandon line 48 :

cmake -DCMAKE_INSTALL_PREFIX="%%s" -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=" /DWIN32 /D_WINDOWS /W3 /Zm1000 /EHsc /GR /wd4355" -Wno-dev -DCMAKE_MODULE_PATH="%saved_directory:\=/%/../cmake-modules;${CMAKE_MODULE_PATH}" !OpenViBE_project_name_full! -G"NMake Makefiles"

Look at this flag :

... -DCMAKE_BUILD_TYPE=Release ...

If you want to compile some part of the software in debug, just replace Release by Debug.
The projects written in the build-order file generated by win32-init_env_command.cmd will be compiled in Debug.
To select only the projects you need, customize your win32-init_env script, as described in this previous article.

It is highly advised to first compile the whole software in Release, then the specific plugins in Debug. With a debug-kernel and/or debug-Designer, it will be insanely (and logically) slow.

Attaching the Visual Studio debugger

First case :
The application crashes. Windows wisely ask you if you want to debug the program. This time (finally…) it will be useful ! Select your opened project and you’re good.
You should have in the call stack the mean to access the failing piece of code.

Second case :
The application runs fine, but you know it will crash at will (e.g. when playing a scenario).
Execute the application, then go back in Visual Studio. You should have in the menu Tools the possibility to attach a process (Ctrl + Alt + P).
In the process list, look for your application (e.g. OpenViBE-Designer-dynamic.exe), and attach it.

Now you can add breakpoints and debug as you usually do when using Visual Studio.

Hope this helps  🙂

Speed up the OpenViBE build on windows

Hello everyone !

This new tips session is focused on helping the openvibe developers to speed up the build process when working on Windows.
When I started extending the platform by developing new plugins, I was always a bit irritated when running the win32-build.cmd script : it took a century even when I modified just one file !
In fact, I felt very  frustrated as the same process usually take less than 30 seconds on Linux (not enough to make me move to Linux though. Sorry 🙂 ).

Let’s take a look at that build scripts…

Win32-build.cmd, a day at the batch

If you have never written any Batch scripts in your life, once you open it you realize it is far from simple.

Hmm… tricky…

The first 20 lines are just a trick, in order to recall win32-build.cmd with some cmd options (/e /v /c ).

if "%1" == "" goto recall_me
goto base

:recall_me

cmd /e /v /c %0 dummy
goto terminate

:base
... build process ...

If no argument is provided, the script recall itself with the options and a dummy argument.
This is not a major point for this article, so I let you check these cmd options in the MS documentation 🙂

Update 12/05/2011 : I recently spent some time investigating batch scripting, and I found a proper way to do that. I replaced this ugly and tricky stuff with the SetLocal command:

SetLocal EnableDelayedExpansion
SetLocal EnableExtensions

Initialize the environment

This is a crucial point !

if not exist "win32-init_env_command.cmd" (
    echo You have to configure your `win32-init_env_command` file.
    echo `win32-init_env_command.cmd-skeleton` is a good file to start with... (I'll copy this file for you^)
    copy "win32-init_env_command.cmd-skeleton" "win32-init_env_command.cmd"
)

call "win32-init_env_command.cmd"

One way or the other, we call the script win32-init_env_command.cmd, in order to prepare the environment to the build process:

• Set the SVN branches that may be used used instead of trunks
• Creates the corresponding path variables
• Calls win32-dependencies.cmd, the files that lists all the dependencies and their locations.
• Finds the compiler (VS2008 or VS 2010, priority to the latest one)
• Completes the PATH variable with the libs & binaries location for the dependencies
• Constructs the build order, i.e. the list of projects scheduled for build

We will detail this file later on, because obviously that’s where many things can be done !

Build baby !  build !

The build itself relies on CMake. We loop on the build-order, and build each project one by one by calling cmake.

cmake -DCMAKE_INSTALL_PREFIX="%%s" -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=" /DWIN32 /D_WINDOWS /W3 /Zm1000 /EHsc /GR /wd4355" -Wno-dev -DCMAKE_MODULE_PATH="%saved_directory:\=/%/../cmake-modules;${CMAKE_MODULE_PATH}" !OpenViBE_project_name_full! -G"NMake Makefiles"

As you can see, the flag DCMAKE_BUILD_TYPE is by default set to Release. You can change it to Debug if you want to generated debugging information with the software.

Then win32-build generates all the scripts that are used to launch the applications, for example:

echo @echo off                                               >  %target_dist%\ov-designer.cmd
echo pushd ..\scripts                                        >> %target_dist%\ov-designer.cmd
echo call win32-init_env_command.cmd                         >> %target_dist%\ov-designer.cmd
echo popd                                                    >> %target_dist%\ov-designer.cmd
echo cd bin                                                  >> %target_dist%\ov-designer.cmd
echo OpenViBE-designer-dynamic.exe %%1 %%2 %%3 %%4 %%5 %%6   >> %target_dist%\ov-designer.cmd
echo pause                                                   >> %target_dist%\ov-designer.cmd

Produces the following script ov-designer.cmd:

@echo off                                               
pushd ..\scripts                                        
call win32-init_env_command.cmd                         
popd                                                    
cd bin                                                  
OpenViBE-designer-dynamic.exe %1 %2 %3 %4 %5 %6   
pause

That prepares the execution environment before calling the executable (giving it the possible arguments %1 to %6).

Finally the generated files are installed in the dist folder.

Customizing the Build process

Now that you saw the build steps, we move on to the interesting part : how we can customize the build and speed it up.
We will focus on the environment initialization, namely the win32-init_env_command.cmd file.

First…

You should always build the whole software once without tweaking anything in the scripts.
Following this advice you should start with a fresh, up-to-date and working openvibe.

Building a SVN branch

This may be useful for those who want to test a work-in-progress functionality before its possible integration in the trunk.

For example : a new driver is being developed for your EEG device, and you want to contribute by giving feedback and bug reports during the development.
The driver is in a branch, let’s say in openvibe-applications\acquisition-server\branches\wip-my-little-eeg.

We will prepare the build environment to choose the branch instead of the trunc.

win32-init_env_command.cmd : line 38

SET OpenViBE_application_acquisition_server_branch=

Will become :

SET OpenViBE_application_acquisition_server_branch=branches\wip-my-little-eeg

And that’s all. CMake will look in the branch instead of the trunk when building the acquisition-server project.

Selecting the projects to be built

When developing new plugins, you need to build it repeatedly. The problem is the time spent by the script… CMake checks every projects for modification, one by one, and on Windows it’s quiet long. I won’t explain why here but the file system on Linux is much faster in that case.

Anyway, you can do something to speed the build up !

At the end of win32-init_env_command.cmd, you will find the construction of the build order, i.e. the ordinated list of all the projects composing the software. The order itself is based on the dependency links between projects. As you can see, every project is present, but you can easily select only the one you need.

There is several ways to customize that part of the script, one is to comment (using REM) all the lines related to the projects you don’t need.
For example, I want to compile only the box I’m working on. Say the box is located in openvibe-plugins\signal-processing.
I comment all the lines except the “signal-processing” one:

del %OpenViBE_build_order% > NULL 2<&1
REM echo %OpenViBE% >> %OpenViBE_build_order%
REM echo %OpenViBE_application_id_generator% >> %OpenViBE_build_order%
REM echo %OpenViBE_module_ebml% >> %OpenViBE_build_order%
...
REM echo %OpenViBE_plugin_samples% >> %OpenViBE_build_order%
echo %OpenViBE_plugin_signal_processing% >> %OpenViBE_build_order%
REM echo %OpenViBE_plugin_signal_processing_gpl% >> %OpenViBE_build_order%
...
REM echo %OpenViBE_documentation% >> %OpenViBE_build_order%
REM echo %OpenViBE_scenarios% >> %OpenViBE_build_order%

When I will run the build, it will only check for modification in the signal-processing project, recompiling it if needed.

Forcing a project to be re-compiled

If you want to force CMake to compile from scratch the whole software, you can use the script win32-clean.cmd.
This script is simple : it destroys every CMake local directories, thus when executing win32-build.cmd, you will build everything again.

If you want to force the recompilation of only one particular project, just erase the corresponding cmake folder, located in local-tmp (e.g. local-tmp\openvibe-plugins\signal-processing)

This may be useful when changing some dependencies of a project (e.g. you want to test an up-to-date or unstable version of an openvibe  dependency). In that case CMake won’t find any change in the source code of the openvibe plugin itself, thus won’t trigger the build. However you do want the build to occur as you need to compile the plugin against your new dependency.

Closing words

When you know where to look, the build scripts for windows can be tweaked without changing much of it.

I hope this article will help the Windows users in the community !

Cheers-

Using Gtk themes on Windows

For those who are not familiar with Gtk, the themes change the whole layout of your Gtk interfaces.

On Linux it’s really easy, as Gtk is widely used and integrated with the various distributions (e.g. Gnome and Xfce are base on Gtk).
You will find Gtk options in some OS “Appearance” menu…

On windows, switching from one theme to another has to be done manually.

When installing OpenViBE dependencies, you can choose to add new Gtk themes directly in openvibe.
Please note that this option is enabled only when building from sources.

Anyway, you can find all the themes you want on the official website (here).
Warning: on windows, you may encounter significant slowdown at runtime white some themes.

The basic theme on windows is a little bit depressive in my opinion. Too much grey…

It somehow reminds me the old Windows application.

I prefer using the Clearlooks Theme. Nice without too much shiny effects.

Now… How to change the Gtk theme used by OpenViBE ?

When building from sources

1. Be sure to check “Gtk Themes” when installing the dependencies.
2. Go into dependencies/gtk.
3. in share/themes you will find many (many !) themes. Each one is in fact described in a file named gtkrc.
4. Copy the gtkrc file you want into etc/gtk-2.0.
5. Run the Designer.

When installing from binaries

You don’t have the Gtk themes installed when using the windows installer.

1. Download themes you find on the Internet
2. Go into dependencies/gtk.
3. Copy the theme files (there should at least a gtkrc) into etc/gtk-2.0.
4. Run the Designer.

Cheers !

Laurent-

The Art of Comment

When a scenario has to many boxes and too many links, it can be complex to edit it. We call that kind spiderman scenario.
In that case, comments blocks are very useful. Look at the samples scenarios given with the official release.
When you open a scenario like the P300 speller ones (50+ boxes), the comments help a lot in order to understand:
– the purpose of the scenario
– the purpose of a particular part of the pipeline
– where configuration can be done
– warning on various aspects : connect or not a specific box, tweak some settings, etc.

Don’t hesitate to comment your scenario, by pressing the “add comment” button on the top toolbar, or by pressing “C” when editing the scenario.
Small tip : when pressing the return key, you will save the current comment. If you want to add a line feed, press Shift + return when editing the comment.

The comments can use pango tags to format the text nicely. Here is the most common tag you can use :
<i>plop</i> : italic
<b>plop</b> : bold
<u>plop</u> : underline
<small>plop</small> : small fontsize
<big>plop</big> : big fontsize

For more specific format use the “span” tag. For example:
<span color=”red”>plop</span> : change the color to red. Instead of the color name you can use hexa code, like #AA00FF.
<span font_desc=”50″>plop</span> : change the font size to a specific value. Normal size is 8.

Complete listing of pango tags here.

Hope this helps !

Laurent-

The Designer shortcuts

The OpenViBE Designer has many features in common with “edition” programs : select, copy-paste objects, navigate in a view, etc.

We implemented standard shortcuts for these features, very useful when building a scenario quickly.
Here is a list of the most useful shortcuts, the ones I use all the time in my job 🙂

Available since 0.10.0 :

Ctrl + C	copy current selection
Ctrl + X	cut current selection
Ctrl +V	paste
Ctrl + Z	undo
Ctrl + Y	redo
Ctrl + N	open a new scenario
Ctrl + O	open an existing scenario
Ctrl + W	close current scenario
Ctrl + S	save current scenario
F1	open in your web browser the documentation page of the selected box
F2	rename the selected boxes. And I mean ALL selected boxes will end with the same name 🙂
Shift + mouse wheel	Scroll the view horizontally
C	Add a new comment box where the mouse pointer is

And if you want to control the player with your keyboard, here is the keys, in the same order as in the Designer toolbar.
Be sure to have the focus on the scenario. If your scenario has visualization windows, they tend to get the focus when playing the scenario.
You must click on the scenario again to get back the focus and control the player.

Only available on the SVN (sinc rev.2922)

F5	STOP
F6	ONE STEP FORWARD
F7	PLAY / PAUSE
F8	FAST FORWARD

Hope this helps !

Laurent-