## Requirements ### Software dependencies * [GLib](https://developer.gnome.org/glib/), v2.32 or higher * An [OpenCL implementation](OpenCL implementations) ### Build tools * C compiler (_cf4ocl_ has been tested with [GCC](https://gcc.gnu.org/) and [Clang](http://clang.llvm.org/)). * [CMake](http://www.cmake.org/) * [Git](http://git-scm.com/) (optional, for cloning and version checking) ### Installing the requirements The following table describes, for several OSes, the package names or binary locations of the libraries and tools used for building _cf4ocl_ from source: | Dependency / tool | Debian/Ubuntu | Fedora/CentOS | OS X1 | Windows | | ------------------ | ----------------- | -------------- | ---- | ------- | | GLib | _libglib2.0-dev_ package | _glib2-devel_ package | _glib_ [homebrew](http://brew.sh/) formula | GTK+ 3.x [32](http://www.gtk.org/download/win32.php) or/and [64](http://www.gtk.org/download/win64.php)-bit all-in-one bundles (see [Build on Windows](#buildonwindows) for installing with [MSYS2](https://msys2.github.io/)) | | OpenCL | _ocl-icd-opencl-dev_ package or [an OpenCL SDK](OpenCL implementations) | _opencl-headers_ and _ocl-icd-devel_ packages or [an OpenCL SDK](OpenCL implementations) | Included with OS | [An OpenCL SDK](OpenCL implementations) | | C compiler | _build-essential_ package | _gcc_ and _make_ packages | Install [Xcode](https://developer.apple.com/xcode/) from the app store | [MinGW](http://www.mingw.org/) and/or [MinGW-w64](http://mingw-w64.sourceforge.net/) (see [Build on Windows](#buildonwindows) for installing with [MSYS2](https://msys2.github.io/)) | | CMake | _cmake-qt-gui_ and _cmake-curse-gui_ packages | _cmake_ and _cmake-gui_ packages | [CMake OS X binaries](http://www.cmake.org/download/) | [CMake Windows binaries](http://www.cmake.org/download/) | | Git (optional) | _git_ package | _git_ package | Included with [Xcode](https://developer.apple.com/xcode/) | [Git Windows binaries](http://git-scm.com/downloads) | 1The [_cf4ocl_ Homebrew formula](http://braumeister.org/formula/cf4ocl) is the recommended approach for installing on OS X. Documentation dependencies and build options and are discussed in [another page](Build docs). ## Build from source ### Get cf4ocl If **git** is installed, clone _cf4ocl_ into your work folder: $ git clone https://github.com/FakenMC/cf4ocl.git Otherwise, [download](https://github.com/FakenMC/cf4ocl/archive/master.zip) the source code, and unzip to the desired folder. ### Configure and generate build files Run the CMake GUI. Point the source code location to the cloned or extracted folder. Specify where to build the binaries as a folder of your choice (should not be the same as the source code location; it's usually a folder named `build` inside that location). Press the 'Configure' button and specify the desired generator (e.g. Unix Makefiles, Xcode, etc.). If all goes well, CMake is able to find the required dependencies. If not, you'll have to provide this information. The remaining build options can be changed from this menu. The defaults are usually OK, but browse through them to confirm. Press 'Configure' again, and then press 'Generate'. Alternatively, use the CMake text interface, `ccmake`, or the CMake command-line interface, `cmake`. Manually create the `build` folder and `cd` into it. Then invoke `cmake` or `ccmake`, specifying the desired generator and the source code location. If you created the `build` folder inside the source code location and want to use the "Unix Makefiles" generator, `cmake` and `ccmake` would be invoked like this, respectively: $ cmake -G "Unix Makefiles" .. $ ccmake -G "Unix Makefiles" .. The `ccmake` text interface mimics the CMake GUI, and follows a similar usage pattern, but it isn't available on some systems. With `cmake`, build options must either be specified when invoking the command itself (using the `-D` option), or by specifying wizard mode with the `-i` option. ### Build cf4ocl from source If the selected generator is a command-line tool (e.g. Make or Ninja), simply invoke it within the `build` folder. For example, for the "Unix Makefiles" generator, `cd` into the build folder and run `make`. If the selected generator is a GUI program such as Eclipse or Xcode, run the program and open the generated project file located within the `build` folder. Then build the project in the usual way. At this time, and before installing _cf4ocl_, you can run the [tests](Testing), examples or utilities, which are in the `./tests`, `./src/examples` and `./src/utils` folders, respectively. If a "library not found" or similar error occurs, make sure the executables can find the _cf4ocl_ shared library and the remaining dependencies, OpenCL and Glib). For example, if using the "Unix Makefiles" generator, prepend `LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./src/cf4ocl2` to the program invocation, e.g.: $ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./src/lib/ ./src/examples/canon _cf4ocl_ can be installed to the location specified in the `CMAKE_INSTALL_PREFIX` CMake variable (which defaults to a system-wide location) by invoking the `install` target. For example, if using the "Unix Makefiles" generator, installation of _cf4ocl_ to a system-wide location can be accomplished by running the following command: $ sudo make install To make sure the _cf4ocl_ library is found by third-party code, it may be necessary to run additional commands depending on the OS. For Linux this would consist of typing the command `sudo ldconfig`, assuming _cf4ocl_ is installed system-wide; on Windows, the _cf4ocl_ DLL should be registered with `regsvr32.exe`. To uninstall _cf4ocl_ remove the files listed in the `install_manifest.txt` file which is created in the `build` folder. ## Build on Windows Windows builds of _cf4ocl_ are performed with MinGW and/or MinGW-w64. Builds with Visual Studio are not directly supported, but you're welcome to try. The generic steps for preparing your Windows installation for building _cf4ocl_ are as follows: 1. Install [MinGW](http://www.mingw.org/) and/or [MinGW-w64](http://mingw-w64.sourceforge.net/). 2. Install GTK+ 3.x [32](http://www.gtk.org/download/win32.php) or/and [64](http://www.gtk.org/download/win64.php)-bit all-in-one bundles. 3. Install [CMake](http://www.cmake.org/download/). 4. Install [Git](http://git-scm.com/downloads). 5. Make sure you have installed an OpenCL SDK which provides the OpenCL development libraries and headers, such as [AMD APP SDK](http://developer.amd.com/tools-and-sdks/opencl-zone/amd-accelerated-parallel-processing-app-sdk/). 6. Follow the instructions in the previous section, [Build from source](#buildfromsource), using the "MinGW Makefiles" generator. The first two steps are easy to get wrong. One of the simplest approaches consists of installing [MSYS2](https://msys2.github.io/), carefully following the instructions on the website, and then install GLib, the GCC toolchain, Git and other utilities from the MSYS terminal. The following commands install everything required for building, testing and installing _cf4ocl_ on 32 and 64-bits platforms: * Install GLib: `$ pacman -S mingw-w64-i686-glib2 mingw-w64-x86_64-glib2 glib2 glib2-devel` * Install MSYS and MinGW toolchains (press ENTER when requested to enter a selection): `$ pacman -S msys2-devel mingw-w64-i686-toolchain mingw-w64-x86_64-toolchain` * Install required command-line utilities: `$ pacman -S git bc grep ctags curl findutils sed gzip gawk` * Install [BATS](https://github.com/sstephenson/bats) (required for [testing](Testing) the utilities): ``` $ git clone https://github.com/sstephenson/bats.git $ cd bats $ ./install.sh /usr/local ``` For 32-bit builds, add the MinGW Win32 path (e.g., `C:\msys64\mingw32\bin`) to the Windows system path. For 64-builds add the MinGW Win64 path instead (e.g., `C:\msys64\mingw64\bin`). Use one path or another, but never both at the same time. Go to "Advanced system settings > Environment Variables > System variables > Path" in order to edit the Windows system path. With everything set up, follow the instruction in the section [Build from source](#buildfromsource) using one of the "MinGW Makefiles" generators. When configuring the build options in CMake check that the version of the specified OpenCL headers is the same or lower than the main OpenCL ICD loader (OpenCL.dll) in the system. You can download and build an ICD loader with support for the latest version of OpenCL [here](https://github.com/KhronosGroup/OpenCL-ICD-Loader). Finally, the MinGW Make tool is invoked as `mingw32-make.exe`.