Overview

To use OpenCL, you need three things:

libOpenCL.so -- the "ICD loader"

This library dispatches your OpenCL calls to OpenCL implementations. It is what you link into your OpenCL-using program (or into PyOpenCL, as the case may be). Individual implementations are called ICDs ("Installable Client Drivers").

/etc/OpenCL/vendors/*.icd -- the "ICD registry"

These files tell the ICD loader what OpenCL implementations (ICDs) are installed on your machine. There's one for each ICD. Each file is a one-line text file containing the name of the dynamic library (aka shared object, aka ".so" file) containing the implementation. The single line may either be the full absolute path or just the file name, in which case the dynamic linker must be able to find that file--perhaps with the help of setting the LD_LIBRARY_PATH environment variable. The names of the .icd files themselves are arbitrary, but they must have a file extension of .icd.

One or more OpenCL implementations -- the "ICDs"

These are dynamic libraries pointed to by the .icd files, plus perhaps a few supporting files. They may reside anywhere on your file system. You can (and likely want to) have more than one installed.

Each implementation typically ships all of these components. They will tend to step on each other's feet if you're not careful. Avoiding such accidents is what this guide is about.

Installation

Installing the AMD ICD loader and CPU ICD (from the "APP SDK")

The AMD ICD works on both AMD and Intel CPUs. And is recommended even for Intel CPUs not providing SSE3/SEE4 support which is required by more recent versions of the Intel OpenCL SDK.

Update: as of July 2014, the AMD Accelerated Parallel Processing ("APP") package can be found here. After agreeing to the license and downloading the appropriate TGZ file, untar it and run

sudo ./AMD-APP-SDK-v3.0.130.136-GA-linux64.sh

Reportedly, the instructions that used to be here no longer work. Greg von Winckel has written a script that can be used instead to do the same thing.

If you want to build code using OpenCL, you probably also want the OpenCL headers. See #headers.

You probably want to change VERSION.MINOR to the version you actually downloaded. The cp might complain about leaving out 'fglrx', which is a directory--that's fine.

The $TGT_DIR will then contain the AMD ICD and the AMD ICD loader. If you want to build code using OpenCL, you probably also want the OpenCL headers. See #headers.

Using the AMD ICD with GPUs

Note that the above procedure only works for the CPU ICD. To use an AMD GPU, use the regular driver installation procedure of your Linux distribution, and do not follow the instructions above. The GPU driver will automatically install and set up everything above.

Running OpenCL code remotely on AMD GPUs (via SSH) without sudo

To use an AMD GPU from OpenCL, the X server has to be running, and the OpenCL code has to have access to it. If you're running your code from within the X session, everything should just work. If you want to run code remotely, the following might help:

Create an amdgpu group, with all the users that need to run code remotely.

You probably want to change VERSION.MINOR to the version you actually downloaded. You also need an ICD loader. See the AMD instructions for that.

Installing the Nvidia ICD

Whatever procedure your distribution uses for installing the Nvidia GPU driver should automatically also install the OpenCL ICD. It might also overwrite your system-wide ICD loader, if you have one.

Note that you need the permission bits on /dev/nvidia* set to allow access if you want remote (SSH) GPU access. Since many Linux distributions play idiotic games with those permission bits as well as the ownership of the device, the most robust solutionn I've found is to use POSIX ACLs:

setfacl -m g:gpu:rw /dev/nvidia*

Debian

Debian packages OpenCL very well and makes installing this much easier.

Packages of ICD loaders: (you just need one of these)

amd-libopencl1 (recommended)

nvidia-libopencl1

ocl-icd-libopencl1 (the reference implementation)

Packages of ICDs:

amd-opencl-icd

nvidia-opencl-icd

beignet

Package for headers:

opencl-headers

I would recommend using the latest versions (perhaps from the 'experimental' repository). Those are usually the least buggy.

In particular, Debian makes it straightforward to use both AMD and Nvidia GPUs in the same computer. Just let the AMD driver drive the display, for Nvidia only install the ICD.

The Intel CPU ICD is not packaged. Install it manually as above.

beignet is a project initiated by Intel to provide OpenCL support for their Ivy Bridge GPUs.