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 oneAPI library dependencies are pulled in from oneAPI’s local conda channel that is installed as a part of oneAPI.

export ONEAPI_ROOT=/opt/intel/oneapi
conda build conda-recipe -c ${ONEAPI_ROOT}/conda_channel

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

set "ONEAPI_ROOT=C:\Program Files (x86)\Intel\oneAPI\"
conda build --croot=C:/tmp conda-recipe -c "%ONEAPI_ROOT%\conda_channel"

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
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:

Linux

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

Windows

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

To develop, run:

Linux

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

Windows

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

Developing can be streamlined using the driver script:

Linux

python scripts/build_locally.py --verbose

Windows

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 develop -- -G Ninja -DCMAKE_C_COMPILER:PATH=$(which clang) -DCMAKE_CXX_COMPILER:PATH=$(which clang++)

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.

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++ 2024.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_PROGRAM_CREATION=ON                   \
    -DDPCTL_BUILD_CAPI_TESTS=ON                             \
    -DDPCTL_GENERATE_COVERAGE=ON                            \
    ..

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

popd || exit 1