Difference between revisions of "Programming Reference:Build System"

From BCI2000 Wiki
Jump to: navigation, search
Line 1: Line 1:
 +
'''The majority of this documentation only applies to BCI2000 Ver 3.0'''
 +
 
== Introduction ==
 
== Introduction ==
 
BCI2000 was originally intended to be built only on the Borland compiler due to the fact that much of its architecture was built on the visual components library (VCL) by Borland.  By making BCI2000 compiler independent, we could no longer use VCL, and had to choose an open source and cross platform replacement.  Qt was chosen to replace VCL because it is not only compiler independent but is also platform independent, a future goal for BCI2000.  
 
BCI2000 was originally intended to be built only on the Borland compiler due to the fact that much of its architecture was built on the visual components library (VCL) by Borland.  By making BCI2000 compiler independent, we could no longer use VCL, and had to choose an open source and cross platform replacement.  Qt was chosen to replace VCL because it is not only compiler independent but is also platform independent, a future goal for BCI2000.  
Line 26: Line 28:
 
**Any other IDE supported by CMake generators (Eclipse CDT, etc...)
 
**Any other IDE supported by CMake generators (Eclipse CDT, etc...)
  
== How To Build ==
+
== How To Build Using CMake ==
# These are
+
#Ensure that your compiler and IDE are installed on the computer.  This means that Visual Studio is installed if you intend to use Visual Studio, or that MinGW and Code::Blocks are installed if you intend to use Code::Blocks as your IDE and MinGW as your compiler. 
# Numbered?
+
#Download and install the Qt SDK from http://www.qtsoftware.com/
 +
##After Installing, add the install path to your PATH environment variable.
 +
###Right click on "My Computer" - select Properties.
 +
###Go to the "Advanced" tab and click the "Environment Variables" button at the bottom.
 +
###In the system variables pane, locate the "Path" variable, highlight and click "Edit"
 +
###Move the cursor to the end of the "Variable value:" text box and type: ";C:\Qt\XXXX.XX\qt\bin\" (without the quotes, XXXX.XX is version. Replace) Adding paths to the "Path" variable is done using semicolon deliminations with no space between the previous path's semicolon and the new path.
 +
###Click Ok, and click Ok again, and Ok again.
 +
##'''IF USING VISUAL STUDIO:''' You need to build Qt from source to get Visual Studio ".lib"s
 +
###Open a Visual Studio command prompt and navigate to C:\Qt\XXXX.XX\qt
 +
###Run the "configure" command
 +
###Type "o" for open source, type "y" for yes
 +
###Qt will now be configured to generate a Visual Studio Project.  This will take a while.
 +
###Build the libraries using the Visual Studio Compiler
 +
####You have two choices here.  If you're looking for an easy, automated build process, but takes a very long time (3-4 Hours), simply run "nmake" from this dir.
 +
####If you're looking for a faster build, only build the necessary libraries.
 +
#####Cd into Qt/XXXX.XX/qt/src/corelib and run "nmake"
 +
#####Cd into Qt/XXXX.XX/qt/src/gui and run "nmake"
 +
#####Cd into Qt/XXXX.XX/qt/src/network and run "nmake"
 +
#####Cd into Qt/XXXX.XX/qt/src/opengl and run "nmake"
 +
#####Cd into Qt/XXXX.XX/qt/src/winmain and run "nmake"
 +
#Download and install cmake (Version 2.6 or higher!) from http://www.cmake.org/ - '''Add to path for all users.'''
 +
#Go to the BCI2000/build directory and double click the .bat file which best describes your intnded platform.  (ie. if you plan to use Visual Studio 2008, run the Visual Studio 2008 .bat file)
 +
#Wait while cmake examines your computer, finds qt and your compiler, and generates applicable project files for your system
 +
#Open the generated project/solution in the IDE and build BCI2000, or - if makefiles were generated - run the make command from a command prompt.  Refer to the IDE help for IDE specific instructions on how to build an application.
 
   
 
   
 
== How To Test ==
 
== How To Test ==
  
Text to follow is for reference as I build this pagePlease ignore.
+
It is important - especially if you're using an unsupported compiler/ide - to test your executables once they've been built to make sure they function properly.
 +
 
 +
'''To run testing:'''
 +
#Ensure that the entire BCI2000 project has built successfully and that executables exist in the <tt>BCI2000/prog</tt> directory, the <tt>BCI2000/tools/cmdline</tt> directory, and the <tt>BCI2000/build/buildutils/test</tt> directory.
 +
#Run "run_tests.bat" in the <tt>BCI2000/build/buildutils/test</tt> directory.
 +
 
 +
