Developing cross-platform plugins for BrainVoyager QX Hester Breman, Pim Pullens and Joost Mulders Brain Innovation B.V. June 12, 2009 Contents 1 Description 3 1.1 About plugins . 3 1.1.1 Terminology . 3 1.2 General development process . 5 1.2.1 Creating a *.dylib (Mac OS X) . 5 1.2.2 Mixing C and C++ . 5 2 Developing source code 7 2.1 Integrated Development Environments (IDE) . 7 2.1.1 Creating a project in Visual Studio . 8 2.1.2 Creating a project in XCode . 12 2.1.3 Code completion . 12 2.2 Using tools and libraries . 13 2.2.1 Using Numerical Recipes’ code . 13 2.2.2 Using precompiled libraries . 13 2.3 Platform differences . 14 2.3.1 Swapping . 14 2.4 Documentation generation (API) . 15 2.4.1 Windows . 15 2.4.2 Mac OS X . 16 3 Configuration 18 3.1 Introduction . 18 3.2 Changing plugin names . 18 3.2.1 Windows: Visual Studio . 18 3.2.2 Mac OS X: XCode . 19 4 Building the plugin 20 4.1 Windows . 20 4.2 Linux . 20 4.2.1 Using a batch file . 20 5 Debugging 22 5.1 Introduction . 22 5.1.1 Debugging symbols . 22 5.1.2 General problem solving . 22 5.2 Debugging on Windows . 23 5.2.1 Preparation . 23 5.2.2 Setting breakpoints in the code . 24 5.3 Run the BrainVoyager QX plugin while debugging . 26 5.3.1 Starting the debugging . 26 5.3.2 Solving problems . 29 1 5.4 Debugging on Mac OS X . 30 5.4.1 Solving problems . 32 6 Source control 33 6.1 Introduction . 33 6.2 Source control on Windows . 33 6.3 Source control on Mac OS X . 33 6.4 Source control on Linux . 33 A Document history 35 2 Chapter 1 Description 1.1 About plugins It is possible to add your own functionality in C++ code to BrainVoyager QX [1] via the plugin mechanism. The code is added to the execute() function of the *.cpp file (derived from a template file that should be used in order to get the plugin working) and possibly additional files in case the execute() function becomes too large. Also, BrainVoyager QX plugin access header files are provided (via the ’Download’ section of the BrainVoyager website http://www.brainvoyager.com/). These header files contain file format and function definitions. The header files are updated regularly, so take care to use the proper version for your BrainVoyager program. 1.1.1 Terminology The following information about plugins was obtained from information provided online by Microsoft. A dynamic-link library (DLL) is an executable file that acts as a shared library of functions. Dynamic linking provides a way for a process to call a function that is not part of its executable code. The executable code for the function is located in a DLL, which contains one or more functions that are compiled, linked, and stored separately from the processes that use them. DLLs also facilitate the sharing of data and resources. Multiple applications can simultaneously access the contents of a single copy of a DLL in memory. Dynamic linking differs from static linking in that it allows an exe- cutable module (either a .dll or .exe file) to include only the information needed at run time to locate the executable code for a DLL function. In static linking, the linker gets all of the referenced functions from the static link library and places it with your code into your executable. Using dynamic linking instead of static linking offers several advan- tages. DLLs save memory, reduce swapping, save disk space, upgrade easier, provide after-market support, provide a mechanism to extend the MFC [Microsoft Foundation Classes, HB] library classes, support multilanguage programs, and ease the creation of international ver- sions. The following definitions were obtained from Apple documentation. Executable: Executables are standalone binaries and cannot be linked. 3 Dynamic Library: Dynamic libraries are linked at build time and loaded automat- ically when needed. Bundle: Bundle libraries are loaded explicitly at run time (Mac OS X only). Static Library: Static libraries are linked at build time and loaded at execution time. Relocatable Object File: Object files are single-module files which are linked at build time. 4 1.2 General development process 1.2.1 Creating a *.dylib (Mac OS X) The process to create a dynamic library (*.dylib) for Mac OS X is depicted in figure 1.1. Figure 1.1: Creating a dynamic library (*.dylib) on Mac OS X 1.2.2 Mixing C and C++ When using C++ concepts in your C code, including only the headers, for example <map>, <string> and <iterator> might not suffice to get the code working. One needs to declare using the namespace “standard” (see figure ??). 5 Figure 1.2: When mixing C++ with your C code, it can be necessary to add ‘using namespace std;’ 6 Chapter 2 Developing source code In this chapter are some suggestions provided that might be useful when coding a plugin for BrainVoyager QX. 2.1 Integrated Development Environments (IDE) Although some programmers prefer to developer their code in a text editor like vi or code editor, and compile the code with a Makefile, it is also possible to use a code development environment that provides editing and compiling functionality. This is called a integrated development environment (IDE). A well-known IDE for Windows is from Microsoft: Visual Studio. Apple provides the IDE XCode. For Linux KDevelop is available. This uses an external compiler, for example the GNU compiler gcc. Cross-platforms alternatives are Code::Blocks (see http://www.codeblocks.org/) and Qt Creator (see http://www.qtsoftware.com/downloads/). Thanks to Michele Rodaro for the Code::Blocks recommendation. 7 2.1.1 Creating a project in Visual Studio When creating a plugin for BrainVoyager QX, one always needs the BrainVoyager Plugin Access functions and the file format files (for example Plugin_VMR_Header.h). Therefore, in Visual Studio, we can start a new project from existing files (see figure 2.1). Figure 2.1: Step 1 in Visual Studio 8 Select the C++ language (see figure 2.2). Figure 2.2: Step 2 in Visual Studio 9 Select the directory where the BrainVoyager Plugin Access header files are lo- cated. The Visual Studio project will be created in this folder as well (see figure 2.3). Figure 2.3: Step 3 in Visual Studio 10 Select the Dynamic Library type of project (see figure 2.4). Figure 2.4: Step 4 in Visual Studio 11 2.1.2 Creating a project in XCode 2.1.3 Code completion In XCode on Mac OS X, code completion can be performed by CodeSense. Go to the ‘Preferences’ tab of XCode to enable CodeSense. On Windows, you will need an additional tool for Visual Studio to perform autocompletion; the WholeTomato software is well recommended. 12 2.2 Using tools and libraries 2.2.1 Using Numerical Recipes’ code The numerical recipes from Vetterling et al [2] can be used successfully if 1. the function files (*.c or *.cpp) are embedded in the XCode or Visual Studio project; in case of *.c files, the files might need to be renamed to *.cpp 2. the project settings are thus modified that the headers of the numerical recipes functions can be found 3. when using the data structures, take care of the indexing of matrices and arrays (1...n) instead of (0...n-1). 2.2.2 Using precompiled libraries The following section can be relevant when using pre-compiled (scientific) libraries. 1. Copy the *.lib file into C:\Program Files\Microsoft Visual Studio 8\VC\PlatformSDK\Lib. In Visual Studio, set the properties of your project as follows: 2. Properties ! Linker ! Input ! additional dependencies ! select the *.lib file. 3. Properties ! General ! Additional Include directories ! add the directories where other files of the library are located. 4. Copy the *.dll file(s) into the output directory of your project (ie the place where your nice exe or dll lives). 13 2.3 Platform differences 2.3.1 Swapping Some machines are still big endian, which causes a shuffling of the bytes in each multi-byte data type like short, float, integer and double. An example is the Apple PowerPC. To adapt the data handling to the routines, the headers CFByteOrder.h of the CoreFoundation classes or NS....h of the Cocoa classes can be used. Apple developed a mechanism called universal binary, which runs on both Pow- erPC and Intel Mac machines. When the dynamic library was originally developed for PowerPC but is used on Intel Mac, the translation system “Rosetta” is used to provide necessary adaptations of the plugin. 14 2.4 Documentation generation (API) When other people are going to use the functions, or just for later, it might be use- ful to write above each function a short explanation of the input parameters, the output values and the goal of the function. If these explanations are written with some attention for the format, they can be automatically collected in a document or HTML pages and resemble the interface to your functions, e.g. an Application Programmer’s Interface (API). Some open-source tools can be downloaded from SourceForge.net, like doxygen or doc++. Others are included in the integrated development environments (IDEs) like HeaderDoc in XCode on Mac OS X. The documentation generation usually consists of two steps. In the first step, all documentation fragments are collected; in doc++ for example, this process is called “docify”. Secondly, the documentation is generated from the collected frag- ments; in doc++, this is called “docxx”.