Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference

ID 767253
Date 7/13/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

Use CMake with the Compiler

Linux

Using CMake with the compiler on Linux is supported. When you are using CMake, the compiler is enabled using the icx (variant) binary. You may need to set your CC/CXX or CMAKE_C_COMPILER /CMAKE_CXX_COMPILER string to icx/icpx. For example:

cmake -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx …

Windows

Using CMake with the compiler on Windows is supported. When you are using CMake, the compiler is enabled using the icx (variant) binary. You may need to set your CC/CXX or CMAKE_C_COMPILER /CMAKE_CXX_COMPILER string to icx. The supported generator in the Windows environment is Ninja. For example:

cmake -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icx -GNinja … 

NOTE:

If your Microsoft Visual Studio default CMake version is older than 3.23.0, you need to install CMake 3.23 (or above) and update Microsoft Visual Studio with the new CMake executable. Edit the CMakeSettings.json file for this update. Windows projects that do not rely on pre-compiled headers can use 3.21.0 or later, and all others should use 3.23.0 on Windows. Linux works with CMake 3.20.5 and later.

Support to GNU-like compiler drivers (icx-cc, icpx) on Windows is being added to CMake and requires a newer version of CMake. Additional information will be provided in future versions of the compiler.

Enable the Compiler

There are two ways to enable compiler for your project. IntelSYCLConfig and IntelDPCPPConfig. We recommend using IntelSYCLConfig approach as it is compatible with de-facto Industry standard and possibility of deprecation of IntelDPCPPConfig in the future.

IntelSYCLConfig

Use the following steps to enable the SYCL compiler for your project.

  1. Add the following snippets to your project’s CMakeLists.txt:
    1. Minimum CMake version check:
      if (CMAKE_HOST_WIN32)
      # need CMake 3.25.0+ for IntelLLVM support of target link properties on Windows
      cmake_minimum_required(VERSION 3.25)
      else()
      # CMake 3.20.5 is the minimum recommended for IntelLLVM on Linux
      cmake_minimum_required(VERSION 3.20.5)
      endif()
    2. Add IntelSYCLConfig package to the project after project() is defined:
      find_package(IntelSYCL REQUIRED)

      This imports the heterogeneous compilation configuration package (IntelSYCLConfig.cmake), which is shipped with the compiler. The package directory is found in the parent directory of the icx bin directory.

    3. Add the sources that require SYCL support to add_sycl_to_target(). Not specifying any sources to add_sycl_to_target() adds SYCL compilation to all sources which may affect compilation time significantly:
      add_executable(target_proj A.cpp B.cpp offload1.cpp offload2.cpp)
      add_sycl_to_target(TARGET target_proj SOURCES offload1.cpp offload2.cpp)
  2. Select the appropriate compilers for C or C++. See the Linux and Windows sections above for specific settings.
  3. Run CMake and build your applications as normal.

IntelDPCPPConfig

Use the following steps to enable the DPC++ compiler for your project:

  1. Add the following snippets to your project’s CMakeLists.txt:

    cmake_minimum_required(VERSION 3.23.0)

    And:

    find_package(IntelDPCPP REQUIRED)

    The second snippet enables the compiler. The heterogeneous compilation configuration package (IntelDPCPPConfig.cmake) is shipped with the compiler. The package directory is found in the parent directory of the icx bin directory.

  2. Select the appropriate compilers for C or C++. See the Linux and Windows sections above for specific settings.
  3. Run CMake and build your applications as normal.
  4. The heterogeneous compilation configuration package exposes other variables that may be required. Refer to the package for more information.

Build and Run

CMake is supported on the Windows and Linux command line. The following CMakeLists.txt builds the SYCL application in simple.cpp for either Windows or Linux with the minimum supported CMake version for each platform. The following examples use SYCL:

if (CMAKE_HOST_WIN32)
    # need at least CMake 3.23 for IntelLLVM support of IntelSYCL package on Windows
    cmake_minimum_required(VERSION 3.23)
else()
    # CMake 3.20.5 is the minimum recommended for IntelLLVM on Linux
    cmake_minimum_required(VERSION 3.20.5)
endif()

project(simple-sycl LANGUAGES CXX)

find_package(IntelSYCL REQUIRED)

add_executable(simple simple.cpp)
add_sycl_to_target(TARGET simple  SOURCES simple.cpp )

The minimum required CMake version for Linux is 3.20.5. For Windows the minimum required version is 3.23.0. The project CMake directive tells CMake the name of this project and that it uses C++. Projects that also use C, Fortran, or other languages can list the languages used them in the LANGUAGES parameter.

NOTE:
Applications not using pre-compiled header files might work with CMake 3.21.0 on Windows.

The find_package directive, tells CMake to use the IntelSYCL module distributed with the oneAPI distribution. IntelSYCL is in CMake's search path after running setvars.sh on Linux or setvars.bat on Windows. The IntelSYCL module sets the compiler and linker flags required to build a project with SYCL.

The add_executable directive tells CMake which source files to use to build the simple application.

An example simple.cpp that works with the above CMakeLists.txt is:

#include <iostream>
#include <CL/sycl.hpp>
#include <cmath>

int main(int argc, char* argv[])
{
    sycl::queue queue;

    std::cout << "Using "
        << queue.get_device().get_info<sycl::info::device::name>()
        << std::endl;

    // Compute the first n_items values in a well known sequence
    constexpr int n_items = 16;
    int *items = sycl::malloc_shared<int>(n_items, queue);
    queue.parallel_for(sycl::range<1>(n_items), [items] (sycl::id<1> i) {
        double x1 = pow((1.0 + sqrt(5.0))/2, i);
        double x2 = pow((1.0 - sqrt(5.0))/2, i);
        items[i] = round((x1 - x2)/sqrt(5));
    }).wait();

    for(int i = 0 ; i < n_items ; ++i) {
        std::cout << items[i] << std::endl;
    }
    free(items, queue);

    return 0;
}

To build and run the simple application, put the CMakeLists.txt and simple.cpp in the same directory. Build the application in a subdirectory of the project using the appropriate compiler for your platform.

Linux

mkdir build
cd build
cmake -G Ninja -DCMAKE_CXX_COMPILER=icpx ..
cmake --build .
./simple

Windows

mkdir build
cd build
cmake -G Ninja -DCMAKE_CXX_COMPILER=icx ..
cmake –build .
.\simple.exe

The Linux Makefile generator is known to work with Intel oneAPI compilers and CMake. Other build generators may work, but have not been thoroughly tested.