Build
clBLAS is supported for Linux and Windows. MacOS is not officially supported.
clBLAS does not provide Microsoft Visual Studio project files, makefiles, or any other native build infrastructure for its examples. Instead, the root directory contains a file named CMakeLists.txt. clBLAS 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 it is cross-platform and it integrates many features in addition to building.
- 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; minimum required version is 2.8.
Historically clBLAS does not support offline kernel compilation. In other words, the OpenCL kernels are generated at runtime based on parameters passed into the library. This work flow has provided clBLAS with great flexibility across different platforms, drivers and hardware. However, the overhead of online compilation calling clBuildProgram() has become a bottleneck for many use cases of the library. In this regard, the offline compilation is added as a new feature to clBLAS.
Currently, only a subset of GEMM and TRSM in three trageted devices (Hawaii, Tahiti and Bonaire) supports offline compilation. This offline compilation has been tested on both Windows and Linux systems.
By default, offline compilation is disabled. The offline compilation can be enabled from CMake.
- By selecting "OCL_OFFLINE_BUILD_HAWAII_KERNEL", the static kernels shipped with the library will be compiled for Hawaii device during the library compilation. similarly, the static kernels can be compiled for Tahiti and Bonaire.
- The users are allowed to choose more than one devices for offline compilation. Note this might result in "running out of heap memory" with certain driver. Offline compiling the kernels for 1 target device at a time is recommended.
- User may supply path to OpenCL compiler by "OCL_COMPILER_DIR". If "OCL_COMPILER_DIR" is not specified, the default compiler in the system will be used.
The clBLAS library itself contains only one build dependency, but the included test and benchmark programs require several others. CMake makes it easy to manage dependencies, but they need to be compiled beforehand and proper environment variables declared to point to them. The build dependencies include
Installing the AMD APP SDK will install all the header and binary files in appropriate locations and will even define the AMDAPPSDKROOT environment variable for you. This should be all that is needed for CMake to find it's OpenCL dependencies. This is true across Windows/Linux. AMD APP SDK version 3.0 is recommended (2.9.1 also works).
Boost is provided in source form, and needs to be compiled by the user. After extracting into the desired location, the bootstrap script is run to compile the build engine, and then the program_options module should be compiled. The following steps provide an example of compiling boost and setting up an appropriate environment variable for CMake to subsequently be able to find Boost during its configure step. Boost version 1.54 or later recommended.
- pushd c:\code\boost_1_54_0
- bootstrap.bat
- b2 -j 4 --with-program_options address-model=64 toolset=msvc-10.0 link=static stage
- setx BOOST_ROOT c:\code\boost_1_54_0
Linxu directions are the same, except bootstrap is a shell script and the environment variable would be set similar to
- export BOOST_ROOT=/usr/local/src/boost_1_54_0
Googletest is provided in source form, and needs to be compiled by the user. After extracting into the desired location, the user has the option of compiling with the provided native build files (which for windows are very old), but googletest also comes with it's own set of cmakefiles. It's recommended to use the cmakefile to generate the googletest binaries, especially for the modern visual studio versions. These directions are the same across Windows and Linux. When configuring gtest, it is also recommended to change gtest_force_shared_crt to ON, to reduce problems associated with multiple CRT's linked into a single application. Unfortunately, the gtest cmake files do not define an 'INSTALL' target, so it is necessary to build the gtest binaries first and then copy them in a convenient format for googletest to find, such as in the picture below. It is also convenient to go ahead and build both 64 and 32 bit libraries, with release/debug builds such that 4 flavors of gtest are available for cmake to discover. A directory layout like below works well.
The testing tools from clBLAS will use ACML as a gold version to compare against. It is recommended to download the ifort compiled version of ACML, run its installer and pick a suitable location to extract it too. Once installed, create an environment variable named ACML_ROOT (note the picture incorrectly says ACMLROOT) that points to the the flavor of ACML that you would like to use, such as c:\code\acml5.3.1\ifort64 or /opt/acml5.3.1/ifort64 on linux. CMake will then find all of the appropriate ACML dependencies and compile clBLAS. On Linux, it helps to set the LD_LIBRARY_PATH environment variable to /opt/acml5.3.1/ifort64/lib to locate the ACML .so files at runtime.
After all the dependencies have been installed and built, the environment variables should contain at least the minimum set of all the environment variables circled in red below. CMake works exactly the same way for linux.
With all of the pre-requisite dependencies downloaded, compiled and setup, cmake is the tool to automate the creation of build environments in a cross-platform manner, generating native build files for a respective platform. When launched, it inspects the host computer and searches for all tools, SDKs, libraries, and code necessary to build the project.
CMake ships with several interfaces to help a developer generate native build files. For X/Windows based systems, CMake has a GUI interface called CMake-gui that incorporates the traditional point-and-click conventions of buttons, list boxes, and search boxes (On linux, cmake-gui is typically installed in a seperate package from cmake; search for cmake-gui using the package managers search mechanism). For CLI-based functionality (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 for scripting purposes, such as might be used with automated and continuous build systems.
The clBLAS source directory contains the initial CMake files necesasary for configuring clBLAS. In the CMake Window, enter the source code and binary URIs as given in the image below and press Configure. You can also use the 'Browse Source ...' and "Browse Build..." buttons to navigate to the source root and binary folder. It is recommended to create subdirectories for both the branch being built and the compiler being used.
As you can see from the filesystem layout, the binary files are built outside of the source code tree. The /bin directory is a sister directory to the clBLAS source directory, not a subdirectory.
Then, click on the Configure button. This will ask you for your choice of generator. In this example, 'Visual Studio 10 Win64' generator is selected, which generates a build tree for 64bit AMD64 executables.
The selected bin directory is descriptive of the generator used, and is convenient to have generated outside of the source tree because it's easy to start a fresh build (just delete the binaries directory). After selecting the generator, CMake examines the system, finding all the 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 clBLAS 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. After the configure button confirms that it can find all dependencies without error, clicking on the generate button will generate the actual build files into the binaries directory specified.
After a successful configuration pass, the directory specified initially in the 'Where to build the binaries:' textbox contains an 'clBLAS.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 generated projects. By default, Visual Studio will have the 'ALL_BUILD' project selected as the 'Startup' project. If a particular project must be run under a debugger (such as a test program), mark it 'Startup' by first right-clicking on the project, then selecting 'Set as Startup Project'. Then it's possible to hit the debug arrow in visual studio or hit the F10 key to single step into the test and the test framework will be under the control of the debugger.
clBLAS currently compiles with Visual Studio 2012, 2013 on Windows. For Linux, clBLAS can be compilable with at least 4.6 and 4.8 (others may also work, but we haven't tested them and cannot guarantee).