Minor fixes to guides, ready for release.

uxlfoundation · Jul 16, 2024 · efa1aac · efa1aac
1 parent fa0f1a3
commit efa1aac
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 28 deletions.
diff --git a/doc/developer-guide.md b/doc/developer-guide.md
@@ -414,10 +414,12 @@ cmake llvm -GNinja \
   -Bbuild-x86_64 \
   -DCMAKE_BUILD_TYPE=Release \
   -DCMAKE_INSTALL_PREFIX=$PWD/build-x86_64/install \
-  -DLLVM_ENABLE_PROJECTS=clang \
-  -DLLVM_TARGETS_TO_BUILD='X86;ARM;AArch64'
+  -DLLVM_ENABLE_PROJECTS=clang;lld \
+  -DLLVM_TARGETS_TO_BUILD='X86;ARM;AArch64;RISCV'
 ```
 
+Note that some of the above LLVM targets could be dropped depending on the target architecture. `lld` is only needed for most non "host" targets e.g. `refsi`.
+
 Now the build directory is configured, build the `install` target.
 
 ```sh
@@ -428,18 +430,15 @@ ninja -C build-x86_64 install
 
 Configure the build directory with CMake, ensuring to enable the `clang`
 project using `LLVM_ENABLE_PROJECTS`. Run this command from the root of the
-repository. The `LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN` variable is needed when
-building LLVM version 8.0 or later on Visual Studio toolchains prior to MSVC
-version 19.1.
+repository.
 
 ```bat
-cmake llvm -G"Visual Studio 15 2017 Win64" ^
+cmake llvm -G"Visual Studio 16 2019 Win64" ^
   -Bbuild-x86_64 ^
   -DCMAKE_BUILD_TYPE=Release ^
   -DCMAKE_INSTALL_PREFIX=%CD%\build-x86_64\install ^
   -DLLVM_TARGETS_TO_BUILD="X86;ARM;AArch64" ^
   -DLLVM_ENABLE_PROJECTS=clang ^
-  -DLLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN=ON
 ```
 
 > Note that using the Ninja generator, `-GNinja`, on Windows may be preferable
@@ -515,6 +514,9 @@ cmake . -GNinja \
   -DCA_LLVM_INSTALL_DIR=$LLVMInstall
 ```
 
+This will build a `host` target, which will run device code on the same machine
+that the oneAPI Construction Kit runs on.
+
 Now the build directory is configured, build the `install` target.
 
 ```sh
@@ -547,23 +549,23 @@ cmake . -GNinja \
 ```
 
 Now the build directory is configured, you can build the oneAPI Construction Kit
-and run the dchecks as above.
+and run the checks as above.
 
 #### Compiling oneAPI Construction Kit on Windows
 
 To configure a oneAPI Construction Kit build run the following command from the
 root of the oneAPI Construction Kit repository.
 
 ```bat
-cmake . -G"Visual Studio 15 2017 Win64" ^
+cmake . -GNinja ^
   -Bbuild-x86_64 ^
   -DCMAKE_BUILD_TYPE=Release ^
   -DCMAKE_INSTALL_PREFIX=%CD%\build-x86_64\install ^
   -DCA_LLVM_INSTALL_DIR=%LLVMInstall%
 ```
 
-> Note that using the Ninja generator, `-GNinja`, on Windows may be preferable
-> for improve compilation times.
+> Note that `Ninja` is recommended as the generator for Windows. We do not currently
+> support multi-configuration generators such as the Visual Studio generators.
 
 Now the build directory is configured, build the `install` target. This can be
 done by opening the `ComputeAorta.sln` solution in Visual Studio and building
@@ -591,7 +593,7 @@ point to a Release install of LLVM, here `%LLVMReleaseInstall%` specifies the
 path to the root of the install.
 
 ```bat
-cmake . -G"Visual Studio 15 2017 Win64" ^
+cmake . -GNinja ^
   -Bbuild-x86_64-Debug ^
   -DCMAKE_BUILD_TYPE=Debug ^
   -DCMAKE_INSTALL_PREFIX=%CD%\build-x86_64-Debug\install ^
@@ -656,7 +658,7 @@ The configure the oneAPI Construction Kit build without LLVM run the following
 command from the root of the oneAPI Construction Kit repository.
 
 ```bat
-cmake . -G"Visual Studio 15 2017 Win64" ^
+cmake . -GNinja ^
   -Bbuild-offline ^
   -DCMAKE_BUILD_TYPE=Release ^
   -DCMAKE_INSTALL_PREFIX=%CD%\build-offline\install ^
@@ -665,10 +667,7 @@ cmake . -G"Visual Studio 15 2017 Win64" ^
   -DCA_ENABLE_API=cl
 ```
 
