Build - tingxingdong/clBLAS-private GitHub Wiki
Using CMake build infrastructure
Operating Systems
clBLAS is supported for Linux and Windows. MacOS is not officially supported.
CMake Overview
clBLAS does not provide Microsoft Visual Studio project files, makefiles, or any other native build infrastructure for its examples. Instead, it includes a file named CMakeLists.txt in the root directory, and uses CMake as a 'master' build system to GENERATE native build files, such as Visual Studio projects, nmake makefiles, UNIX makefiles, or Mac xcode projects.
- NOTE: CMake is very similar to the autoconf tool 'configure', except it is cross-platform and it integrates many features in addition to building. 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; the minimum required version is 2.8.
Build dependencies
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 must be compiled beforehand, with the proper environment variables declared to point to them. The build dependencies include:
OpenCL setup
Installing the AMD APP SDK installs all the header and binary files in the appropriate locations and also defines the AMDAPPSDKROOT environment variable. CMake requires only this information to find the OpenCL dependencies--on Windows or Linux. AMD APP SDK version 3.0 is recommended; version 2.9.1 also works.
Boost setup
Boost is provided in source form, and must be compiled by the user. After extracting into the desired location, run the bootstrap script to compile the build engine, and then compile the program_options module. Boost version 1.54 or later is recommended. To compile boost and set up an appropriate environment variable for CMake to subsequently locate Boost during its configure step, see the following example:
- 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
For Linux, follow similar steps, except that bootstrap is a shell script--so the environment variable would be set similar to:
- export BOOST_ROOT=/usr/local/src/boost_1_54_0
Googletest setup
Googletest is provided in source form, and needs to be compiled by the user. After extracting into the desired location, you can compile it with the provided native build files (which for Windows are very old)-- but Googletest also comes with its own set of cmakefiles. It is 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 CRTs 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 four flavors of gtest are available for cmake to discover. A directory layout like the following works well.
ACML setup
The testing tools from clBLAS 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 to. 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 then locates the appropriate ACML dependencies and compiles clBLAS. On Linux, set the LD_LIBRARY_PATH environment variable to /opt/acml5.3.1/ifort64/lib to locate the ACML .so files at runtime.
Note: After all the dependencies have been installed and built, the environment variables must contain at least the minimum set of all the environment variables circled below in red. CMake works exactly the same way for Linux.
CMake clBLAS Configuration
With all of the pre-requisite dependencies downloaded, compiled and set up, CMake automates 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 the 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 for buttons, list boxes, and search boxes (On linux, cmake-gui is typically installed in a separate 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 necessary for configuring clBLAS. In the CMake Window, enter the source code and binary URIs as given in the image below, and select 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.
Next, click the Configure button, and specify 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 is easy to start a fresh build (just delete the binaries directory). After selecting the generator, CMake examines the system, locating all the project dependencies and properties, which appear in the properties box in RED.
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 implies that 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 the "Generate" button generates the actual build files into the specified binaries directory.
Offline Kernel Compilation
clBLAS first introduced Offline Kernel Compilation in version 2.6.0. This feature enables the library to pre-compile OpenCL kernels at build time rather than run time and thus improves the overall library performance. With version 2.8.0, Offline Kernel Compilation feature is both expanded and made more flexible.
- All GEMM and DTRSM kernels can be offline compiled.
- User can choose to offline compile a specific subset of GEMM kernels.
- All kernels chosen to be offline compiled will be compiled for device 0.
For example, a CMake configuration shown in above figure will generate a clBLAS project that pre-compiles SGEMM NT kernels and still compiles other kernels at runtime, with OpenCL 2.0 compiler.
Startup projects
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 is 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.
Supported compilers
clBLAS currently compiles with Visual Studio 2012, 2013 on Windows.
For Linux, clBLAS compiles with at least 4.6 and 4.8 (others may also work, but we haven't tested them and cannot guarantee).