Installing and Building with OpenCL on Gentoo GNU/Linux

December 27 2024I have been using Gentoo as my daily-driver distribution for a while now and, coming from arch, the documentation is a bit different.I was trying to build my graphics engine with g++ when I got this error:

g++ -Og -g -fopenmp -DUNIX -m64 main.cpp ./implementations/display.cpp ./implementations/transforms.cpp 	./implementations/utils.cpp ./implementations/window.cpp ./implementations/gpu.cpp 	./implementations/clbuild.cpp -I. -I/opt/cuda/targets/x86_64-linux/include/CL/ -lm -lX11 -lXext -lOpenCL
In file included from ./include/transforms.hpp:16,
				from main.cpp:16:
./include/../include/gpu.hpp:3:10: fatal error: CL/cl.h: No such file or directory
	3 | #include &lt;CL/cl.h&gt;
	|          ^~~~~~~~~
compilation terminated.
In file included from ./implementations/../include/transforms.hpp:16,
				from ./implementations/display.cpp:8:
./implementations/../include/../include/gpu.hpp:3:10: fatal error: CL/cl.h: No such file or directory
	3 | #include &lt;CL/cl.h&gt;
	|          ^~~~~~~~~
compilation terminated.
In file included from ./implementations/../include/transforms.hpp:16,
				from ./implementations/transforms.cpp:7:
./implementations/../include/../include/gpu.hpp:3:10: fatal error: CL/cl.h: No such file or directory
	3 | #include &lt;CL/cl.h&gt;
	|          ^~~~~~~~~
compilation terminated.
./implementations/gpu.cpp:2:10: fatal error: CL/cl.h: No such file or directory
	2 | #include &lt;CL/cl.h&gt;
	|          ^~~~~~~~~
compilation terminated.
In file included from ./implementations/clbuild.cpp:4:
./implementations/../include/gpu.hpp:3:10: fatal error: CL/cl.h: No such file or directory
	3 | #include &lt;CL/cl.h&gt;
	|          ^~~~~~~~~
compilation terminated.
make: *** [makefile:12: all] Error 1

On most distributions, solving this is as simple as going to the wiki and finding out you need to install the OpenCL headers.On arch, you can run # pacman -S opencl-headers and you'll get the correct header files, ignoring the requirement for an implementation as well.On Gentoo however, I didn't yet know what package the files came from, and I'd like to demonstrate some techniques for solving issues like this.

Searching Packages by Filenames

For Gentoo, there is a website called Portage File List that can be used to search for a package by files.In this case, this is what I wanted, since I'm missing specific header files that need to be included from OpenCL.PFL: https://www.portagefilelist.de/Searching for CL.h returned 20+ files belonging to 7 packages. In my case, I opted for dev-util/nvidia-cuda-toolkit which needed one use flag and one accepted license before it would install.

Linking OpenCL to Your Program

Installing nvidia-cuda-toolkit with the correct header files eliminated my first issue, but introduced a new one. Now the compiler could find the header files, but the linker found no libraries to link against.As per the OpenCL Getting Started guide, you should use gcc and g++ with the -lOpenCL flag set, but compiling with -lOpenCL returned an error from ld.https://github.com/KhronosGroup/OpenCL-Guide/blob/main/chapters/getting_started_linux.md

/usr/libexec/gcc/x86_64-pc-linux-gnu/ld: cannot find -lOpenCL: No such file or directory

Reading the F'ing Manual (RTFM)

The very same OpenCL Getting Started guide I was using to check out the correct compiler flags also mentions installing a package on Ubuntu called ocl-icd-opencl-dev. This package seems innocent, but it could be the key.Doing some searching for "OpenCL ICD" shows that it is a package that "allow(s) developers to build applications against an Installable Client Driver loader (ICD loader) rather than linking their applications against a specific OpenCL implementation."https://github.com/KhronosGroup/OpenCL-ICD-LoaderOpenCL has many implementations for different brands of graphics cards, CPUs, FPGAs, uCs, etc. Setting makefile to link the program to one specific OpenCL implementation, that probably only works on my computer running Gentoo, would be stupid, so we can rely upon the "ICD Loader" to link our program in a more portable way.https://www.iwocl.org/resources/opencl-implementations/Doing a quick search resulted in the Portage package dev-libs/opencl-icd-loader which was a quick install and pulled in one dependency.

Results

Now compiling and linking my program was no issue, and it was running well.Generally, searching and reading the manuals are the only techniques you need to solve issues on Linux. For something with extensive documentation, going straight to the source is the same thing the wiki writers are doing.