From 3e5bee2b723dc49b2133f6f6a38e1db19c5b3bcc Mon Sep 17 00:00:00 2001 From: "Kenneth Benzie (Benie)" Date: Mon, 21 Jul 2025 11:43:37 +0100 Subject: [PATCH] [Offload] Expand documentation with & build guide This patch introduces essential information to the landing page of the Sphinx documentation: * Copy and translate the contents of `offload/README.md` as the project summary section * Document how to configure CMake and build the project * Document running tests * Document building the Sphinx documentation --- offload/docs/index.rst | 98 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 92 insertions(+), 6 deletions(-) diff --git a/offload/docs/index.rst b/offload/docs/index.rst index 481d1f7ddd8b8..11f7f89a59f11 100644 --- a/offload/docs/index.rst +++ b/offload/docs/index.rst @@ -1,17 +1,103 @@ -.. Offload documentation master file, created by - sphinx-quickstart on Fri Jul 4 14:59:13 2025. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Welcome to Offload's documentation! =================================== .. toctree:: :maxdepth: 2 - :caption: Contents: + :hidden: offload-api +Summary +------- + +The Offload subproject aims at providing tooling, runtimes, and APIs that allow +users to execute code on accelerators or other "co-processors" that may or may +not match the architecture of their "host". In the long run, all kinds of +targets are in scope of this effort, including but not limited to: CPUs, GPUs, +FPGAs, AI/ML accelerators, distributed resources, etc. + +For OpenMP offload users, the project is ready and fully usable. The final API +design is still under development. More content will show up here and on our +webpage soon. In the meantime, people are encouraged to participate in our +meetings (see below) and check our `development board +`_ as well as the discussions on +`Discourse `_. + +Meetings +-------- + +Every second Wednesday, 7:00 - 8:00am PT, starting Jan 24, 2024. Alternates +with the OpenMP in LLVM meeting. `invite.ics +`_ +`Meeting Minutes and Agenda +`_. + + +Building +-------- + +A minimal Linux build CMake configuration: + +.. code-block:: console + + $ cmake llvm -Bbuild \ + -DCMAKE_BUILD_TYPE=Release \ + -DLLVM_ENABLE_PROJECTS='clang;clang-tools-extra;lldb;lld' \ + -DLLVM_ENABLE_RUNTIMES='offload;openmp' + $ cmake --build build + +* ``LLVM_ENABLE_RUNTIMES`` must include ``openmp`` as it is currently a + dependency of ``offload`` during the initial transitional phase of the + project. + +.. hint:: + + As part of the main build an `ExternalProject + `_ will be + created at ``build/runtimes/runtimes-bins`` which contains the Offload + sub-build. Additional build targets are present in the sub-build which are + not accessible in the LLVM build. + +Running Tests +^^^^^^^^^^^^^ + +There are two main check targets: + +* ``check-offload`` runs the OpenMP tests, this is available in both the LLVM + build directory as well as the runtimes-bin sub-build directory. +* ``check-offload-unit`` runs the Offload API unit test, this is only available + in the runtimes-bin sub-build directory. + +Building Documentation +^^^^^^^^^^^^^^^^^^^^^^ + +Additional CMake options are necessary to build the Sphinx documentation. +Firstly, we need to ensure the Python dependencies are available, ideally using +a virtual environment: + +.. code-block:: console + + $ python -m venv env + $ source env/bin/activate + $ pip install -r llvm/docs/requirements.txt + +Assuming we already have an existing build described above, we need to +reconfigure the Offload sub-build, this will enable the ``docs-offload-html`` +target. + +.. code-block:: console + + $ cmake runtimes -Bbuild/runtimes/runtimes-bins \ + -DLLVM_ENABLE_SPHINX=ON + $ cmake --build build + +Once the documentation is built it can be viewed on `localhost:8000 +`_ as follows: + +.. code-block:: console + + $ cd build/runtimes/runtimes-bins/offload/docs/html + $ python -m http.server Indices and tables ==================