Building from the Source

To build dpctl from the source, you need DPC++ compiler. To run examples and test suite you would need GPU drivers and/or CPU OpenCL drivers. It is preferable to use the Intel(R) oneAPI DPC++ compiler available as part of oneAPI Base-Kit. However, it is possible to use a custom build of DPC++ to build dpctl, especially if you want to enable CUDA support or try latest features.

Building using oneAPI DPC++

Prerequisites

Install oneAPI and graphics drivers according to your targeted hardware:

  • To target Intel GPUs, see the Installation Page of the Intel(R) software for general purpose GPU capabilities document for driver information.

  • To target NVIDIA* or AMD* GPUs, see the vendor website for drivers, as well as CodePlay plugins to enable hardware targeting.

  • To target a CPU, the OpenCL* CPU driver is included as a part of the oneAPI DPC++ Compiler installation. The CPU driver is also packaged in conda, and is automatically made available using conda activation scripts on Linux*, and on Windows* (in user-mode). If conda is used with elevated privileges in Windows (similar to GitHub Actions CI), a PowerShell script must be run:

    &$Env:CONDA_PREFIX\Scripts\script_name.ps1

Use the script set-intel-ocl-icd-registry.ps1 to set appropriate registry key, and unset-intel-ocl-icd-registry.ps1 to remove it.

Activate oneAPI

On Linux OS

source ${ONEAPI_ROOT}/setvars.sh

On Windows OS

call "%ONEAPI_ROOT%\setvars.bat"

Build and Install Using Conda-Build

You can use the conda-recipe included with the sources to build the dpctl package. The advantage of this approach is that all dependencies are pulled in from the conda-forge channel.

conda build conda-recipe -c conda-forge --override-channels

On Windows OS to cope with long file names, use croot with a short folder path:

conda build --croot=C:/tmp conda-recipe -c conda-forge --override-channels

After building the Conda package, install it by executing:

conda install dpctl

Build and Install with scikit-build

To build using Python setuptools and scikit-build, install the following Python packages:

  • cython

  • numpy

  • cmake

  • scikit-build

  • ninja

  • versioneer

  • gtest (optional to run C API tests)

  • gmock (optional to run C API tests)

  • pytest (optional to run Python API tests)

Once the prerequisites are installed, building using scikit-build involves the usual steps.

To build and install, run:

python setup.py install -- -G Ninja -DCMAKE_C_COMPILER:PATH=icx -DCMAKE_CXX_COMPILER:PATH=icpx

python setup.py install -- -G Ninja -DCMAKE_C_COMPILER:PATH=icx -DCMAKE_CXX_COMPILER:PATH=icx

To develop, run:

python setup.py build_ext --inplace -G Ninja -DCMAKE_C_COMPILER:PATH=icx -DCMAKE_CXX_COMPILER:PATH=icpx
python -m pip install -e .

python setup.py build_ext --inplace -G Ninja -DCMAKE_C_COMPILER:PATH=icx -DCMAKE_CXX_COMPILER:PATH=icx
python -m pip install -e .

Developing can be streamlined using the driver script:

python scripts/build_locally.py --verbose

python scripts/build_locally.py --verbose

Building Using Custom DPC++

You can build dpctl from the source using the DPC++ toolchain instead of the DPC++ compiler that comes with oneAPI.

Following steps in the Build and install with scikit-build use a command-line option to set the relevant CMake variables, for example:

python setup.py build_ext --inplace -G Ninja -DCMAKE_C_COMPILER:PATH=$(which clang) -DCMAKE_CXX_COMPILER:PATH=$(which clang++)
python -m pip install -e .

Or you can use the driver script:

python scripts/build_locally.py --c-compiler=$(which clang) --cxx-compiler=$(which clang++)

You can retrieve available options and their descriptions using the option --help.

Runtime loaders when using a nightly DPC++ build

dpctl creates kernel bundles from OpenCL* source and from SPIR-V by calling into the OpenCL ICD loader and the Level Zero loader directly.

The oneAPI DPC++ Compiler installation and the conda packages provide these loaders as dependencies. Nightly builds of the open source DPC++ toolchain, however, bundle neither, so they must be installed separately:

  • libOpenCL.so.1, from the OpenCL ICD loader (for example, ocl-icd conda package or ocl-icd-libopencl1 system package)

  • libze_loader.so.1, from the Level Zero loader (for example, the level-zero conda package or the libze1 system package)

Both can be installed from the toolchain’s own dependencies. The DPC++ toolchain pins them in devops/dependencies.json, as the level_zero and oclcpu entries.

Should a loader be installed under a different file name, override the name that dpctl uses with the LIBCL_SET_LOADER_FILENAME and LIBZE_SET_LOADER_FILENAME CMake variables.

Building the libsyclinterface Library

The libsyclinterface is a shared library used by the Python package. To build the library, you need:

  • DPC++ toolchain

  • cmake

  • ninja or make

  • Optionally gtest 1.10 if you want to build and run the test suite

For example, on Linux OS the following script can be used to build the C oneAPI library.

#!/bin/bash
set +xe
rm -rf build
mkdir build
pushd build || exit 1

INSTALL_PREFIX=$(pwd)/../install
rm -rf "${INSTALL_PREFIX}"
export ONEAPI_ROOT=/opt/intel/oneapi
# Values are set as appropriate for oneAPI DPC++ 2026.0
# or later.
DPCPP_ROOT=${ONEAPI_ROOT}/compiler/latest/

# Set these to ensure that cmake can find llvm-cov and
# other utilities
LLVM_TOOLS_HOME=${DPCPP_ROOT}/bin/compiler
PATH=$PATH:${DPCPP_ROOT}/bin/compiler

cmake                                                       \
    -DCMAKE_BUILD_TYPE=Debug                                \
    -DCMAKE_C_COMPILER=icx                                  \
    -DCMAKE_CXX_COMPILER=icpx                               \
    -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX}                \
    -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX}                   \
    -DDPCTL_ENABLE_L0_KERNEL_BUNDLE_CREATION=ON             \
    -DDPCTL_BUILD_CAPI_TESTS=ON                             \
    -DDPCTL_GENERATE_COVERAGE=ON                            \
    ..

make V=1 -n -j 4 && make check && make install

popd || exit 1