Skip to content

Latest commit

 

History

History
244 lines (175 loc) · 8.17 KB

getting-started.rst

File metadata and controls

244 lines (175 loc) · 8.17 KB

Getting Started

Platform Dependencies

Each supported platform has a set of dependencies which are required in order to build the oneAPI Construction Kit.

Once the platform dependencies have been installed please read the :doc:`/developer-guide` for more information about building and contributing to the oneAPI Construction Kit.

Ubuntu 20.04

On an x86-64 host system these are the minimum requirements to build the oneAPI Construction Kit. These packages are required for any build configuration.

$ sudo apt update
$ sudo apt install -y build-essential git cmake libtinfo-dev python3

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 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.
  • lit is a portable tool for executing LLVM and Clang style test suites.
$ sudo apt update
$ sudo apt install -y ninja-build doxygen python3-pip
$ sudo pip3 install lit virtualenv cmakelint clang-format==19.1.0

Tip

For ease of use python3 and pip3 can be symlinked to python and pip with the following commands:

$ sudo apt install python-is-python3
$ sudo update-alternatives --install /usr/bin/pip pip `which pip3` 30

32-bit Compile

Install the 32-bit C and C++ standard libraries, LLVM also depends on the 32-bit terminal info library.

$ sudo apt install -y gcc-9-multilib g++-9-multilib libc6-dev:i386 lib32tinfo-dev

Warning

The gcc-multilib and g++-multilib packages conflict with the Arm and AArch64 toolchain packages below. To install the 32 bit libraries at the same time use gcc-9-multilib, g++-9-multilib, and libc6-dev:i386 that gcc-multilib and g++-multilib depend on but do not conflict with the Arm and AArch64 toolchain packages.

Arm 32-bit Cross Compile

In addition to the 32-bit packages, install the Arm toolchain.

$ sudo apt install -y gcc-9-arm-linux-gnueabihf g++-9-arm-linux-gnueabihf

Arm 64-bit (AArch64) Cross Compile

Install the AArch64 toolchain.

$ sudo apt install -y gcc-9-aarch64-linux-gnu g++-9-aarch64-linux-gnu

Ubuntu 22.04

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.

Windows 10 does not provide an adequate package manager. However, the third-party Chocolatey package manager can be used to install the required packages.

$ choco install -y python
$ choco install -y cmake --installargs 'ADD_CMAKE_TO_PATH=System'

There are a number of choices for installing Git on Windows, the recommended approach is to install Cmder which bundles Git, various UNIX core utilities, and an improved cmd.exe user experience.

$ choco install -y cmder

Alternatively, to install Git for Windows and forego using Cmder do the following.

$ choco install -y git

Recommended for Windows 10

  • 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 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.
  • lit is a portable tool for executing LLVM and Clang style test suites.
$ choco install -y ninja doxygen.install
$ 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

For Vulkan support the Vulkan SDK is required to be installed. It can be acquired from LunarG. The latest version should always be supported. The minimum supported version is 1.1.97.

The Vulkan SDK includes SPIRV-Tools as part of the package. Therefore SPIRV-Tools does not need to be installed separately.

Package Manager Installation

Users of Ubuntu 20.04 and later should configure their apt package manager to install the Vulkan SDK packages directly as described by the LunarG Vulkan SDK 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 users should install directly from LunarG, as at the time of writing the Vulkan SDK cannot be installed through Chocolatey.

Manual Installation

Other Linux users will need to take some extra steps after downloading the tarball distribution. First run the build_tools.sh script; then source the setup-env.sh script whilst the Vulkan SDK directory as the current directory. These steps are needed to access the spirv-as tool through the :envvar:`VULKAN_SDK` environment variable in order to successfully compile the oneAPI Construction Kit and generate all test suites correctly.

Hint

Modifying .bashrc to source the setup-env.sh script avoids having to remember to do this on every new terminal session building the oneAPI Construction Kit.

The setup-env.sh script prepends :envvar:`VULKAN_SDK` to the system :envvar:`PATH`, leading to prioritization of :envvar:`VULKAN_SDK` binaries ahead of any other versions of the tools which may be installed in /usr/bin.

SPIRV-Tools

When OpenCL support is required but Vulkan support is not, SPIRV-Tools may optionally be installed on the system :envvar:`PATH`. This is recommended to achieve good coverage of SPIR-V compilation paths.

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 and later users can install spirv-tools from the package repository:

$ sudo apt install -y spirv-tools

Warning

As the LunarG Vulkan SDK packages and the spirv-tools package both provide SPIRV-Tools builds, it is possible these packages may conflict causing issues during installation. Choose one or the other.