The tests will run and report a message after they've finished whether they've failed or not.  You may see a message in the beginning of the test stating that a directory does not exist.  This is normal behavior and does not reflect whether or not your executables have failed testing or not.
 +
 
 +
'''A Note on found differences:''' depending on how many differences found it may not indicate that you have a broken build.  Sometimes different compilers handle random number generation differently than others.  These can account for small differences in calculated state values. The default ref files were generated using Borland 2007.  If your compiler is different, this may not be a problem.   
  
===This is a subcategory===
+
== Known Issues ==
  
{|border="1"
+
*'''Visual Studio''' tends to put executables into a Release or Debug directory within prog. This behavior is non-standard when compared to every other compiler.  Behavior may be changed by going into the specific project properties and deleting "$(Configuration Name) from the  "Output Directory" under the general sub-heading.  This behavior may be fixed by a future release of CMake.
|
 
|This
 
|Code
 
|-
 
|has
 
|a
 
|border
 
|-
 
|and
 
|its
 
|nice
 
|}
 
  
<tt>CodeFont()</tt>  
+
*'''MinGW, Borland''' and other single configuration generators within CMake only generate one configuration at CMake Run-time.  By default, this is set to the release configuration.  It can be set - along with specific compiler options - in <tt>BCI2000/build/cmake/BuildConfigurations.cmake</tt>.  The Visual Studio generator will ignore settings in this file.
  
===Another Subhead===
+
== Conclusions ==
  
* This text is bulleted
+
Now that BCI2000 is open to other compilers - and soon - other platforms, support may not exist for every possible compiler/platform available. Certain compilers do not optimize code as well as others, and this behavior may lead to poor system latencies during BCI2000 experiments. The supported compilers have been rigorously tested and confirmed to be adequate for compiling the BCI2000 sources.  If you wish to use a different compiler,
 +
be sure to run tools/BCI2000Certification in order to confirm your setup.  CMake is a powerful tool, but in the end, your ability to compile the sources is completely up to your IDE/compiler choice.  If your IDE/compiler choice is not listed above, we strongly urge you to consider using one which we will support.  If you run into problems using an unsupported IDE/compiler combination, you can try to find help at the BBS - www.bci2000.org/phpbb/index.php.  BCI2000 should compile as effortlessly as possible on supported platforms.
  
 
[[Category:Framework API]][[Category:Development]]
 
[[Category:Framework API]][[Category:Development]]

Revision as of 19:05, 13 August 2009

The majority of this documentation only applies to BCI2000 Ver 3.0

Introduction

BCI2000 was originally intended to be built only on the Borland compiler due to the fact that much of its architecture was built on the visual components library (VCL) by Borland. By making BCI2000 compiler independent, we could no longer use VCL, and had to choose an open source and cross platform replacement. Qt was chosen to replace VCL because it is not only compiler independent but is also platform independent, a future goal for BCI2000.

As such, Qt is required for compiling the BCI2000 source on a non-Borland platform. If Borland is still being used as the compiling environment, VCL is still temporary supported and the project will be built using the VCL for it's graphical elements. If Visual Studio or MinGW is used to compile BCI2000, you will need to have the Qt SDK installed on your computer.

To support such a large number of platforms and compilers, BCI2000 has turned to CMake http://www.cmake.org to generate makefiles, project files, and visual studio solutions. Cmake can be thought of as a meta-makefile, in that it examines your build environment, and sets up a Visual Studio project, or a Code::Blocks project which is custom tailored to your environment. It is because of varying build environments, that BCI2000 can not come with a set Visual Studio solution file, or an Eclipse project file without giving the user a lot of headache in setting up the compiler to work correctly. The number of platforms BCI2000 supports is only limited by the number of platforms and compilers that CMake has generators for.

Dependencies

Qt 4.5+ http://qt.nokia.com/products/ is required. In case the Qt website goes down, or is changed in some drastic way, a mirror of a confirmed working version of Qt 4.5 is provided here: <LINK>

Supported Environments

  • Supported Operating Systems
    • Windows XP, Windows 2000 (Vista and Windows 7 have poor Audio Video latencies - not recommended for BCI2000)
    • Macintosh OSX support coming soon
    • Linux support coming soon
  • Supported Compilers
    • Borland 6, 2007, 2009
    • Visual Studio 8 (2005), 9 (2008)
    • MinGW
  • Supported IDEs
    • Borland 6, 2007, 2009 (Note: Use the project files in the src directory for Borland IDE support. This support is being phased out)
    • Visual Studio 8 (2005), 9 (2008) (via CMake)
    • Code::Blocks - MinGW Makefiles (via CMake)
    • Any other IDE supported by CMake generators (Eclipse CDT, etc...)

