Adapter implementations for Unified Runtime currently reside in the SYCL repository. This branch contains scripts to automatically fetch and build them directly in the UR tree. The adapters are disabled by default, see cmake options for details.
This repo contains the following:
- API specification in YaML
- API programming guide in RST
- Loader and a null adapter implementation (partially generated)
- Example applications
- API C/C++ header files (generated)
- API Python module (generated)
- Sample C++ wrapper (generated)
- Sample C/C++ import library (generated)
The recommended way to integrate this project into another is via CMake's FetchContent, for example:
include(FetchContent)
FetchContent_Declare(
unified-runtime
GIT_REPOSITORY https://github.com/oneapi-src/unified-runtime.git
GIT_TAG main # This will pull the latest changes from the main branch.
)
FetchContent_MakeAvailable(unified-runtime)
add_executable(example example.cpp)
target_link_libraries(example PUBLIC unified-runtime::headers)
Each Friday at 23:00 UTC time a prerelease
tag is created which
takes the form weekly-YYYY-MM-DD
. These tags should be used by downstream
projects which intend to track development closely but maintain a fixed point in
history to avoid pulling potentially breaking changes from the main
branch.
Tools can be acquired via instructions in third_party.
Required packages:
- C++ compiler with C++17 support
- CMake >= 3.14.0
- Python v3.6.6 or later
For development and contributions:
- clang-format-15.0 (can be installed with
python -m pip install clang-format==15.0.7
)
Generating Visual Studio Project. EXE and binaries will be in build/bin/{build_config}
$ mkdir build
$ cd build
$ cmake {path_to_source_dir} -G "Visual Studio 15 2017 Win64"
Executable and binaries will be in build/bin
$ mkdir build
$ cd build
$ cmake {path_to_source_dir}
$ make
List of options provided by CMake:
Name | Description | Values | Default |
---|---|---|---|
UR_BUILD_TESTS | Build the tests | ON/OFF | ON |
UR_BUILD_TOOLS | Build tools | ON/OFF | ON |
UR_FORMAT_CPP_STYLE | Format code style | ON/OFF | OFF |
UR_DEVELOPER_MODE | Treat warnings as errors and enables additional checks | ON/OFF | OFF |
UR_USE_ASAN | Enable AddressSanitizer | ON/OFF | OFF |
UR_USE_TSAN | Enable ThreadSanitizer | ON/OFF | OFF |
UR_USE_UBSAN | Enable UndefinedBehavior Sanitizer | ON/OFF | OFF |
UR_USE_MSAN | Enable MemorySanitizer (clang only) | ON/OFF | OFF |
UR_ENABLE_TRACING | Enable XPTI-based tracing layer | ON/OFF | OFF |
UR_CONFORMANCE_TARGET_TRIPLES | SYCL triples to build CTS device binaries for | Comma-separated list | spir64 |
UR_BUILD_ADAPTER_L0 | Fetch and use level-zero adapter from SYCL | ON/OFF | OFF |
UR_BUILD_ADAPTER_OPENCL | Fetch and use opencl adapter from SYCL | ON/OFF | OFF |
UR_BUILD_ADAPTER_CUDA | Fetch and use cuda adapter from SYCL | ON/OFF | OFF |
UR_BUILD_ADAPTER_HIP | Fetch and use hip adapter from SYCL | ON/OFF | OFF |
UR_BUILD_ADAPTER_NATIVE_CPU | Fetch and use native-cpu adapter from SYCL | ON/OFF | OFF |
UR_HIP_PLATFORM | Build hip adapter for AMD or NVIDIA platform | AMD/NVIDIA | AMD |
UR_ENABLE_COMGR | Enable comgr lib usage | AMD/NVIDIA | AMD |
UR_DPCXX | Path of the DPC++ compiler executable to build CTS device binaries | File path | "" |
UR_SYCL_LIBRARY_DIR | Path of the SYCL runtime library directory to build CTS device binaries | Directory path | "" |
To run automated code formatting, configure CMake with UR_FORMAT_CPP_STYLE
option
and then run a custom cppformat
target:
$ make cppformat
If you've made modifications to the specification, you can also run
a custom generate
target prior to building.
It will generate the source code and run automated code formatting:
$ make generate
For those who intend to make a contribution to the project please read our Contribution Guide for more information.
To maintain consistency and clarity in naming adapter libraries, it is recommended to use the following naming convention:
- On Linux platforms, use
libur_adapter_[name].so
. - On Windows platforms, use
ur_adapter_[name].dll
.
Code is generated using included Python scripts.
Documentation is generated from source code using Sphinx - see scripts dir for details.