Programming Reference:Build System (obsolete): Difference between revisions

Latest revision as of 21:57, 24 February 2021

Introduction

Early versions of BCI2000 (2.x and earlier) were dependent on the visual components library (VCL) by Borland and could only be built using the Borland compiler. Since version 3.0, Qt has replaced the VCL because it is not only compiler-independent, but also platform-independent.

To support many platforms and compilers, BCI2000 is using CMake https://www.cmake.org to generate Makefiles, project files, and Visual Studio solutions. CMake can be thought of as a meta-makefile; it examines your build environment and sets up a Visual Studio project, a Code::Blocks project, or a Unix Makefile which is custom tailored to your environment. Due to the wide variation in possible build environments, BCI2000 can not come with a fixed Visual Studio solution file, or a fixed Eclipse project file (such fixed solutions would always end up costing users a lot of effort). Thus, the number of platforms BCI2000 supports is mainly limited by the number of platforms and compilers for which CMake has generators.

Supported Environments

Supported Operating Systems
- 32 and 64-bit Windows systems
- Windows 7, 8, 10 (Vista not recommended)
- Support for Unix-like systems (macOS, Linux) is currently limited to building mex files
Supported Compilers
- Visual Studio 2015, 2017, 2019 full and community editions
- MinGW is currently unsupported
Supported IDEs
- Qt Creator
- Visual Studio 2015, 2017, 2019

How To Build Using CMake

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 QtCreator are installed if you intend to use QtCreator as your IDE and MinGW as your compiler.
Download and install a recent version of cmake (Version 3.14.5 at the time of this writing) from https://www.cmake.org/ - Add to path for all users.
Download and install Qt based on your Visual Studio version, and system's architecture. For example, if you wanted to build BCI2000 as a 32 bit architecture on Visual Studio 2019, make sure that you choose the most recent Qt version which supports a 32 bit architecture and Visual Studio 2019; at the time of writing this, that would be Qt 5.15.2: MSVC 2019 32 bit. The same goes for if you want to compile BCI2000 for a 64 bit system, go to your most recent Qt version, and choose MSVC 2019 64 bit.
Create a build directory inside or outside your BCI2000 source tree, open a Windows shell inside the build directory (e.g., "BCI2000_build64"), and run "cmake-gui path/to/bci2000/build/directory".
In the cmake GUI, click "configure", and select the compiler of your choice.
If you are using Visual Studio 2015, and cmake fails to find your compiler, then you may need to copy the files rc.exe and rcdll.dll from one of your Program Files (x86)/WindowsKits bin folders to Program Files (x86)/Microsoft Visual Studio 14.0/VC/bin.
Now that you have Qt installed on your machine, you can now set the CMake variable Qt5_DIR to your Qt installation's lib/cmake/Qt5 directory, and click "configure" again.
Finally, in the cmake GUI, click "generate" to generate a project or solution file.
Open the generated project/solution (for Visual Studio, this is called "BCI2000.sln") in the IDE of your choice. Or, if you are using MinGW make, run the make command from the command prompt using the Makefile in the top-level "build" directory. Refer to your IDE's help for IDE-specific instructions on how to build an application.
Even though CMake must always be run from one top-level place (the "build" directory), and will spend several seconds generating a Makefile or project file for the whole BCI2000 tree at once, this does not mean that you have to compile all of BCI2000 at once. In the next step, if you're using MinGW-make on the command-line, you could for example type "make Operator" or "make SignalGenerator" to build only selected modules (again, you should be in the top-level "build" directory when you do this). Visual IDEs usually have their own equivalent of this: for example, in Visual Studio 2019, you can right-click on a particular module and select "Build".
If you build the targets "NewBCI2000Module" and "NewBCI2000Filter", this will create two new binary executables with these names. They will be found in the top-level "build" directory (and, in common with CMake and make, they should be launched only from this location). Launch NewBCI2000Module to create a new project in order to compile your own custom module. Launch NewBCI2000Filter to create a new filter and add it to a project you have already created. In either case, you may need to re-run CMake (step 3) in order to ensure these changes are reflected in the project file.