-Now the build directory is configured, build the `install` target. This can be
-done by opening the `ComputeAorta.sln` solution in Visual Studio and building
-the `install` target via the GUI for a Release configuration. Alternatively we
-can build on the command line using CMake as shown below.
+We can build on the command line using CMake as shown below.
 
 ```bat
 cmake --build %CD%\build-offline --target install --config Release
@@ -703,6 +702,8 @@ cmake --build %CD%\build-offline --target install --config Release
 > POSIX threads. The `choco` command is
 > `choco install mingw -y -params "/exception:seh /threads:posix"`.
 
+Note that this is not part of the regular testing of OCK, but should work.
+
 ## Cross-compiling
 
 > Note: Cross-compilation is only supported on Linux.
@@ -884,6 +885,8 @@ cmake -GNinja \
 cmake --build build-mingw --target ComputeAorta
 ```
 
+Note that approach is not tested and is not guaranteed to work.
+
 ## Testing
 
 <!-- TODO: Document gtest suites -->

diff --git a/doc/getting-started.rst b/doc/getting-started.rst
@@ -9,6 +9,7 @@ build the oneAPI Construction Kit.
 
 * `Ubuntu 20.04`_
 * `Ubuntu 22.04`_
+* `Ubuntu 24.04`_
 * `Windows 10`_
 
 Once the platform dependencies have been installed please read the
@@ -37,7 +38,7 @@ Recommended for Ubuntu 20.04
 
 * `Ninja`_ is a useful, fast, build tool. To use it pass ``-GNinja`` to
   `CMake`_ the first time it configures a build directory.
-* `clang-format`_ 16 is a tool to format
+* `clang-format`_ 17 is a tool to format
   C/C++/Java/JavaScript/Objective-C/Protobuf code. All oneAPI Construction
   Kit source files are required to be formatted before being committed to
   the repository, including source files which are generated by the build.
@@ -97,15 +98,25 @@ Install the AArch64 toolchain.
 Ubuntu 22.04
 ------------
 
-Support for Ubuntu 22.04 is still experimental.
+This is fully supported. This is recommended for the `RISC-V` host target. gcc
+version 11 is recommended for this operating system.
+
+Ubuntu 24.04
+------------
+
+This is supported, but has not been tested to the same level as 22.04. gcc
+version 13 is recommended for this operating system. This will be required for
+some qemu RISC-V features such as the half extension which was added in version
+7.
 
 Windows 10
 ----------
 
 On an x86-64 Windows 10 host system these are the minimum requirements to build
-the oneAPI Construction Kit. These tools are required for any build configuration.
+the oneAPI Construction Kit. These tools are required for any build
+configuration.
 
-* `Visual Studio <https://www.visualstudio.com/>`_ 2017 or 2019
+* `Visual Studio <https://www.visualstudio.com/>`_  2019 or 2022.
 * `Git`_
 * `CMake`_ 3.4.3+
 * `Python`_ 3.6.9+
@@ -149,9 +160,14 @@ Recommended for Windows 10
 .. code-block:: console
 
    $ choco install -y ninja doxygen.install
-   $ choco install -y llvm --version 16.0.6
+   $ choco install -y llvm --version 18.1.5
    $ pip install lit virtualenv cmakelint
 
+Windows 11
+----------
+
+Windows 11 has not been tested but should work.
+
 Vulkan SDK
 ----------
 
@@ -171,11 +187,9 @@ packages`_ page. This installation method does neither set nor require the
 :envvar:`VULKAN_SDK` environment variable, avoiding the configuration
 complexities experienced when installing manually.
 
-Windows 10 users can install the `Vulkan SDK Chocolatey`_ package:
-
-.. code-block:: console
-
-   $ choco install -y vulkan-sdk
+Windows users should install directly from `LunarG
+<https://www.lunarg.com/vulkan-sdk/>`_, as at the time of writing the Vulkan SDK
+cannot be installed through Chocolatey.
 
 Manual Installation
 ...................
@@ -207,7 +221,7 @@ Follow the build instructions, or install the pre-built binaries in the
 repository. It's harder to pin down versions of `SPIRV-Tools`_ since they don't
 do releases, but we should support any commit from after January 2019.
 
-Ubuntu 20.04 users can install ``spirv-tools`` from the package repository:
+Ubuntu 20.04 and later users can install ``spirv-tools`` from the package repository:
 
 .. code-block:: console