Configuring, Building, and Installing

Ginkgo follows the standard CMake procedure. A default configuration of Ginkgo can be configured, build, and installed with the following three commands:

cmake -S <path-to-source-directory> -B <path-to-build-directory> [options]
cmake --build <path-to-build-directory>
cmake --install <path-to-build-directory>

Ginkgo requires both CMake 3.16+ and a C++17 compiler to be available. Each backend might have additional requirements. A full list of the requirements can be found in System Requirements.

Selecting Backends

The default configuration will try to detect and enable all available backends. Each backend can also be explicitly enabled via the following CMake options:

  • GINKGO_BUILD_REFERENCE: enable the reference backend

  • GINKGO_BUILD_OMP: enable the OpenMP backend

  • GINKGO_BUILD_CUDA: enable the CUDA backend

  • GINKGO_BUILD_HIP: enable the HIP backend

  • GINKGO_BUILD_SYCL: enable the SYCL backend

Note

It is valid to enable multiple backends, even GPU ones, at the same time, as long as the system supports those backends.

Using these, Ginkgo can be told to explicitly enable the CUDA backend and explicitly disable the OpenMP backend with the following command:

cmake -DGINKGO_BUILD_CUDA=ON -DGINKGO_BUILD_HIP=OFF -S <source> -B <build>

If any backend is explicitly enabled, the required compilers, libraries, etc. must be available on the system. In the above example, CMake must be able to find a CUDA capable compiler. This can be helped by setting the CMake option -DCMAKE_CUDA_COMPILER=/path/to/compiler. The same fix can be applied to the HIP backend. CMake will return an error, if the requirements for enabling a backend are not satisfied.

Attention

If using the SYCL backend, the CMAKE_CXX_COMPILER option must be set to a SYCL compatible compiler.

Configuration Options

Ginkgo has more options than the backend selection to configure its build. The full list of options is available in CMake Option List

Linking Ginkgo

After installing, Ginkgo may be linked against by using:

find_package(Ginkgo VERSION 1.9.0 REQUIRED)

target_link_libraries(target Ginkgo::ginkgo)

If Ginkgo can’t be found by CMake, either add the install directory to the CMake option CMAKE_PREFIX_PATH, or passing -DGinkgo_ROOT=<install-directory> to the CMake configuration of the consumer library. The default install directory is system dependent. To explicitly set this directory either provide a prefix path to the install step:

cmake --install <build-directory> --prefix <custom-install-directory>

Alternatively, the same path might be set during the configuration step:

cmake -DCMAKE_INSTALL_PREFIX=<custom-install-directory> -S <source-directory> -B <build-directory>

Advanced Topics

Details on more advanced topics can be found here: