Missing documentation on how to build and run an OpenCL example program

[rojkov]

I managed to successfully build the runtime as a deb package and after its installation clinfo reports platforms and devices correctly. But now I'm struggling to compile an example program like [1]. It builds and works perfectly when linked to Beignet.

With the current runtime I get

$ gcc -g -w fft.c -o fft -I../opencl_headers -L/opt/intel/opencl -ligdrcl -lm
/tmp/ccYHHFKV.o: In function `fftCore':
/home/rojkov/work/vpg/opencl-book-example/fft.c:63: undefined reference to `clCreateKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:68: undefined reference to `clCreateKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:73: undefined reference to `clCreateKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:91: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:96: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:101: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:106: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:112: undefined reference to `clSetKernelArg'
/tmp/ccYHHFKV.o:/home/rojkov/work/vpg/opencl-book-example/fft.c:117: more undefined references to `clSetKernelArg' follow
/tmp/ccYHHFKV.o: In function `fftCore':
/home/rojkov/work/vpg/opencl-book-example/fft.c:151: undefined reference to `clEnqueueNDRangeKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:163: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:169: undefined reference to `clEnqueueNDRangeKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:176: undefined reference to `clWaitForEvents'
/home/rojkov/work/vpg/opencl-book-example/fft.c:182: undefined reference to `clGetEventProfilingInfo'
/home/rojkov/work/vpg/opencl-book-example/fft.c:190: undefined reference to `clGetEventProfilingInfo'
/home/rojkov/work/vpg/opencl-book-example/fft.c:204: undefined reference to `clEnqueueNDRangeKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:211: undefined reference to `clWaitForEvents'
/home/rojkov/work/vpg/opencl-book-example/fft.c:219: undefined reference to `clReleaseKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:224: undefined reference to `clReleaseKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:229: undefined reference to `clReleaseKernel'
/tmp/ccYHHFKV.o: In function `main':
/home/rojkov/work/vpg/opencl-book-example/fft.c:306: undefined reference to `clGetPlatformIDs'
/home/rojkov/work/vpg/opencl-book-example/fft.c:311: undefined reference to `clGetDeviceIDs'
/home/rojkov/work/vpg/opencl-book-example/fft.c:319: undefined reference to `clCreateContext'
/home/rojkov/work/vpg/opencl-book-example/fft.c:326: undefined reference to `clCreateCommandQueue'
/home/rojkov/work/vpg/opencl-book-example/fft.c:334: undefined reference to `clCreateBuffer'
/home/rojkov/work/vpg/opencl-book-example/fft.c:340: undefined reference to `clCreateBuffer'
/home/rojkov/work/vpg/opencl-book-example/fft.c:346: undefined reference to `clCreateBuffer'
/home/rojkov/work/vpg/opencl-book-example/fft.c:355: undefined reference to `clEnqueueWriteBuffer'
/home/rojkov/work/vpg/opencl-book-example/fft.c:364: undefined reference to `clCreateProgramWithSource'
/home/rojkov/work/vpg/opencl-book-example/fft.c:372: undefined reference to `clBuildProgram'
/home/rojkov/work/vpg/opencl-book-example/fft.c:379: undefined reference to `clCreateKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:384: undefined reference to `clCreateKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:389: undefined reference to `clCreateKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:396: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:397: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:399: undefined reference to `clEnqueueNDRangeKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:410: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:411: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:412: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:414: undefined reference to `clEnqueueNDRangeKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:426: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:427: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:428: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:430: undefined reference to `clEnqueueNDRangeKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:443: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:444: undefined reference to `clSetKernelArg'
/home/rojkov/work/vpg/opencl-book-example/fft.c:446: undefined reference to `clEnqueueNDRangeKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:457: undefined reference to `clEnqueueReadBuffer'
/home/rojkov/work/vpg/opencl-book-example/fft.c:482: undefined reference to `clFlush'
/home/rojkov/work/vpg/opencl-book-example/fft.c:487: undefined reference to `clFinish'
/home/rojkov/work/vpg/opencl-book-example/fft.c:492: undefined reference to `clReleaseKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:497: undefined reference to `clReleaseKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:502: undefined reference to `clReleaseKernel'
/home/rojkov/work/vpg/opencl-book-example/fft.c:507: undefined reference to `clReleaseProgram'
/home/rojkov/work/vpg/opencl-book-example/fft.c:512: undefined reference to `clReleaseMemObject'
/home/rojkov/work/vpg/opencl-book-example/fft.c:518: undefined reference to `clReleaseMemObject'
/home/rojkov/work/vpg/opencl-book-example/fft.c:524: undefined reference to `clReleaseMemObject'
/home/rojkov/work/vpg/opencl-book-example/fft.c:530: undefined reference to `clReleaseCommandQueue'
/home/rojkov/work/vpg/opencl-book-example/fft.c:535: undefined reference to `clReleaseContext'
collect2: error: ld returned 1 exit status

readelf shows that the missing functions exist in the lib, but not exported for some reason. The only exported functions seem to be only clIcdGetPlatformIDsKHR, clGetPlatformInfo and clGetExtensionFunctionAddress. How the lib is supposed to be used then?

Could you please provide a short intro on how to use the runtime?

[1] https://github.com/rojkov/opencl-fft-example

[MichalMrozek]

We currently do not support direct linking to igdrcl, that's why those functions are not exported. We will add proper clarifications to our documents.

Supported model is to link with ICD library.

In general we do not want to export those functions from the library as we prefer to be used via ICD, as this is the correct layer to handle such interaction.

Are there any strong reasons to use Runtime directly ?

[rojkov]

Thank you for the explanation!

There's no particular reason. For a newbie like me it's just unusual that a lib is supposed to be used through an additional layer of indirection. Probably the deb package could have a binary dependency on the ICD library declared to give users a hint.

[MichalMrozek]

With commit b397499 our Readme file is updated,

[MichalMrozek]

We had an internal discussion about adding binary dependency on ICD for deb package and we fell that it's not a correct thing. This is due to the fact that we don't require ICD to install the driver and we do not want to warn/fail at the installation time about its absence. We feel that it is applications responsibility to link properly and check for its dependencies.

At this moment we think that README clarifies this problem.
If you strongly disagree feel free to reopen with arguments.