clcreateprogramwithsource后必须调用clbuildprogram，否则clcreatekernel返回null、clenqueuendrangekernel报cl_invalid_kernel(-45)；build失败需用clgetprogrambuildinfo获取日志；clcreatecontext须显式指定平台并复用同一cl_device_id，避免多平台/多设备下绑定错误。
clCreateProgramWithSource 之后必须调用 clBuildProgram 才能执行
OpenCL 不像普通 C++ 那样“编译链接后运行”，它的内核代码（__kernel 函数）是在运行时由设备驱动动态编译的。你传入的 kernelSource 字符串只是源码文本，不调用 clBuildProgram 就直接创建 cl_kernel，后续 clEnqueueNDRangeKernel 会失败，错误码通常是 CL_INVALID_PROGRAM_EXECUTABLE。
常见错误现象：
- 程序卡在
clCreateKernel返回NULL，但没检查返回值 - 执行时
clEnqueueNDRangeKernel返回 -45（CL_INVALID_KERNEL），实际根源是前面没 build 成功 - build 失败但没读取日志，误以为成功了——必须用
clGetProgramBuildInfo拿CL_PROGRAM_BUILD_LOG
实操建议：
- 调用
clBuildProgram后，务必检查返回值；若非CL_SUCCESS，立即用clGetProgramBuildInfo获取CL_PROGRAM_BUILD_LOG打印调试 - 不要省略
cl_program的 error-checking：build 失败时，clCreateKernel必然失败，且不报明确原因 - 如果 kernel 源码来自文件（如
"vector_add.cl"），读取后要确保kernel_source.c_str()和kernel_source.size()对齐，避免末尾多 \0 或截断
clCreateContext 要显式指定平台，否则可能绑定错设备
很多示例代码写 clCreateContext(NULL, ...) 看似省事，但在多平台机器（比如同时装了 Intel GPU 驱动 + NVIDIA 驱动）上极不可靠。OpenCL ICD Loader 可能随机选一个平台，导致你本想用 GPU 却绑到了 CPU 设备，或反过来。
实操建议：
- 先用
clGetPlatformIDs拿所有平台，再遍历每个平台调用clGetDeviceIDs查设备类型和名称，用clGetPlatformInfo和clGetDeviceInfo打印识别（例如过滤含"NVIDIA"或"AMD"的CL_PLATFORM_NAME） - 构造
cl_context_properties数组，显式传入CL_CONTEXT_PLATFORM+ 对应cl_platform_id，再传给clCreateContext - 别依赖
clCreateContextFromType(CL_DEVICE_TYPE_GPU, ...)：它不保证跨平台行为一致，某些旧驱动下可能返回 CPU 设备
用 cl::Context（C++ 绑定）比 cl_context（C API）更安全，但要注意 RAII 生命周期
cl.hpp 提供的 C++ 封装确实减少了裸指针管理负担，比如 cl::Context context(device) 自动处理 clCreateContext 和析构时的 clReleaseContext。但它隐藏了错误传播路径——构造失败时抛异常，而默认异常未捕获会导致进程终止。
实操建议：
- 启用异常模式：编译时定义
CL_HPP_ENABLE_EXCEPTIONS，否则所有 C++ 绑定函数返回cl_int错误码，和 C API 一样难 debug - 不要把
cl::Context、cl::CommandQueue等对象声明为全局或静态变量：它们依赖 OpenCL 运行时初始化顺序，提前构造可能 crash - 设备选择仍需手动：C++ 绑定不自动筛选 GPU，
platform.getDevices(CL_DEVICE_TYPE_GPU, &devices)仍可能为空，得 fallback 到 CPU
clBuildProgram 的 device 参数必须和上下文设备完全一致
这是最容易被忽略的兼容性陷阱。你用某个 cl_device_id 创建了 cl_context，但调用 clBuildProgram 时传了另一个设备（哪怕同属一个平台），build 会静默失败或产生不可预测行为。尤其在多 GPU 机器上，clGetDeviceIDs 返回的设备列表顺序不固定，不能假设 devices[0] 就是你上下文里的那个。
实操建议：
- 保存创建上下文时用的
cl_device_id变量（比如叫selected_device），后续所有涉及设备的操作（clBuildProgram、clCreateCommandQueue、clCreateBuffer）都复用它 - 不要混合使用 C API 和 C++ 绑定的设备对象：比如用
cl::Device构造cl::Context，却把它的底层cl_device_id()拿去喂给 C API 的clBuildProgram——虽然可行，但易出错，统一用一套风格更稳 - 如果需要支持多个设备并行 build，必须为每个设备单独创建
cl_context和cl_program；OpenCL 不允许单个 program 对象在多个 context 中复用
clGetPlatformIDs 开始，每一步都校验返回值、打印关键信息、复用同一设备句柄，而不是抄一段“能跑”的示例就完事。C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
