Merge pull request uxlfoundation#491 from coldav/colin/update_docs_re…

…lease

Minor fixes to guides, ready for release.

doc/developer-guide.md

@@ -301,7 +301,7 @@ The builtin CMake options used when invoking CMake on the command line.
   use the installed OpenCL or Vulkan library. Do disable this behaviour set
   `-DCMAKE_SKIP_RPATH=ON` when configuring CMake in build directory.
 
-- `CA_HOST_TARGET_<arch>_CPU`: This option is used by the `host`` target to
+- `CA_HOST_TARGET_<arch>_CPU`: This option is used by the `host` target to
   optimize for performance on a given CPU. `arch` should be a capitalized
   version of the `host` target architecture e.g. `X86_64`, `RISCV64` or
   `AARCH64`. If set to "native" host will optimize for the CPU being used to
@@ -412,10 +412,14 @@ 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
@@ -426,22 +430,19 @@ 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
-> for improve compilation times.
+> for improve compilation times. `Ninja` can also be used in conjunction with the IDE.
 
 Now the build directory is configured, build the `install` target. This can be
 done by opening the `llvm.sln` solution in Visual Studio and building the
@@ -513,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
@@ -545,15 +549,15 @@ 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 . -G"Visual Studio 16 2019 Win64" ^
   -Bbuild-x86_64 ^
   -DCMAKE_BUILD_TYPE=Release ^
   -DCMAKE_INSTALL_PREFIX=%CD%\build-x86_64\install ^
@@ -589,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 . -G"Visual Studio 16 2019 Win64" ^
   -Bbuild-x86_64-Debug ^
   -DCMAKE_BUILD_TYPE=Debug ^
   -DCMAKE_INSTALL_PREFIX=%CD%\build-x86_64-Debug\install ^
@@ -654,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 . -G"Visual Studio 16 2019 Win64" ^
   -Bbuild-offline ^
   -DCMAKE_BUILD_TYPE=Release ^
   -DCMAKE_INSTALL_PREFIX=%CD%\build-offline\install ^
@@ -701,6 +705,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.
@@ -865,8 +871,8 @@ ninja -C build-aarch64 check
 #### Cross-compiling the oneAPI Construction Kit for Windows with the MinGW toolchain
 
 oneAPI Construction Kit for Windows can be built on Linux using MinGW. This
-requires LLVM that has been built with MinGW. Note that offline-compiled
-kernels cannot be built, because there is no way to run the `clc` that is built.
+requires LLVM that has been built with MinGW. Note that MinGW kernels cannot be
+compiled offline using an external clc, so we disable their tests.
 
 ```console
 cmake -GNinja \
@@ -882,6 +888,8 @@ cmake -GNinja \
 cmake --build build-mingw --target ComputeAorta
 ```
 
+This is not part of the regular testing, but should work.
+
 ## Testing
 
 <!-- TODO: Document gtest suites -->

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 is supported, but has not been tested to the same level as Windows 10.
+
 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