Build
clFFT 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. clFFT 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.
The clFFT 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
The current build scripts have been developed and tested against the AMD APP SDK. Other OpenCL SDK support should be relatively easy to add to the CMake scripts and could be contributed back into the codebase. 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.
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.
- 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 install --prefix=c:\MY_INSTALL_DIR
- setx BOOST_ROOT c:\MY_INSTALL_DIR
Linxu directions are the same, except bootstrap is a shell script and the environment variable would be set similar to By default, BOOST is installed in /user/local/
- 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 test binaries from clFFT use FFTW as the gold version to compare against. FFTW is an open-source project and for the Linux platform it is expected for the user to download the source from the FFTW download site and compile the source. Windows pre-compiled binaries are also available. Once installed, create an environment variable named FFTW_ROOT that points to where the binaries were extracted, such as F:\code\fftw-3.3.3-dll64 or /opt/fftw-3.3.3/lib64 on linux. For the windows platform, make sure to read the FFTW download page carefully, as a pre-processing step is necessary to create linkable .lib import libraries; the download package itself does not ship with them. CMake will then find all of the appropriate FFTW dependencies and compile clFFT. On Linux, the LD_LIBRARY_PATH environment variable should point to the path of the binaries, such as /opt/fftw-3.3.3/lib64 to locate the FFTW .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 clFFT source directory contains the initial CMake files necesasary for configuring clFFT. 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 clFFT 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 clFFT 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 'clFFT.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.
clFFT currently compiles with Visual Studio 2010 on Windows and has not been ported to the 2012 compilers yet. For Linux, clFFT should be compilable with any 4.6 or newer GCC compiler.