Installation — Portable Computing Language (PoCL) 6.0 documentation (original) (raw)

Requirements

In order to build pocl, you need the following support libraries and tools:

Installing requirements for Ubuntu

Note: The binary packages from https://apt.llvm.org/ are recommended (and tested for each release) instead of the binary tar balls or the packages included in the distribution. The following assumes apt.llvm.org is added to your apt repos:

apt install -y python3-dev libpython3-dev build-essential ocl-icd-libopencl1 cmake git pkg-config libclang-${LLVM_VERSION}-dev clang-${LLVM_VERSION} llvm-${LLVM_VERSION} make ninja-build ocl-icd-libopencl1 ocl-icd-dev ocl-icd-opencl-dev libhwloc-dev zlib1g zlib1g-dev clinfo dialog apt-utils libxml2-dev libclang-cpp${LLVM_VERSION}-dev libclang-cpp${LLVM_VERSION} llvm-${LLVM_VERSION}-dev

Installing requirements for Arch Linux:

pacman -S gcc patch hwloc cmake git pkg-config make ninja ocl-icd clang llvm llvm-libs clinfo opencl-headers

Installing requirements for Fedora:

dnf install gcc gcc-c++ clinfo hwloc-devel hwloc-libs cmake git-core pkgconfig make ninja-build ocl-icd ocl-icd-devel clang clang-devel clang-libs llvm llvm-devel llvm-libs patch redhat-rpm-config findutils

There are also Dockerfiles available for a few most common linux distributions in tools/docker, looking into them might be helpful.

OpenCL 3.0 support

If you want PoCL built with ICD and OpenCL 3.0 support at platform level, you will need sufficiently new ocl-icd (2.3.x). For Ubuntu, it can be installed from this PPA: https://launchpad.net/~ocl-icd/+archive/ubuntu/ppa

Note: PoCL assumes that the OpenCL development headers and the ICD loader (if present on your system) are version compatible.

Clang / LLVM Notes

IMPORTANT NOTE! Some targets (TCE and possibly HSA) require that you compile & build LLVM with RTTI on. It can be enabled on cmake command line, as follows:

cmake [other CMake options] -DLLVM_ENABLE_RTTI=ON -DLLVM_ENABLE_EH=ON

Supported LLVM versions

Note that pocl aims to support the latest LLVM version at the time of pocl release, plus the previous LLVM version. All older LLVM versions are supported with “best effort” basis; there might not be CI continuously testing the code base nor anyone fixing their possible breakage.

Configure & Build

CMake version 3.12 or higher is required.

The build+install is the usual CMake way:

cd mkdir build cd build cmake [-D

To see the default detected values, run cmake .. without any options, it will produce a summary.

CMake variables

Since pocl includes a compiler for the kernels, it both compiles (producing code) and is compiled (it consists of code). This distinction typically called “host” and “target”: The host is where pocl is running, the target is where the OpenCL code will be running. These two systems can be wildly different.

Host compiler used to compile pocl can be GCC or Clang; the target compiler is always Clang+LLVM since pocl uses Clang/LLVM internally. For host compiler, you should use the one which your LLVM was compiled with (because the LLVM-related parts of pocl take LLVM’s CXXFLAGS from llvm-config and pass them to the host compiler).

CMake host flags

Compile C:

CMAKE_C_FLAGS CMAKE_C_FLAGS_

Compile C++:

CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_

Building kernels and the kernel library, i.e. target flags

All of these empty by default. There are hardcoded defaults which may be overridden by setting these variables (rarely needed).

Extra parameters to llc

EXTRA_HOST_LLC_FLAGS

Extra parameters to clang

EXTRA_HOST_CLANG_FLAGS

Extra parameters to linker (links kernel to shared library which is then dlopened):

EXTRA_HOST_LD_FLAGS

EXTRA_KERNEL_FLAGS

is applied to all kernel library compilation commands, IOW it’s for language-independent options

EXTRA_KERNEL_{C,CL,CXX}_FLAGS

cmake variables for per-language options for kernel library compilation

CMake: other options & features

Note that there are a few more packaging-related options described in README.packaging.

For multiple-item options like KERNELLIB_HOST_CPU_VARIANTS, use “;” as separator (you’ll have to escape it for bash).

LLVM-less build

You can build a runtime-only pocl to run prebuilt pocl binaries on a device. To do this

The string after “HSTR:” is the device build hash.

NOTE: If you’ve enabled the almaif device, HOST_DEVICE_BUILD_HASH can be set to anything you want. Reason being, fixed function accelerators don’t require compiling OpenCL kernels, therefore, no hash will ever be matched.

Cross-compile PoCL

It’s now possible to cross-compile pocl on x86-64 to run on ARM/MIPS/etc, There is a ToolchainExample.cmake file; copy it under different name, then follow the instructions in the file.

Known build-time issues

There are unsolved issues and bugs in pocl. See the bug listing for a complete listing at https://github.com/pocl/pocl/issues

Building & running in Docker

Make sure you have enough space (default location is usually /var/lib/docker, required storage for standard pocl build is about 1.5 GB per container)

Build & start Pocl container

Dockerfiles

Note that some images (e.g. RHEL and PHSA) may be impossible to build, due to not having a sufficiently new version of LLVM available.

Dockerfiles are named according to what they build, or the release they’re based on:

ARM 32/64bit support

Status:

PoCL builds (as of Dec 2023) on ODROID XU3 and ODROID C2 and almost all tests pass.

ARM specific build notes:

RISC-V support

The RISC-V support has been tested (as of Dec 2023) on Starfive VisionFive 2 using Ubuntu 23.10 preinstalled image, with LLVM 17 and GCC 13.2; of the internal tests, 98% tests pass, 4 tests fail out of 253. In particular, tests using printf with vector arguments are broken ATM. Other boards / CPUs have not been tested. RISC Vector extension is not supported.

RISC-V specific build notes: