Table of Contents
Bolt dynamically generated native build infrastructure
CMake Overview
Bolt does not provide Microsoft Visual Studio project files, makefiles, or any other native build infrastructure for its examples. Instead, the examples directory contains a file named CMakeLists.txt. Bolt uses CMake as a 'master' build system, and native build files, such as Visual Studio projects, nmake makefiles, UNIX makefiles, or Mac xcode projects are GENERATED with CMake. CMake is very similar to the autoconf tool 'configure', except that it is cross-platform.
NOTE: With CMAKE the native OS build files are GENERATED, so changes made to the native build files are overwritten the next time cmake runs.
CMake is freely available for download on the web from:
http://www.cmake.org/
OpenCL™ Dependencies
Bolt's OpenCL™ projects have a dependency on the AMD APP SDK and the AMD OpenCL™ runtime provided by the Catalyst ™ drivers. OpenCL™ is regarded as a cross-platform, vendor-neutral API and AMD is using C++ kernel template features found in the AMD OpenCL™ implementation that to date are not found in other vendor implementations. During its configuration, CMake requires an environment variable to find the root of the OpenCL™ installation. Provide this by defining the environment variable AMDAPPSDKROOT with the path to the root of the OpenCL™ SDK, typically 'C:/Program Files (x86)/AMD APP' on Windows ® 64-bit machines. This environment variable is automatically defined by the Catalyst ™ installer; so, in most circumstances, no additional work is needed. A more vendor-neutral environment variable is OPENCL_ROOT, but it is not defined by the Catalyst ™ installer.
NOTE : On Linux ® , set the environment variable by 'export OPENCL_ROOT = /opt/AMDAPP/'
CMake ships with several interfaces to help a developer generate native build files. CMake has a GUI interface called cmake-gui that incorporates the traditional point-and-click conventions of buttons, list boxes, and search boxes. For CLI-based sytems (including CMD from Windows ®), CMake has a native command-line executable (the GUI is just a wrapper around the command line). The command line executable is useful, even in Windows ®, for scripting purposes, such as might be used with automated and continuous build systems.
CMake Bolt Configuration
Once installed, the easiest interface for Linux ® or Windows ® or X-windows ® is the CMake GUI program 'cmake-gui' . The terminal applications cmake.exe and ccmake.exe (based on curses library) are easy to learn. CMake automates the creation of build environments in a cross-platform manner, generating native build files for each respective platform. When launched, it inspects the host computer and searches for all tools, SDKs, libraries, and code necessary to build the project. Once CMake-gui is launched, a configuration window appears with two text boxes on the top.
For this example, Bolt has been installed from from a .zip file on the local machine at C:/code/bolt. In this document, it is called BOLT_ROOT. Either click the 'browse source...' button, and navigate to the BOLT_ROOT/examples directory, or manually type the path into the textbox. Note that the path in the 'source code' text box contains the root-level CMakeLists.txt file for the example projects. The directory we type select for, 'Where to build the binaries:', can go anywhere on the hard drive, but should NOT be in a directory that contains source code. This makes it easy to cleanly rebuild projects by deleting the binaries directory. Each target generator (picure below) must have its own binaries directory: do not mix Visual Studio 2010 binaries with Visual Studio 2012 binaries. The advantage of out-of-source builds are numerous, and are documented in CMAKE FAQ. For example, for a debug configuration with an NMake generator, a directory such as BOLT_ROOT/examples/bin/nMakeDebug can exist. All generated build files and all the binary intermediate object files are built in this path. Generated files are kept seperat from source files in a similar concept to what Autotools does for Linux ® with configure scripts. After setting the build directory, click the 'Generate' button near the bottom of the main window. A new window appears to prompt what type of generator to use.
In the example above, 'Visual Studio 11 Win64' generator is selected. The selected build directory should be descriptive of the generator used; otherwise, it is easy to start over (delete the binaries directory). On Linux ®, choose the Unix Makefiles option as generator. After selecting the generator, CMake examines the system, finding all project dependencies and properties, which appear red in the properties box.
While CMake finishes configuring the projects, it prints messages in the output log visible in the bottom textbox within the GUI; this states that CMake found the OpenCL ™ and Bolt libraries. If not, cmake prints in red text which libraries or header files are missing. This usually means the environment variables that CMake uses to find dependencies are not set up properly (see OpenCL™ Dependencies ).
Startup projects
On Windows ® , after a successful configuration pass, the directory specified initially in the 'Where to build the binaries:' textbox contains an 'Examples.sln' file, which can be opened in the appropriate version of Visual Studio. At this point, selecting the 'Build Solution' menu item builds all the samples selected. By default, Visual Studio will have the 'ALL_BUILD' project selected as the 'Startup' project. If a particular sample must be run under a debugger, mark it 'Startup' by first right-clicking on the project, then selecting 'Set as Startup Project'. Debugging then proceeds normally.
On Linux ®, open the terminal and change the directory to the one specified initially in the 'Where to build the binaries:' Run make in that directory to build all samples. Indivisual samples can also be built by running make in the corresponding sample directory.
Supported compilers
On Windows ® , Bolt currently uses type traits introduced in Visual Studio 2010. We hope to support additional compilers at some time. On Linux ® , GCC is supported. We also hope to add MinGW support in future.
