From d367c68c73580467fcb340b9f37b51c1b58bf0da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Stolarczuk?= Date: Tue, 4 Jul 2023 17:14:52 +0200 Subject: [PATCH] [UR] Revamp README file a little - add TOC to the top-level README file, - order sections and group them together (incl. new Contrib section), - clean and unify Markdown syntax a little, - add new badges for CodeQL and Bandit, - fix main GHA badge to point to a specific ('cmake') workflow. --- README.md | 100 +++++++++++++++++++++++++++------------------- scripts/README.md | 10 ++--- 2 files changed, 63 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index b295f3c314..634bcc6ca9 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,29 @@ # Unified Runtime -[![GHA build status](https://github.com/oneapi-src/unified-runtime/actions/workflows/cmake.yml/badge.svg?branch=main)](https://github.com/oneapi-src/unified-runtime/actions) +[![Build and test](https://github.com/oneapi-src/unified-runtime/actions/workflows/cmake.yml/badge.svg)](https://github.com/oneapi-src/unified-runtime/actions/workflows/cmake.yml) +[![CodeQL](https://github.com/oneapi-src/unified-runtime/actions/workflows/codeql.yml/badge.svg)](https://github.com/oneapi-src/unified-runtime/actions/workflows/codeql.yml) +[![Bandit](https://github.com/oneapi-src/unified-runtime/actions/workflows/bandit.yml/badge.svg)](https://github.com/oneapi-src/unified-runtime/actions/workflows/bandit.yml) -> **Note** -> -> For those who intend to make a contribution to the project please read our -> [Contribution Guide](https://oneapi-src.github.io/unified-runtime/core/CONTRIB.html) -> for more information. + -## Contents +## Table of contents + +1. [Contents of the repo](#contents-of-the-repo) +2. [Integration](#integration) + - [Weekly tags](#weekly-tags) +3. [Third-Party tools](#third-party-tools) +4. [Building](#building) + - [Windows](#windows) + - [Linux](#linux) + - [CMake standard options](#cmake-standard-options) + - [Additional make targets](#additional-make-targets) +5. [Contributions](#contributions) + - [Adapter naming convention](#adapter-naming-convention) + - [Source code generation](#source-code-generation) + - [Documentation](#documentation) + + +## Contents of the repo This repo contains the following: @@ -41,7 +56,7 @@ add_executable(example example.cpp) target_link_libraries(example PUBLIC unified-runtime::headers) ``` -### Weekly Tags +### Weekly tags Each Friday at 23:00 UTC time a [prerelease tag](https://github.com/oneapi-src/unified-runtime/releases) is created which @@ -49,15 +64,7 @@ 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. -## Source Code Generation - -Code is generated using included [Python scripts](/scripts/README.md). - -## Documentation - -Documentation is generated from source code using Sphinx. - -## Third-Party Tools +## Third-Party tools Tools can be acquired via instructions in [third_party](/third_party/README.md). @@ -65,31 +72,29 @@ Tools can be acquired via instructions in [third_party](/third_party/README.md). Requirements: - C++ compiler with C++17 support -- cmake >= 3.14.0 +- [CMake](https://cmake.org/) >= 3.14.0 - clang-format-15.0 (can be installed with `python -m pip install clang-format==15.0.7`) -Project is defined using [CMake](https://cmake.org/). - -**Windows**: +### Windows -Generating Visual Studio Project. EXE and binaries will be in **build/bin/{build_config}** +Generating Visual Studio Project. EXE and binaries will be in **build/bin/{build_config}** -~~~~ +```bash $ mkdir build $ cd build $ cmake {path_to_source_dir} -G "Visual Studio 15 2017 Win64" -~~~~ +``` -**Linux**: +### Linux Executable and binaries will be in **build/bin** -~~~~ +```bash $ mkdir build $ cd build $ cmake {path_to_source_dir} $ make -~~~~ +``` ### CMake standard options @@ -98,32 +103,36 @@ 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_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_BUILD_TOOLS | Build tools | ON/OFF | ON | -**General**: +### Additional make targets + +To run automated code formatting, configure CMake with `UR_FORMAT_CPP_STYLE` option +and then run a custom `cppformat` target: -To run automated code formatting build with option `UR_FORMAT_CPP_STYLE` and then run a custom `cppformat` target: -~~~~ +```bash $ make cppformat -~~~~ +``` -If you've made modifications to the specification, you can also run a custom `generate-code` or `generate` target prior to building. -This call will generate the source code: -~~~~ -$ make generate-code -~~~~ +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 call will generate the source code and run automated code formatting: -~~~~ +```bash $ make generate -~~~~ -Note: `generate` target requires `UR_FORMAT_CPP_STYLE` to bet set. +``` + +## Contributions + +For those who intend to make a contribution to the project please read our +[Contribution Guide](https://oneapi-src.github.io/unified-runtime/core/CONTRIB.html) +for more information. ### Adapter naming convention @@ -132,3 +141,12 @@ 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](/scripts/README.md). + +### Documentation + +Documentation is generated from source code using Sphinx - +see [scripts dir](/scripts/README.md) for details. diff --git a/scripts/README.md b/scripts/README.md index f7c41b445a..c51008a120 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -4,12 +4,10 @@ Python dependencies: * [PyYAML](https://pyyaml.org/) v3.13 * [Sphinx](https://www.sphinx-doc.org/en/master/) v2.2.2 -Installing Python dependencies: - ~~~~ - * Install all python requirements. - ~~~~ - python -m pip install -r ../third_party/requirements.txt - ~~~~ +To install all Python dependencies, execute: +```bash +$ python -m pip install -r ../third_party/requirements.txt +``` Documentation is generated from source code using Doxygen. * [Doxygen](http://www.doxygen.nl/) v1.8.15