CMake无法检测到CUDA Toolkit目录：原因及CudaToolkitDir属性解析

问题背景 #

Windows 11系统已安装MSVC和CUDA 13.2，使用如下CMakeLists.txt配置项目：

cmake_minimum_required(VERSION 4.2 FATAL_ERROR)
PROJECT(hello LANGUAGES CUDA)
find_package(CUDAToolkit REQUIRED)

执行cmake -B build命令时触发错误：

error : The CUDA Toolkit directory '' does not exist.

1. 为何CMake认为CUDA Toolkit目录为空？ #

• CMake未定位到CUDA安装路径：Windows下CUDA默认安装路径为C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.2，若安装时修改了路径，或系统未配置对应环境变量，CMake无法自动识别该目录。
• 关键环境变量缺失：CMake查找CUDA依赖CUDA_PATH或CUDAToolkit_ROOT环境变量，若这些变量未设置或设置错误，会导致查找失败，最终目录字段为空。
• CMake版本不兼容：你指定的最低CMake版本为4.2，但CUDA 13.2要求CMake版本至少3.24以上，低版本CMake无法正确识别新版CUDA的安装结构。
• CUDA安装不完整：若安装过程中缺失关键组件，目录或核心文件不存在，CMake检测时会判定目录为空。

2. 什么是CudaToolkitDir属性？ #

• CudaToolkitDir是CMake的CUDAToolkit模块提供的只读属性，用于存储找到的CUDA Toolkit根目录路径。
• 当find_package(CUDAToolkit REQUIRED)执行成功后，该属性会自动赋值，后续可通过${CUDAToolkit_DIR}变量（注意变量名与属性名的细微差异）引用此路径，用于链接CUDA库、引入头文件等操作。
• 它的核心作用是标记CUDA工具包的核心路径，确保项目能正确调用CUDA的编译工具、库文件和头文件资源。

内容的提问来源于stack exchange，提问作者einpoklum