In regular software development parlance, we begin with program sources; we then compile them into binary objects; and finally link the objects them into an executable object. And the entire process is called a build.

Now, in the OpenCL API, we have two functions named clCompileProgram() and clBuildProgram() and . If I were to go by intuition, I would assume that clCompileProgram() only works on programs created with text sources, or at most intermediate language; and that the result of the compilation must then undergo clLinkProgram(); and that clBuildProgram() would take inputs at any stage of the build, and bring them all the way to the end, with executable binary objects.

However... the documentation for these function don't seem to clearly agree with that description:

• Both clCompileProgram() and clBuildProgram() result in "program binaries", which are retried the same way (using clGetProgramInfo() with CL_PROGRAM_BINARIES specified).
• One can't pass memoized headers to clBuildProgram(), as one can to clCompileProgram().
• Both of these can be called with inputs of type clCreateProgramWithSource, clCreateProgramWithIL or clCreateProgramWithBinary (the latter, for clCompileProgram(), only wit switche).
• clCompileProgram() does mention later use of clLinkProgram()?

So, what's the deal? Which of these should I use, and in what sequence?