GitHub - oneapi-src/unified-runtime (original) (raw)

Unified Runtime

Table of contents

• Unified Runtime
  • Table of contents
  • Contents of the repo
  • Integration
    * Weekly tags
  • Third-Party tools
  • Building
    * Requirements
    * Windows
    * Linux
    * CMake standard options
    * Additional make targets
  • Contributions
    * Adapter naming convention
    * Source code generation
    * Documentation
  • Release Process

Contents of the project

This project 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)

Integration

The recommended way to integrate this project into another is via CMake'sFetchContent, 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)

Third-Party tools

The recommended method to install the third-party tools is using a Python virtual environment, for example:

$ python -m venv .venv $ source .venv/bin/activate $ pip install -r third_party/requirements.txt

Building

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

Requirements

Required packages:

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

Windows

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"

Linux

Executable and binaries will be in build/bin

$ mkdir build $ cd build $ cmake {path_to_source_dir} $ make

CMake standard options

List of options provided by CMake:

Testing

Unified Runtime uses lit and FileCheck as part of its test suite. When built as part of an LLVM build, the binaries provided by LLVM will be used. When built standalone, both lit and FileCheck (or filecheck) must be visible on $PATH. The easiest way to do this is to install the Python packages for lit and filecheck.

$ source .venv/bin/activate $ pip install -r third_party/requirements_testing.txt

Note: filecheck requires Python >= 3.10; if you get errors claiming that filecheck is not available, update your Python version or disable testing.

Once installed, tests can be executed using:

Additional make targets

To run automated code formatting, configure CMake with UR_FORMAT_CPP_STYLE option and then run a custom cppformat target:

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:

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

Contributions

For those who intend to make a contribution to the project please read ourContribution Guidefor more information.

Adapter naming convention

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.

Source code generation

Code is generated using included Python scripts.

Documentation

Documentation is generated from source code using Sphinx - see scripts dir for details.