Programming Reference:BCI2000 Source Code
- 1 Version Management
- 2 Stable Versions and Branches
- 3 Access
- 4 Howto Pages
- 5 Directory Layout
- 6 Coding Guidelines
- 7 See also
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 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 http://www.bci2000.org/svn/tags/releases/current/ --username <your BCI2000 account name>
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 http://www.bci2000.org/downloads/src/BCI2000src.txz . This copy reflects the current revision of the BCI2000 source, and is updated daily.
- Accessing the BCI2000 source code:
- Building BCI2000 from the source code:
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|
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:
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.
Holds small utility programs that are used for maintenance.
Scripts and data used to test executables during the build phase (make test).
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.
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.
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:
- contains code related to the Environment accessor layer,
- provides code for the bcierr, bciout, and bcidbg output streams, and error handling,
- contains configuration and versioning information in form of header files,
- contains code dealing with directories and files, and its subdirectories represent data formats used for output and input,
- provides a very basic platform-independent interface layer to graphical elements.
- 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.
- holds pre-compiled header files during make and build processes,
- contains BCI2000-specific data types that may be sent through BCI2000 messages, such as signals, parameters, and states.
- contains miscellaneous utility classes and functions.
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.
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.
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.