How To Build Using CMake

  1. Ensure that your compiler and IDE are installed on the computer. This means that Visual Studio is installed if you intend to use Visual Studio, or that MinGW and Code::Blocks are installed if you intend to use Code::Blocks as your IDE and MinGW as your compiler.
  2. Download and install the Qt SDK from http://www.qtsoftware.com/
    1. After Installing, add the install path to your PATH environment variable.
      1. Right click on "My Computer" - select Properties.
      2. Go to the "Advanced" tab and click the "Environment Variables" button at the bottom.
      3. In the system variables pane, locate the "Path" variable, highlight and click "Edit"
      4. Move the cursor to the end of the "Variable value:" text box and type: ";C:\Qt\XXXX.XX\qt\bin\" (without the quotes, XXXX.XX is version. Replace) Adding paths to the "Path" variable is done using semicolon deliminations with no space between the previous path's semicolon and the new path.
      5. Click Ok, and click Ok again, and Ok again.
    2. IF USING VISUAL STUDIO: You need to build Qt from source to get Visual Studio ".lib"s
      1. Open a Visual Studio command prompt and navigate to C:\Qt\XXXX.XX\qt
      2. Run the "configure" command
      3. Type "o" for open source, type "y" for yes
      4. Qt will now be configured to generate a Visual Studio Project. This will take a while.
      5. Build the libraries using the Visual Studio Compiler
        1. You have two choices here. If you're looking for an easy, automated build process, but takes a very long time (3-4 Hours), simply run "nmake" from this dir.
        2. If you're looking for a faster build, only build the necessary libraries.
          1. Cd into Qt/XXXX.XX/qt/src/corelib and run "nmake"
          2. Cd into Qt/XXXX.XX/qt/src/gui and run "nmake"
          3. Cd into Qt/XXXX.XX/qt/src/network and run "nmake"
          4. Cd into Qt/XXXX.XX/qt/src/opengl and run "nmake"
          5. Cd into Qt/XXXX.XX/qt/src/winmain and run "nmake"
  3. Download and install cmake (Version 2.6 or higher!) from http://www.cmake.org/ - Add to path for all users.
  4. Go to the BCI2000/build directory and double click the .bat file which best describes your intnded platform. (ie. if you plan to use Visual Studio 2008, run the Visual Studio 2008 .bat file)
  5. Wait while cmake examines your computer, finds qt and your compiler, and generates applicable project files for your system
  6. Open the generated project/solution in the IDE and build BCI2000, or - if makefiles were generated - run the make command from a command prompt. Refer to the IDE help for IDE specific instructions on how to build an application.

How To Test

It is important - especially if you're using an unsupported compiler/ide - to test your executables once they've been built to make sure they function properly.

To run testing:

  1. Ensure that the entire BCI2000 project has built successfully and that executables exist in the BCI2000/prog directory, the BCI2000/tools/cmdline directory, and the BCI2000/build/buildutils/test directory.
  2. Run "run_tests.bat" in the BCI2000/build/buildutils/test directory.

The tests will run and report a message after they've finished whether they've failed or not. You may see a message in the beginning of the test stating that a directory does not exist. This is normal behavior and does not reflect whether or not your executables have failed testing or not.

A Note on found differences: depending on how many differences found it may not indicate that you have a broken build. Sometimes different compilers handle random number generation differently than others. These can account for small differences in calculated state values. The default ref files were generated using Borland 2007. If your compiler is different, this may not be a problem.

Known Issues

  • Visual Studio tends to put executables into a Release or Debug directory within prog. This behavior is non-standard when compared to every other compiler. Behavior may be changed by going into the specific project properties and deleting "$(Configuration Name) from the "Output Directory" under the general sub-heading. This behavior may be fixed by a future release of CMake.
  • MinGW, Borland and other single configuration generators within CMake only generate one configuration at CMake Run-time. By default, this is set to the release configuration. It can be set - along with specific compiler options - in BCI2000/build/cmake/BuildConfigurations.cmake. The Visual Studio generator will ignore settings in this file.

Conclusions

Now that BCI2000 is open to other compilers - and soon - other platforms, support may not exist for every possible compiler/platform available. Certain compilers do not optimize code as well as others, and this behavior may lead to poor system latencies during BCI2000 experiments. The supported compilers have been rigorously tested and confirmed to be adequate for compiling the BCI2000 sources. If you wish to use a different compiler, be sure to run tools/BCI2000Certification in order to confirm your setup. CMake is a powerful tool, but in the end, your ability to compile the sources is completely up to your IDE/compiler choice. If your IDE/compiler choice is not listed above, we strongly urge you to consider using one which we will support. If you run into problems using an unsupported IDE/compiler combination, you can try to find help at the BBS - www.bci2000.org/phpbb/index.php. BCI2000 should compile as effortlessly as possible on supported platforms.