diff --git a/README.md b/README.md index ad0c629555..d97848ecc4 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,12 @@ Tools can be acquired via instructions in [third_party](/third_party/README.md). ## Building +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](https://oneapi-src.github.io/unified-runtime/core/CONTRIB.html) +for more detailed instructions on the correct setup. + ### Requirements Required packages: @@ -79,9 +85,6 @@ Required packages: - [CMake](https://cmake.org/) >= 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`) - ### Windows Generating Visual Studio Project. EXE and binaries will be in **build/bin/{build_config}** @@ -137,6 +140,10 @@ 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](https://oneapi-src.github.io/unified-runtime/core/CONTRIB.html). + ## Contributions For those who intend to make a contribution to the project please read our diff --git a/scripts/core/CONTRIB.rst b/scripts/core/CONTRIB.rst index 137f190b31..3264422c45 100644 --- a/scripts/core/CONTRIB.rst +++ b/scripts/core/CONTRIB.rst @@ -39,6 +39,62 @@ accepted into the project. Runtime team via the `GitHub issue tracker `_. +Build Environment +================= + +To be able to generate the source from the YAML files, the build environment +must be configured correctly and all dependencies must be installed. The +instructions for a basic setup are available in the `README +`_. + +The following additional dependencies are required to support the ``generate`` +target: + +* Doxygen (>= 1.8) + +* The Python script requirements listed in `thirdparty/requirements.txt`_ + +Doxygen can be installed via your system's package manager, e.g. on Ubuntu +``sudo apt install doxygen``, or by downloading it from the Doxygen website. It +must be available on the current ``PATH`` when the script is run. + +One way to install the requirements for the script is using a Python virtual +environment. This can be set up by running the following commands from the +project root: + +.. code-block:: console + + $ python3 -m venv .local + $ source .local/bin/activate + $ pip install -r third_party/requirements.txt + +The virtual environment can be subsequently reactivated before any builds +without needing to reinstall the requirements: + +.. code-block:: console + + $ source .local/bin/activate + +Alternatively, a Docker container can be used instead of a virtual environment. +Instructions on building and using a Docker image can be found in +`.github/docker`_ + +You *must* also enable the ``UR_FORMAT_CPP_STYLE`` CMake option to allow +formatting of the generated code, or the ``generate`` target will not be +available. + +.. code-block:: console + + $ cmake build/ -DUR_FORMAT_CPP_STYLE=ON + +You can then follow the instructions below to use the ``generate`` target to +regenerate the source. + +.. _thirdparty/requirements.txt: + https://github.com/oneapi-src/unified-runtime/blob/main/third_party/requirements.txt +.. _.github/docker: + https://github.com/oneapi-src/unified-runtime/blob/main/.github/docker + Generating Source ================= @@ -46,10 +102,9 @@ The specification and many other components in the Unified Runtime repository are generated from a set of YAML_ files which are used as inputs to a Mako_ based templating system. The YAML file syntax is defined in `YAML syntax`_. To generate the outputs of the Mako templates a build directory must be -configured, instructions are available in the `README -`_ file. -Upon successfully configuring a build directory, generate the outputs with the -following command (or suitable build system equivalent): +configured as detailed above. Upon successfully configuring a build directory, +generate the outputs with the following command (or suitable build system +equivalent): .. code-block:: console