From 81e7cd3524e0a2d07f395739ff24c230baac97c4 Mon Sep 17 00:00:00 2001 From: Colin Davidson Date: Tue, 9 Jul 2024 15:12:21 +0100 Subject: [PATCH] Minor fixes to guides, ready for release. Improved commentary on supported platforms and build of OCK/llvm. --- doc/developer-guide.md | 38 +++++++++++++++++++++++--------------- doc/getting-started.rst | 36 +++++++++++++++++++++++++----------- 2 files changed, 48 insertions(+), 26 deletions(-) diff --git a/doc/developer-guide.md b/doc/developer-guide.md index 2eb09db29..31a795188 100644 --- a/doc/developer-guide.md +++ b/doc/developer-guide.md @@ -303,7 +303,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__CPU`: This option is used by the `host`` target to +- `CA_HOST_TARGET__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 @@ -414,10 +414,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 @@ -428,22 +432,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 @@ -515,6 +516,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,7 +551,7 @@ 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 @@ -555,7 +559,7 @@ 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 ^ @@ -591,7 +595,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 ^ @@ -656,7 +660,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 ^ @@ -703,6 +707,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. @@ -867,8 +873,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 \ @@ -884,6 +890,8 @@ cmake -GNinja \ cmake --build build-mingw --target ComputeAorta ``` +This is not part of the regular testing, but should work. + ## Testing diff --git a/doc/getting-started.rst b/doc/getting-started.rst index 9fd2253e1..d0a6f9304 100644 --- 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 `_ 2017 or 2019 +* `Visual Studio `_ 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 +`_, 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