Programming Reference:BCI2000 Source Code

From BCI2000 Wiki
Jump to navigation Jump to search

Version Management

The BCI2000 source code is managed with the help of Subversion, an open-source cross-platform versioning tool widely used in various kinds of projects.

Subversion (SVN) uses the HTTP-based WebDAV protocol, so even web browsers may be used to browse directories and files. Still, a true SVN client software is required to access all features of the versioning system.

Stable Versions and Branches

For each upcoming major release of BCI2000, a branch is created in /svn/branches. Development of the new version occurs there, and only bug fixes are committed to /svn/trunk. Between major releases, some amount of development occurs in the trunk directory in addition to fixing bugs. Thus, it may be that the trunk does not build on all compilers, or contains unfixed bugs. To obtain a stable, tested version of the BCI2000 source code, please checkout one of the tagged release versions from /svn/tags/releases. These correspond to binary distributions as listed on the binary distribution page. The version corresponding to the most current binary distribution is available by checking out /svn/tags/releases/current. By doing an "SVN update" on the checkout folder, you will then be able to update to the latest stable version of the source code.

Access

Access to the BCI2000 source code requires a BCI2000 user account, and agreeing to the GNU Public License (GPL). You may create a user account online, as described on the "Creating a User Account" page.

Browsing the Source Code Repository Online

Online viewing, and comparison of different versions of all source code files, is possible with a web browser (http://www.bci2000.org/tracproj/browser). (If you get a message about "viewing privileges", click the "login" link at the top right to log in.)

SVN command line client

The SVN command line client is available (and often installed by default) on all major operating systems. For creating a local copy of the BCI2000 source code, the command is

svn checkout https://www.bci2000.org/svn/tags/releases/current/ --username <your BCI2000 account name>

TortoiseSVN Client

For Win32 platforms, we recommend TortoiseSVN, a comfortable-to-use SVN client integrated into the Explorer shell.

Downloading the BCI2000 source as an archive

For users who have difficulties accessing the BCI2000 source via SVN, there is a copy of the source repository available for download at https://www.bci2000.org/downloads/src/BCI2000src.txz . This copy reflects the current revision of the BCI2000 source, and is updated daily.

Howto Pages

Directory Layout

The SVN directory layout matches that of the BCI2000 binary distribution, and is as follows:

batch on-line system startup scripts
build scripts and utilities for building BCI2000 from source
data online data output
doc information, HTML help files
parms on-line system parameter files
prog on-line system executables
tools off-line analysis tools
src source code

The build and src subtrees are not present in the binary distribution--they hold the BCI2000 build system and source code. Below src, there should be no end-user executables, compiled LaTeX files, or pdf files converted from editable formats. Rather, their source files should go below src, and their end-user versions go into either prog, doc, or the appropriate end-user directory below tools. In all makefiles or project files that are relevant to the binary distribution, the compiled output is directed into the appropriate executable directory (prog or tools/mytool).

The build and src subtrees are organized as follows:

build

This is the main workbench area for building and customizing BCI2000 from source. CMake is launched from here (and several batch files are provided here to call CMake with the correct options for various compilers). The resulting global Makefile or project file will be created here. New custom BCI2000 modules and filters can be created easily using the NewBCI2000Module and NewBCI2000Filter tools, which also appear here, once they themselves have been compiled. More information about the build system is available here.

build/buildutils

Holds small utility programs that are used for maintenance.

build/buildutils/tests

Scripts and data used to test executables during the build phase (make test).

src/contrib

Source code (and legacy Borland project files) from the Contributions section. Paralleling organization of the core directory, there are subdirectories for application, signal processing, and source modules, and for tools. An additional directory, AppConnector, contains programs connecting via the App Connector interface.

Each project from the contrib directory should have its own documentation page accessible through the Contributions:Contents hierarchy.

By default, contrib projects are excluded from the build process. For information about how to compile and use a piece of software located in the contrib directory, see the Building BCI2000 Howto page.

src/core

Source code (and legacy Borland project files) for the BCI2000 core distribution. Below this directory, there are subdirectories for the Operator module, core modules, and tools.

src/custom

This directory does not exist when you first check out the source code. It is a reserved location which you can create and use for your own projects, parallel to core and contrib.

src/shared

The core, contrib and custom directories will only contain project files (or CMakeLists.txt files), and source code that is unique to the respective piece of software. BCI2000 framework code is contained below the "shared" directory.

Inside the "shared" directory, code is organized into subdirectories as follows:

  • accessors
contains code related to the Environment accessor layer,
  • bcistream
provides code for the bcierr, bciout, and bcidbg output streams, and error handling,
  • config
contains configuration and versioning information in form of header files,
  • fileio
contains code dealing with directories and files, and its subdirectories represent data formats used for output and input,
  • gui
provides a very basic platform-independent interface layer to graphical elements.
  • modules
holds code that is common to core modules, and one subdirectory for common code from each application, signal processing, and source modules. Most BCI2000 filters are located inside those subdirectories.
  • obj
holds pre-compiled header files during make and build processes,
  • types
contains BCI2000-specific data types that may be sent through BCI2000 messages, such as signals, parameters, and states.
  • utils
contains miscellaneous utility classes and functions.

src/extlib

Unlike the shared directory, this directory contains libraries, or interfaces to libraries, that are used by BCI2000 but not part of BCI2000 itself. Typically, the code in extlib is independent of BCI2000, and in most cases external to the BCI2000 project, e.g. provided by library vendors.

src/doc

Contents of this directory are related to the production of documentation, they do not represent documentation itself. Its figures subdirectory holds original vector format versions of PNG files uploaded into the wiki, and additional versioned copies of those PNG files. wiki2help contains maintenance software related to the conversion of Wiki pages into the HTML help files located in the BCI2000 distribution's doc/htmlhelp directory.

Coding Guidelines

We maintain a loose set of guidelines/rules that is aimed at readability and maintenance efficiency. These rules are not obligatory but we ask contributors to consider them before handing in their code.

See also

SVN Client Setup, Using TortoiseSVN, Building BCI2000