CMake Support#

General Usage#

CMake is a cross-platform build system generator. It can be used to generate build scripts which can then be used to build and link your application.

oneDPLConfig.cmake and oneDPLConfigVersion.cmake are distributed with oneDPL. These files allow integration of oneDPL into user projects with the find_package command. Successful invocation of find_package(oneDPL <options>) creates imported target oneDPL that can be passed to the target_link_libraries command.

Some useful CMake variables (here you can find a full list of CMake variables for the latest version):

CMAKE_CXX_COMPILER - C++ compiler used for build: CMAKE_CXX_COMPILER=dpcpp.
CMAKE_BUILD_TYPE - build type that affects optimization level and debug options; For example: CMAKE_BUILD_TYPE=Release.
CMAKE_CXX_STANDARD - C++ standard: CMAKE_CXX_STANDARD=17.

Requirements#

The minimal supported CMake version for oneDPL is 3.11 on Linux and 3.20 on Windows.

The supported CMake Generator for Linux is Unix Makefiles (default). In the Windows environment, the supported generator is Ninja which may be specified via -GNinja as described in the CMake support documentation for the Intel® oneAPI DPC++/C++ Compiler.

oneDPL Backend Options#

Backend for Parallel Execution Policies (par and par_unseq)#

The oneDPL backend for parallel execution policies controls how algorithms with parallel execution policies (par or par_unseq) are implemented. This option is controlled via the ONEDPL_PAR_BACKEND setting.

ONEDPL_PAR_BACKEND	oneTBB	OpenMP	Serial
[not set]	oneDPL heuristics
tbb	X
openmp		X
serial			X

The oneDPL heuristics are the following: the first suitable backend is chosen among oneTBB, OpenMP and Serial, in that order. If ONEDPL_PAR_BACKEND is specified, but the selected backend is not found or unsupported, oneDPL is considered not found (oneDPL_FOUND=False).

Backend for Device Execution Policies#

The oneDPL backend for device execution policies controls if device policies are enabled.

DPCPP
oneDPL heuristics

The heuristics are the following: DPCPP backend is enabled if the compiler supports -fsycl option and SYCL headers are available.

For more details on oneDPL backends, see Execution Policies.

Example CMake File#

To use oneDPL with CMake, you must create a CMakeLists.txt file for your project and add oneDPL. This file should be placed in the project’s base directory. Below is an example CMakeLists.txt file:

if (CMAKE_HOST_WIN32)
  find_package(oneDPLWindowsIntelLLVM)
endif()

project(Foo)
add_executable(foo foo.cpp)

# Search to find oneDPL
find_package(oneDPL REQUIRED)

# Connect oneDPL to foo
target_link_libraries(foo oneDPL)

Note

On Windows, some workarounds may be required to use icx[-cl] successfully with oneDPL. We recommend updating to the most recent version of CMake to minimize the workarounds required for successful use. A CMake package has been provided, oneDPLWindowsIntelLLVM, to provide the necessary workarounds to enable support for icx[-cl] on Windows with CMake versions 3.20 and greater. Some workarounds are provided for icpx, but it is not fully supported on Windows at this time. To use this package, please add find_package(oneDPLWindowsIntelLLVM) to your CMake file before you call project().

Example CMake Invocation#

After creating a CMakeLists.txt file for your project, you may use a command line CMake invocation to generate build scripts.

Below is an example Linux CMake invocation which generates Unix makefiles for the project with the icpx compiler, oneTBB backend and Release build type:

mkdir build && cd build
cmake -DCMAKE_CXX_COMPILER=icpx -DCMAKE_BUILD_TYPE=release -DONEDPL_PAR_BACKEND=tbb ..

Below is an example Windows CMake invocation which generates Ninja build scripts (see the Requirements Section) for the project in the parent directory with the icx compiler, OpenMP backend and debug build type:

mkdir build && cd build
cmake -GNinja -DCMAKE_CXX_COMPILER=icx -DCMAKE_BUILD_TYPE=debug -DONEDPL_PAR_BACKEND=openmp ..

Both of these examples assume the starting working directory is the project’s base directory which contains CMakeLists.txt. The build scripts are generated in a newly created build directory.

Example Build Command#

Once build scripts have been generated for your desired configuration following the instruction above, a build command can be issued to build your project:

cmake --build .

This example assumes the starting working directory is in the directory which contains the CMake generated build scripts, build, if following the instructions above.

CMake Support

Contents