Requirements & Compilation

Requirements

This section lists the software requirements for building the CLIc library. If you never compiled a C++ project before, you may want to check out these tutorials before proceeding:

Otherwise, you’ll need the following software to continue:

  • Git

  • CMake (version 3.20 or higher)

  • OpenCL (usually provided by the GPU vendor)

  • Python

  • a C++ Compiler:

    • On Windows, you can install it with MSVC

    • On macOS, you can install the Xcode command line tools

    • On Linux, you can install GCC with the build-essential package.

    • Or any other compiler that supports C++17 should work.

For building the documentation, the additional library is required:

Note

Ensure that all the following software are available in your system’s $PATH variable, especially Git and CMake. Please, refer to the respective software documentation for installation instructions and usage.

Compilation

Using terminal CLI

First, clone the repository with Git:

git clone https://github.com/clEsperanto/CLIc.git
cd CLIc

We can then uses CMakes’s command-line interface to configure

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON

The parameter -S specifies the source directory, and -B specifies the build directory. -G allows you to specify your project generator like Ninja, MSVC, XCode, or other compatible with CMake. You can also configure specific variable of the project as followed -D<NAME_OF_THE_VARIABLE>=<VALUE>. In this case, we are setting the build type to Release and enabling the tests.

Once configure, we can build the project with the following command:

cmake --build build --parallel 10 --target install

This command will build the project in parallel using 10 threads and install the project in the system.

Note

By default the installation directory follows a GNU standard, which is usually /usr/local for Unix system. If you want to change the installation directory, you can set the variable CMAKE_INSTALL_PREFIX during the configuration step. This allows you to better control where the library and headers are installed.

Using CMake GUI

If you prefer a graphical interface, you can use CMake’s GUI. The logic is the same as the command-line interface, but you can set the variables in the GUI.

  1. Open CMake GUI

  2. Set the source directory to the path where you cloned the repository.

  3. Set the build directory to a path where you want to build the project.

  4. Click on Configure and select your compiler/generator.

  5. Set the variables you want to change.

  6. Click on Generate.

Once you have generated the project, you can open the project file with your IDE (this should match the compiler/generator you have selected in the GUI) and build the project.

Using VSCode

If you are using Visual Studio Code, you can use the C/C++ Extension Pack provided by Microsoft. This extension pack includes the CMake Tools extension, which allows you to configure and build the project directly from the IDE. We provided a set of presets configurations for the project that can be directly used with the CMake Tools extension. Configure the project manually or using the presets from the extension menu or the bottom action bar. Mainly you will have to specify: - The project generator (Ninja, MSVC, XCode, etc.) - The project build type (Debug, Release, etc.) - The project test type (Ctest Debug, Ctest Release, etc.)

Note

Only a minimal set of presets are provided so far, for Ninja, Makefile, and MSVC. Do not hesitate to create your own presets if needed or to provide us with new presets. They can be found in the ./cmake/presets directory of the project.

Warning

Tests cannot properly run in Release mode. If you want to run the tests, you should use the Debug mode.

Configuration options

The following options are available to configure the build:

  • BUILD_TESTS:

    Enable the build of the tests. Default is OFF.

  • BUILD_CUDA_BACKEND:

    Enable the build of the CUDA backend. Default is OFF.

  • BUILD_OPENCL_BACKEND:

    Enable the build of the OpenCL backend. Default is ON.

  • BUILD_DOCUMENTATION:

    Enable the build of the documentation. Default is ON (sphinx and doxygen required).

  • BUILD_SHARED_LIBS:

    Build the library as a shared library. Default is ON.

  • BUILD_COVERAGE:

    Enable the build of the coverage report. Default is OFF.

  • BUILD_BENCHMARKS:

    Enable the build of the benchmarks. Default is OFF (Work in Progress).

  • CMAKE_BUILD_TYPE:

    Specify the build type. Possible values are Debug, Release, RelWithDebInfo, MinSizeRel.

  • CMAKE_INSTALL_PREFIX:

    Specify the installation directory. Default is /usr/local.