Chapter 01: Getting started — Setting up OpenCL

Introduction

This chapter describes how to install and verify an OpenCL development environment so that opencltools — and any downstream package that uses it, such as nmathopencl or glmbayes — can compile and run GPU‑accelerated code.

OpenCL is vendor‑neutral and works across NVIDIA, AMD, and Intel hardware. All opencltools functions degrade gracefully when OpenCL is unavailable: device probing, kernel source loading, dependency sorting, and library subsetting all work without a GPU. Only the live kernel‑launch path requires OpenCL at runtime.

1. Download and install build tools

1.1 Windows: Install Rtools

https://cran.r-project.org/bin/windows/Rtools/

1.2 Linux: Install compiler toolchain and R development headers

1.3 macOS: Install Xcode Command Line Tools and GCC

macOS requires both the Xcode Command Line Tools and GCC when installing packages from source. The configure script uses GCC to detect system include and library paths for OpenCL.

xcode-select --install
brew install gcc

Binary installs do not require GCC.

2. Install OpenCL components

Packages that use GPU acceleration must be installed from source because neither CRAN nor R‑universe build packages with OpenCL GPU support — their build systems do not provide OpenCL headers or development libraries, so any precompiled binary has OpenCL disabled. To enable GPU acceleration you must build from source on a system with a complete OpenCL development environment.

A full OpenCL development environment includes:

  1. OpenCL header files (needed at compile time)
  2. The OpenCL runtime / ICD loader (needed at runtime)
  3. The OpenCL development library providing the unversioned linker symlink libOpenCL.so (needed for linking)

Most GPU drivers provide only the vendor‑specific runtime, not the headers or the development symlink. The following subsections describe how to obtain all three components on each platform.

2.1 Windows

Choose one of:

Note: When installing the CUDA Toolkit, Intel OpenCL SDK, or Khronos headers you can accept all default installation options. The defaults include CL/cl.h and the other headers required to compile from source.

On Windows, installing the CUDA Toolkit or Intel OpenCL SDK is sufficient; no additional runtime or development packages are required.

AMD’s Windows driver package includes the OpenCL runtime and ICD components automatically. No additional installation or PATH configuration is required. If OpenCL is not detected, updating to the latest AMD Software (Adrenalin Edition) typically resolves the issue.

2.2 Linux

To compile and run with OpenCL support on Linux, you must install:

  1. An OpenCL implementation (vendor runtime)
  2. OpenCL header files (compile‑time)
  3. The OpenCL ICD loader (runtime)
  4. The OpenCL development library providing libOpenCL.so (linking)

The correct OpenCL implementation depends on your GPU vendor. For NVIDIA and Intel the runtime is installed automatically with the GPU driver. For AMD see Appendix A.

2.2.1 OpenCL implementation (vendor runtime)

  • NVIDIA: installed automatically with the proprietary driver.
  • Intel: installed automatically with the Intel GPU driver.
  • AMD: requires installing ROCm OpenCL. See Appendix A.

2.2.2 OpenCL header files

These provide CL/cl.h, CL/cl_platform.h, and related headers.

  • Ubuntu / Debian

      sudo apt-get install opencl-headers

  • Fedora

      sudo dnf install opencl-headers

  • Arch Linux

      sudo pacman -S opencl-headers

2.2.3 OpenCL runtime (ICD loader)

Provides the shared library libOpenCL.so.1 required for OpenCL to function at runtime.

  • Ubuntu / Debian

      sudo apt-get install ocl-icd-libopencl1

  • Fedora

      sudo dnf install ocl-icd

  • Arch Linux

      sudo pacman -S opencl-icd-loader

2.3 macOS

macOS includes the OpenCL headers and system runtime as part of the Xcode Command Line Tools, so no additional installation is required for compilation. However, Apple has deprecated OpenCL, and modern Apple Silicon systems do not provide hardware OpenCL support. Packages will compile successfully on macOS but GPU acceleration is not guaranteed and may fall back to CPU execution.

3. Install opencltools from source (for OpenCL)

The CRAN release and pre-built R-Universe binaries are built without OpenCL GPU support. Install from source on a machine with OpenCL headers and a working vendor runtime to enable GPU acceleration.

install.packages(
  "opencltools",
  repos = c("https://cloud.r-project.org", "https://knygren.r-universe.dev"),
  type = "source"
)

4. Load the package

library(opencltools)

5. Check for OpenCL availability

On Linux, if you have shell access (including Jupyter Terminal on a cloud instance), running clinfo before opening R is recommended — it catches missing vendor ICDs early, independent of the R session.

has_opencl()

5.1 Full diagnostic

If has_opencl() returns FALSE, or to get a complete picture of your OpenCL environment, run the diagnostic suite:

# High-level environment and GPU detection
detect_environment_and_gpus()

# Runtime availability check (platform probe)
verify_opencl_runtime()

# PATH and library directory validation
check_runtime_env()

detect_environment_and_gpus() reports the OS, GPU vendor(s) detected, and which runtimes are present. verify_opencl_runtime() performs a live clGetPlatformIDs() call and reports the first usable device. check_runtime_env() validates PATH and library search paths.

A clean verify_opencl_runtime() output looks like:

=== OpenCL Runtime Check ===
Environment: linux
GPU: NVIDIA
  [OK] Driver installed
  [OK] OpenCL headers found (CL/cl.h)
  [OK] OpenCL runtime found (libOpenCL ICD)
  [OK] OpenCL fully available (headers + runtime)
  [OK] Required PATH and library dirs present
  [OK] OpenCL runtime probe succeeded (platform available)
  [OK] opencltools was compiled with OpenCL support.

If any line shows a warning or error the output indicates which component is missing and how to correct it.

6. Verify the kernel-loading path

Even without a GPU you can verify that opencltools’ kernel loading and dependency management work correctly. These operate entirely in R without touching the OpenCL runtime:

library(opencltools)

# Load a single kernel source file
src <- load_kernel_source("OPENCL.cl")
nchar(src)

# List available devices (requires runtime)
if (has_opencl()) {
  opencl_device_info()
  gpu_names()
}

References

Stone, J. E., Gohara, D., & Shi, G. (2010). OpenCL: A Parallel Programming Standard for Heterogeneous Computing Systems. IEEE Computing in Science & Engineering, 12(3), 66–72. https://doi.org/10.1109/MCSE.2010.69

Khronos OpenCL Working Group. The OpenCL Specification and The OpenCL C Specification. https://www.khronos.org/opencl/

OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission by Khronos.