Known Issues

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. To turn on a debug build in a single configuration generator, run cmake -i in the build directory and set CMAKE_BUILD_TYPE to "Debug" when prompted.

All Compilers handle non standard characters, such as umlauts and characters with accents or tildes, differently. Because BCI2000 currently has no standardized way of handling non standard characters in a cross-compiler environment, it is strongly recommended that - for the time being - special characters are not used in localizations during the development of BCI2000 Ver 3.0.

Conclusions

Now that BCI2000 is open to a number of platforms, and compilers, 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, ability to compile the sources is completely up to the IDE/compiler choice. If your IDE/compiler choice is not listed above, it is strongly urged that you to consider using one which is supported. If you run into problems using an unsupported IDE/compiler combination, you can try to find help at the BBS - https://www.bci2000.org/phpbb/index.php. BCI2000 should compile as effortlessly as possible on supported platforms.

@@ Line 1: / Line 1: @@
-'''This documentation only applies to BCI2000 Ver 3.0 (Now current HEAD)'''
 == Introduction ==
-Previous versions of BCI2000 (2.x and earlier) were dependent on the visual components library (VCL) by Borland and could only be built using the Borland compiler.  For version 3.0, we made BCI2000 compiler-independent, and therefore had to choose a portable replacement for VCL.  Qt was chosen to replace VCL because it is not only compiler-independent, but also platform-independent; a future goal for BCI2000.
+Early versions of BCI2000 (2.x and earlier) were dependent on the visual components library (VCL) by Borland and could only be built using the Borland compiler.  Since version 3.0, Qt has replaced the VCL because it is not only compiler-independent, but also platform-independent.
-As such, Qt is required for compiling the BCI2000 source on a non-Borland platform.  If Borland is still being used as the build environment, VCL is still temporarily supported and the project will be built using the VCL for its graphical elements.  For Visual Studio or MinGW builds of BCI2000, a stripped-down version of the Qt SDK is provided in the BCI2000 source tree.
-To support such a large number of platforms and compilers, BCI2000 is using CMake http://www.cmake.org to generate Makefiles, project files, and Visual Studio solutions.  CMake can be thought of as a meta-makefile; it examines your build environment and sets up a Visual Studio project, a Code::Blocks project, or a Unix Makefile which is custom tailored to your environment.  Due to the wide variation in possible build environments, BCI2000 can not come with a fixed Visual Studio solution file, or a fixed Eclipse project file (such fixed solutions would always end up costing users a lot of effort).  Once remaining dependencies on the Win32 API are removed, the number of platforms BCI2000 supports will only be limited by the number of platforms and compilers for which CMake has generators.
-<!--
-== 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>
+To support many platforms and compilers, BCI2000 is using CMake https://www.cmake.org to generate Makefiles, project files, and Visual Studio solutions.  CMake can be thought of as a meta-makefile; it examines your build environment and sets up a Visual Studio project, a Code::Blocks project, or a Unix Makefile which is custom tailored to your environment.  Due to the wide variation in possible build environments, BCI2000 can not come with a fixed Visual Studio solution file, or a fixed Eclipse project file (such fixed solutions would always end up costing users a lot of effort).  Thus, the number of platforms BCI2000 supports is mainly limited by the number of platforms and compilers for which CMake has generators.
--->
 == Supported Environments ==
 *'''Supported Operating Systems'''
-**Windows XP, Windows 2000 (Vista and Windows 7 have poor Audio Video latencies - not recommended for BCI2000)
+**32 and 64-bit Windows systems
-**64-bit Windows systems--[[Programming Reference:Building BCI2000 for Win64|please read this information]]
+**Windows 7, 8, 10 (Vista not recommended)
-**Macintosh OSX: compiles most of the time, not officially supported
+**Support for Unix-like systems (macOS, Linux) is currently limited to building mex files
-**Linux: compiles, but networking is currently broken
 *'''Supported Compilers'''
-**Borland/CodeGear/Embarcadero C++ Builder 2010 (core modules only, no GUI applications); C++ Builder XE2 is '''not supported'''
+**Visual Studio 2015, 2017, 2019 full and community editions
-**Visual Studio 9 (2008) and 10, download free Express version from [http://www.microsoft.com/express/downloads/ here] (although some BCI2000 modules require MFC, most modules may be built using the Express version)
+**MinGW is currently unsupported
-**MinGW with gcc 4.x
 *'''Supported IDEs'''
-**Borland/CodeGear/Embarcadero 6, 2007, 2009, 2010 (Note: Use the project files in the src directory for Borland IDE support. GUI application projects cannot be opened in the IDE. This support is being phased out)
+**Qt Creator
-**Visual Studio 9 (2008), Visual Studio 10 (via CMake)
+**Visual Studio 2015, 2017, 2019
-**Code::Blocks - MinGW Makefiles (via CMake)
-**Other IDEs supported by CMake generators (Eclipse CDT, ...), as long as these use the compilers listed above
-== Setting up MinGW to build BCI2000 ==
-This section only applies when you want to use MinGW as a compiler to build BCI2000. If you are using a different compiler/IDE, please proceed to the next section.
-*If you don't care whether your BCI2000 executables are statically linked against Qt libraries, you may use any recent version of MinGW. You will need to install Qt separately from BCI2000, and you will need to follow the instructions in the next section, "Building against a Qt distribution outside the BCI2000 source tree".
-*If you want to statically link BCI2000 against Qt libraries using any version of MinGW, you will need to install Qt separately from BCI2000, and recompile it from source with the "static" configuration flag as described [http://developer.qt.nokia.com/wiki/How_to_build_a_static_Qt_version_for_Windows_with_gcc here]. Then, follow the instructions in the next section, "Building against a Qt distribution outside the BCI2000 source tree".
-*If you want to use the pre-compiled static Qt libraries in the BCI2000 source tree, you will need to install a compatible version of MinGW. Currently, this is MinGW with gcc 4.4.0, which can be downloaded from [http://{{SERVERNAME}}/downloads/bin/mingw_440.zip]. Extract this file into any path on your local hard drive, and add its "bin" subdirectory to your system path variable so MinGW commands are recognized when entering them from the command line.
 == How To Build Using CMake ==
-#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.
+#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 QtCreator are installed if you intend to use QtCreator as your IDE and MinGW as your compiler.
-<!--
+#Download and install a recent version of cmake (Version 3.14.5 at the time of this writing) from https://www.cmake.org/ - '''Add to path for all users.'''
-#Download and install the Qt SDK from http://www.qtsoftware.com/
+#Download and install Qt based on your Visual Studio version, and system's architecture. For example, if you wanted to build BCI2000 as a 32 bit architecture on Visual Studio 2019, make sure that you choose the most recent Qt version which supports a 32 bit architecture and Visual Studio 2019; at the time of writing this, that would be Qt 5.15.2: MSVC 2019 32 bit. The same goes for if you want to compile BCI2000 for a 64 bit system, go to your most recent Qt version, and choose MSVC 2019 64 bit.
-##After Installing, add the install path to your PATH environment variable.
+#Create a build directory inside or outside your BCI2000 source tree, open a Windows shell inside the build directory (e.g., "BCI2000_build64"), and run "cmake-gui path/to/bci2000/build/directory".
-###Right click on "My Computer" - select Properties.
+#In the cmake GUI, click "configure", and select the compiler of your choice.
-###Go to the "Advanced" tab and click the "Environment Variables" button at the bottom.
+#If you are using Visual Studio 2015, and cmake fails to find your compiler, then you may need to copy the files rc.exe and rcdll.dll from one of your Program Files (x86)/WindowsKits bin folders to Program Files (x86)/Microsoft Visual Studio 14.0/VC/bin.
-###In the system variables pane, locate the "Path" variable, highlight and click "Edit"
+#Now that you have Qt installed on your machine, you can now set the CMake variable Qt5_DIR to your Qt installation's lib/cmake/Qt5 directory, and click "configure" again.
-###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.
+#Finally, in the cmake GUI, click "generate" to generate a project or solution file.
-###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
-###Add ";C:\Program Files\Microsoft Visual Studio XX\VC\bin\" to the "Path" variable
-###Copy "mspdb80.dll", "mspdbcore.dll", "mspdbsrv.exe" and "msobj80.dll" from "C:\Program Files\Microsoft Visual Studio XX\Common7\IDE"to the folder "C:\Program Files\Microsoft Visual Studio XX\VC\bin"
-###Open a Visual Studio command prompt and navigate to C:\Qt\XXXX.XX\qt
-###Type "set INCLUDE=C:\Program Files\Microsoft Visual Studio XX\VC\include;C:\Program Files\Microsoft SDKs\Windows\vXX\Include;%INCLUDE%"
-###Type "set LIB=C:\Program Files\Microsoft Visual Studio XX\VC\lib;C:\Program Files\Microsoft SDKs\Windows\vXX\Lib;%LIB%"
-###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.8.2 or higher!) from http://www.cmake.org/ - '''Add to path for all users.''' -- If you experience a problem with a version of cmake newer than 2.8.3, download cmake 2.8.3 from [http://{{SERVERNAME}}/downloads/bin/cmake-2.8.3-win32-x86.exe here].
-#Go to the BCI2000/build directory and double-click the "Make ... .bat" file which best describes your intended platform.  (for example, if you plan to use Visual Studio 2008, you would run the "Make VS2008 Project Files.bat"). These batch files will ask you a few questions about which parts of the BCI2000 distribution you want to make, and will then call CMake with the appropriate options.
-#Wait while cmake examines your computer, finds Qt and your compiler, and generates applicable project files for your system
 #Open the generated project/solution (for Visual Studio, this is called "BCI2000.sln") in the IDE of your choice.  Or, if you are using MinGW make, run the make command from the command prompt using the Makefile in the top-level "build" directory.  Refer to your IDE's help for IDE-specific instructions on how to build an application.
-# Even though CMake must always be run from one top-level place (the "build" directory), and will spend several seconds generating a Makefile or project file for the whole BCI2000 tree at once, this does not mean that you have to '''compile''' all of BCI2000 at once.  In the next step, if you're using MinGW-make on the command-line, you could for example type "make Operator" or "make SignalGenerator"  to build only selected modules (again, you should be in the top-level "build" directory when you do this).  Visual IDEs usually have their own equivalent of this:  for example, in Visual Studio 2008, you can right-click on a particular module and select "Build".
+# Even though CMake must always be run from one top-level place (the "build" directory), and will spend several seconds generating a Makefile or project file for the whole BCI2000 tree at once, this does not mean that you have to '''compile''' all of BCI2000 at once.  In the next step, if you're using MinGW-make on the command-line, you could for example type "make Operator" or "make SignalGenerator"  to build only selected modules (again, you should be in the top-level "build" directory when you do this).  Visual IDEs usually have their own equivalent of this:  for example, in Visual Studio 2019, you can right-click on a particular module and select "Build".
-# If you build the targets"NewBCI2000Module"  and "NewBCI2000Filter", this will create two new binary executables with these names. They will be found in the top-level "build" directory (and, in common with CMake and make, they should be launched only from this location). Launch NewBCI2000Module to create a new project in order to compile your own custom module.  Launch NewBCI2000Filter to create a new filter and add it to a project you have already created.  In either case, you may need to re-run CMake (step 3) in order to ensure these changes are reflected in the project file.
+# If you build the targets "NewBCI2000Module"  and "NewBCI2000Filter", this will create two new binary executables with these names. They will be found in the top-level "build" directory (and, in common with CMake and make, they should be launched only from this location). Launch NewBCI2000Module to create a new project in order to compile your own custom module.  Launch NewBCI2000Filter to create a new filter and add it to a project you have already created.  In either case, you may need to re-run CMake (step 3) in order to ensure these changes are reflected in the project file.
-== Building against a Qt distribution outside the BCI2000 source tree ==
-BCI2000 may be built against a standard Qt distribution rather than the stripped-down, precompiled version of Qt coming with the BCI2000 source code. Depending on your compiler and desired configuration (e.g., when using Visual Studio), you might need to re-build that distribution from source before building BCI2000.
-To enable the BCI2000 build system to use the external Qt distribution, open the file <tt>BCI2000/build/cmake/FindQt.cmake</tt>
-in a text editor.
-There, in line 10, replace
- SET( USE_STD_QT FALSE )
-with
- SET( USE_STD_QT TRUE )
-Then, go to the directory <tt>BCI2000/build</tt> and remove the file <tt>CMakeCache.txt</tt> before re-creating project files using the appropriate batch file in <tt>BCI2000/build</tt>.
-== 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:'''
-#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 <tt>test_executables.bat</tt> 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:''' differences may not indicate that you have a broken build.  Sometimes different compilers handle the precision of floating point numbers differently than others.  These can account for small differences in calculated signal or state values. The default reference 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 <tt>BCI2000/build/cmake/BuildConfigurations.cmake</tt>.  The Visual Studio generator will ignore settings in this file.  To turn on a debug build in a single configuration generator, run <tt>cmake -i</tt> in the build directory and set CMAKE_BUILD_TYPE to "Debug" when prompted.
@@ Line 105: / Line 37: @@
 == 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,
+Now that BCI2000 is open to a number of platforms, and compilers, 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, ability to compile the sources is completely up to the IDE/compiler choice.  If your IDE/compiler choice is not listed above, it is strongly urged that you to consider using one which is supported.  If you run into problems using an unsupported IDE/compiler combination, you can try to find help at the BBS - http://www.bci2000.org/phpbb/index.php.  BCI2000 should compile as effortlessly as possible on supported platforms.
+be sure to run tools/BCI2000Certification in order to confirm your setup.  CMake is a powerful tool, but in the end, ability to compile the sources is completely up to the IDE/compiler choice.  If your IDE/compiler choice is not listed above, it is strongly urged that you to consider using one which is supported.  If you run into problems using an unsupported IDE/compiler combination, you can try to find help at the BBS - https://www.bci2000.org/phpbb/index.php.  BCI2000 should compile as effortlessly as possible on supported platforms.
-== Windows platforms tested successfully so far ==
-{| border="1" cellspacing="0" cellpadding="2"
-!Compiler!!OS!!Processors!!Qt linkage
-|-
-|MSVC2008||Win XP SP3||2||static
-|-
-|MSVC2008||Win XP SP3||1||static
-|-
-|MSVC2008||Win 7 64bit||1||dynamic
-|-
-|MSVC2010||Win XP SP3||1||static
-|-
-|MSVC2010||Win XP SP3||1||dynamic
-|-
-|MinGW > 4||Win XP SP3||1||static
-|-
-|MinGW > 4||Win XP SP3||1||dynamic
-|-
-|C++ Builder 2010*||Win XP SP3||2||n/a
-|}
-<nowiki>*</nowiki>In version 3, the Operator module cannot be built with Borland C++ Builder (BCB). For the test, an MSVC-compiled Operator module was used in conjunction with BCB-compiled core modules.
-==Status on other OSes==
-===OS X===
-BCI2000 builds successfully in OS X Leopard and Snow Leopard using the CMake generating script at <tt>build/Make Xcode Project.sh</tt>. Note that the Qt libraries provided in the BCI2000 source tree are for Windows only, so you need to separately install Qt on your OS X system.
-Using the BCI2000Launcher, the online system can be started up and runs. This works fine when Qt 4.5 is installed on the machine. With Qt 4.7.3, core modules run but have a high CPU usage, and don't quit when the Operator module is shut down. It appears that QCoreApplication::hasPendingEvents() always returns true, such that core modules always try to process messages. It is not clear whether this is a bug in Qt, or a problem on the BCI2000 side.
 ==See also==
-[[Programming Reference:Building Qt for BCI2000]], [[Programming Reference:Building BCI2000 for Win64]]
+[[Programming Reference:Building Qt for BCI2000]]
 [[Category:Framework API]][[Category:Development]]