1. Contents of the repo
2. Integration
   • Weekly tags
3. Third-Party tools
4. Building
   • Requirements
   • Windows
   • Linux
   • CMake standard options
   • Additional make targets
5. Contributions
   • Adapter naming convention
   • Source code generation
   • Documentation
6. Release Process

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.

The requirements and instructions below are for building the project from source without any modifications. To make modifications to the specification, please see the Contribution Guide for more detailed instructions on the correct setup.

Required packages:

• C++ compiler with C++17 support
• CMake >= 3.14.0
• Python v3.6.6 or later

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:

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

This target has additional dependencies which are described in the Build Environment section of the Contribution Guide.

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.

Unified Runtime releases are aligned with oneAPI releases. Once all changes planned for a release have been accepted, the release process is defined as:

1. Create a new release branch based on the main branch taking the form v<major>.<minor>.x where x is a placeholder for the patch version. This branch will always contain the latest patch version for a given release.
2. Create a PR to increment the CMake project version on the main and merge before accepting any other changes.
3. Create a new tag based on the latest commit on the release branch taking the form v<major>.<minor>.<patch>.
4. Create a new GitHub release using the tag created in the previous step.
   • Prior to version 1.0, check the Set as a pre-release tick box.
5. Update downstream projects to utilize the release tag. If any issues arise from integration, apply any necessary hot fixes to v<major>.<minor>.x branch and go back to step 3.