企业官网建设流程全解析

深入解析 PyTorch 的 cmake/Modules_CUDA_fix：为旧版 CMake 回移 FindCUDA 补丁的机制与实战指南

【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch

导读

本文围绕 PyTorch 仓库中的 cmake/Modules_CUDA_fix/README.md 展开，系统剖析 PyTorch 如何在构建系统中"自备一份打过补丁的FindCUDA.cmake"，把新版 CMake 才修复的两个 NVCC 编译缺陷移植到旧版 CMake 上。读完本文，你将理解该目录的目录结构、两类补丁的底层成因、顶层 wrapper 与 upstream 模块的协作方式，以及它在 PyTorch CUDA 构建流程中的真实接入点，从而能在自己的 CUDA 项目中借鉴这套"回移补丁 + wrapper 自动装载"的工程实践。

一、背景：PyTorch 为什么需要一份自带的 FindCUDA

在 CMake 生态中，FindCUDA.cmake是一段经典的查找脚本，负责定位 NVIDIA CUDA 工具链（nvcc、CUDA 头文件、cudart 等运行时库），并对外提供CUDA_FOUND、CUDA_NVCC_EXECUTABLE、CUDA_INCLUDE_DIRS等变量，以及CUDA_ADD_LIBRARY、CUDA_WRAP_SRCS等宏，供find_package(CUDA)调用。

值得先说明一个"版本观"：仓库中这份从上游 CMake 移植的FindCUDA模块，其头部文档已经明确写着该模块已被 CMake 对 CUDA 语言的一等支持所取代，保留它只是为了兼容尚未迁移的老项目（见 upstream/FindCUDA.cmake 第 5~17 行）。PyTorch 的构建既有调用旧式find_package(CUDA)的地方，也通过enable_language(CUDA)与find_package(CUDAToolkit REQUIRED)走 CMake 原生路径（见 cmake/public/cuda.cmake）。

问题在于：PyTorch 需要支持比官方最新 CMake 更早的版本范围，而新版 CMake 对FindCUDA的若干修复（涉及 nvcc 编译参数拼装）在旧版上反而会报错。因此 PyTorch 不能简单升级 CMake 解决，而是把修复回移进仓库，形成一个专用的模块搜索目录——这就是cmake/Modules_CUDA_fix存在的直接原因。

二、目录结构：wrapper、upstream 与附属查找模块

先给出该目录在仓库中的实际文件布局（以仓库根目录为起点）：

cmake/Modules_CUDA_fix/ ├── FindCUDA.cmake # 顶层 wrapper：引入 upstream 前的初始化入口 ├── FindCUDNN.cmake # 同目录下的 cuDNN 查找模块（供 find_package(CUDNN) 使用） ├── README.md # 本文所依据的核心说明文档 └── upstream/ # 从 CMake 主线回移的"打了补丁"的模块 ├── CMakeInitializeConfigs.cmake ├── FindCUDA.cmake ├── FindPackageMessage.cmake ├── README.md └── FindCUDA/ ├── make2cmake.cmake ├── parse_cubin.cmake ├── run_nvcc.cmake └── select_compute_arch.cmake

各角色可概括为：

• upstream/：从 CMake 主线仓库回移的一整套FindCUDA实现（含子脚本run_nvcc.cmake、parse_cubin.cmake、make2cmake.cmake、select_compute_arch.cmake等），并在其上叠加了针对旧版 CMake 的兼容修复；
• 顶层FindCUDA.cmake（wrapper）：不直接改动上游源码，而是在 include 上游模块之前完成必要初始化，保证回移补丁在旧版 CMake 上可运行；
• CMakeInitializeConfigs.cmake：定义了cmake_initialize_per_config_variable等"每构建类型变量"初始化辅助函数，是新补丁引用的新依赖（详见第四节）；
• FindCUDNN.cmake：同一目录下的姊妹模块。由于 cmake/public/cuda.cmake 先把本目录追加进CMAKE_MODULE_PATH，第 189 行的find_package(CUDNN)也会经由该模块解析。

upstream/README.md的内容很短，主要交代升级策略（见第七节），并回链到本目录的 README.md。

三、被回移的两类上游修复

按照 Modules_CUDA_fix/README.md 的说明，这个upstream子目录包含两个对FindCUDA的修复，它们分别来自 CMake 主线不同时期的提交，但共同点是：只适合较新版本 CMake，若直接用在旧版 CMake 上会触发"生成器表达式（generator expression）"相关错误。

3.1 include 目录生成器表达式缺少-I前缀（首次修复于 CMake 3.7，对应提交 7ded655f）

这是该目录 README 列出的第一个问题：旧版FindCUDA在把 include 目录传给 NVCC 时，会把一个生成器表达式整体拼进参数串，并在表达式前只加一次-I。生成器表达式（形如$<TARGET_PROPERTY:target,INCLUDE_DIRECTORIES>）在构建期会展开为一个目录列表；当它展开出多个目录时，只有第一个目录享受了-I前缀，第二、第三个目录裸奔在命令行上，NVCC 随即报错。

在仓库代码中可以找到与该缺陷对应的生成器表达式使用点。upstream/FindCUDA.cmake在收集目标 include 目录时写道：

# Append the include directories for this target via generator expression, which is # expanded by the FILE(GENERATE) call below. list(APPEND CUDA_NVCC_INCLUDE_DIRS "$<TARGET_PROPERTY:${cuda_target},INCLUDE_DIRECTORIES>")

（见 upstream/FindCUDA.cmake 第 1334~1341 行。）这段注释点明了关键机制：表达式由后续的file(GENERATE ...)在生成阶段展开，而不是在 configure 阶段展开。同一文件后面构造按构建类型区分的编译脚本时也确实用了file(GENERATE)：

set(custom_target_script "${cuda_compile_intermediate_directory}/${generated_file_basename}$<$<BOOL:$<CONFIG>>:.$<CONFIG>>.cmake") ... configure_file("${CUDA_run_nvcc}" "${custom_target_script_pregen}" @ONLY) file(GENERATE OUTPUT "${custom_target_script}" INPUT "${custom_target_script_pregen}" )

（见 upstream/FindCUDA.cmake 第 1525、1566~1570 行。）README 特别点名了NNPACK的 include 目录：NNPACK 通过生成器表达式挂入多个 include 路径，在旧实现下正是"N 个目录只有第一个带-I"这类问题的典型触发者。

需要强调的是，本次修复是"把主线修复回移"而非 PyTorch 自创逻辑——README 明确记录该问题首次在 CMake 3.7 中修复（Kitware 提交 7ded655f），这里是把修复成果搬到旧版能用的形态。

3.2 Windows / VS2017 下 ccbin（主机编译器路径）的差异处理（3.10.1 master 之后引入，对应提交 bc88329e）

第二个问题发生在 Windows + Visual Studio 场景：新版 Visual Studio 2017（对应MSVC_VERSION >= 1910）改变了 MSVC 工具链的目录布局，编译器所在的 ccbin 路径必须与旧版 Visual Studio 区分开。若FindCUDA不知道这种差异，为 nvcc 指定的-ccbin（主机编译器绑定目录）就会指向错误位置，导致 CUDA 编译失败。

仓库中的upstream/FindCUDA.cmake精确地实现了这一分支。先看它对"VS2017 前后默认主机编译器路径"的区分：

elseif(CMAKE_GENERATOR MATCHES "Visual Studio") set(_CUDA_MSVC_HOST_COMPILER "$(VCInstallDir)Tools/MSVC/$(VCToolsVersion)/bin/Host$(Platform)/$(PlatformTarget)") if(MSVC_VERSION LESS 1910) set(_CUDA_MSVC_HOST_COMPILER "$(VCInstallDir)bin") endif() set(CUDA_HOST_COMPILER "${_CUDA_MSVC_HOST_COMPILER}" CACHE FILEPATH "Host side compiler used by NVCC")

（见 upstream/FindCUDA.cmake 第 539~545 行。）可见：VS2017 及以上（MSVC_VERSION >= 1910）走$(VCInstallDir)Tools/MSVC/$(VCToolsVersion)/bin/Host$(Platform)/$(PlatformTarget)这条带版本号的新路径；更早的 Visual Studio 回退到旧的$(VCInstallDir)bin。这正是 README 所说"在早期 VS 版本与 VS2017 之间以不同方式定义 ccbin 路径"。

随后，构建规则把这些宏推迟到编译期展开（因为 VS 多配置构建要到 build 阶段才知道具体配置）：

if(CMAKE_GENERATOR MATCHES "Visual Studio") set(ccbin_flags -D "\"CCBIN:PATH=${_CUDA_MSVC_HOST_COMPILER}\"" ) else() set(ccbin_flags) endif()

（见 upstream/FindCUDA.cmake 第 1302~1310 行。）执行 nvcc 时，若用户没有显式给出-ccbin/--compiler-bindir，模块再把CUDA_HOST_COMPILER拼进去：

list( FIND nvcc_flags "-ccbin" ccbin_found0 ) list( FIND nvcc_flags "--compiler-bindir" ccbin_found1 ) if( ccbin_found0 LESS 0 AND ccbin_found1 LESS 0 AND CUDA_HOST_COMPILER ) ... list(APPEND nvcc_flags -ccbin "${CUDA_HOST_COMPILER}")

（见 upstream/FindCUDA.cmake 第 1693~1701 行。）路径中残留$(VCInstallDir)这类 VS 宏时，构建命令还会相应地去掉VERBATIM，让宏能由 VS 在编译期展开（第 1603~1605 行）。

README 记录该修复在 CMake 3.10.1 的 master 版本之后引入（Kitware 提交 bc88329e），因此它同样属于"较新 CMake 才有的行为"，需要回移才能让旧版 CMake 的 PyTorch 用户在 VS2017+ 上正确编译 CUDA。

四、回移的代价：补丁依赖新变量初始化，需CMakeInitializeConfigs.cmake打前站

任何回移都不是免费的。该目录 README 明确指出了这套补丁的"副作用"：upstream/中新版的FindCUDA.cmake依赖一些只在较新 CMake 中才定义的变量与辅助函数，这些内容由新增的./upstream/CMakeInitializeConfigs.cmake提供（对应 Kitware 提交 48f7e2d3）。因此，在使用./upstream/FindCUDA.cmake之前，必须先 include./upstream/CMakeInitializeConfigs.cmake，否则在旧版 CMake 上回移补丁本身会因找不到新变量而失败。

这一依赖在实际代码中有清晰印证。upstream/FindCUDA.cmake在初始化各配置的 NVCC 编译参数时调用了：

cmake_initialize_per_config_variable(CUDA_NVCC_FLAGS "Semi-colon delimit multiple arguments.")

（见 upstream/FindCUDA.cmake 第 535 行。）而cmake_initialize_per_config_variable这个函数正是由 upstream/CMakeInitializeConfigs.cmake 定义的。其核心逻辑是把CUDA_NVCC_FLAGS（以及CUDA_NVCC_FLAGS_DEBUG、CUDA_NVCC_FLAGS_RELEASE等按Debug/Release/MinSizeRel/RelWithDebInfo及多配置生成器展开的变体）统一初始化为 CMake 缓存变量，以便FindCUDA在后续CUDA_WRAP_SRCS等宏中按构建类型拼装 nvcc 参数。

该初始化文件自身也写明了"旧版兼容"定位——文件开头注释提到上游用include_guard(GLOBAL)但旧版 CMake 尚不支持，因此被移除或替换（见 upstream/CMakeInitializeConfigs.cmake 第 4~5 行）。这进一步说明：整个upstream目录就是一份"按 PyTorch 需要支持的 CMake 最低版本做裁剪与适配"的定制快照。

五、顶层 wrapper：让子模块无感使用补丁的关键设计

"必须在 FindCUDA 之前先 include 初始化文件"这一顺序约束若交给每个调用方手动维护，极易出错。README 给出的工程解法是：提供一个顶层 wrapper./FindCUDA.cmake，把"先初始化、后加载"这两步封装起来自动完成。

仓库中的 wrapper 文件内容如下：

# This is a wrapper of the upstream `./upstream/FindCUDA.cmake` that # automatically includes `./upstream/CMakeInitializeConfigs.cmake` before # `./upstream/FindCUDA.cmake`. The `CMakeInitializeConfigs.cmake`, which is # absent in old CMake versions, creates some necessary variables for the later # to run. # See ./README.md for details. set(UPSTREAM_FIND_CUDA_DIR "${CMAKE_CURRENT_LIST_DIR}/upstream/") include("${UPSTREAM_FIND_CUDA_DIR}/FindCUDA.cmake")

（见 cmake/Modules_CUDA_fix/FindCUDA.cmake。）文件头注释与 README 保持一致的描述：wrapper 负责把upstream/CMakeInitializeConfigs.cmake的加载放在upstream/FindCUDA.cmake之前，为后者补齐在旧版 CMake 中缺失的变量；代码中用UPSTREAM_FIND_CUDA_DIR指向upstream/子目录后完成 include。文件路径基于CMAKE_CURRENT_LIST_DIR计算，保证无论 wrapper 从何处被 include，都能正确定位到upstream/。

wrapper 的第二层价值在于子模块（submodule）场景。README 特别说明：PyTorch 依赖的若干第三方子模块也需要这些修复，但我们无法去给子模块自身的CMakeLists.txt打补丁（也不能 patch 它们维护的 CMake 逻辑）。通过把带修复的模块放进本目录、并让整个构建把该目录加入模块搜索路径，子模块调用find_package(CUDA)时就会自然命中这份打过补丁的实现，从而"无感"获得修复，而无需改动子模块源码。

六、在 PyTorch 构建系统中的真实接入点

Modules_CUDA_fix 并非孤立存在，它被 PyTorch 的 CUDA 公共构建模块显式引用。在 cmake/public/cuda.cmake 的开头：

# sccache is only supported in CMake master and not in the newest official # release (3.11.3) yet. Hence we need our own Modules_CUDA_fix to enable sccache. list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR}/../Modules_CUDA_fix)

（见 cmake/public/cuda.cmake 第 8~10 行。）这段注释透露出一个重要的历史动机：PyTorch 需要借助 sccache/ccache 这类编译缓存工具来加速 CI 与日常构建，而相关支持当时只存在于 CMake master、官方最新发布版（注释提到 3.11.3）尚未包含——这与回移FindCUDA修复是同一类"领先官方发布、自备实现"的做法。

该目录被追加到CMAKE_MODULE_PATH后，其后的调用链顺理成章：

1. find_package(CUDA)（第 29 行）→ 命中本目录 wrapper，进而加载打过补丁的upstream/FindCUDA.cmake，获得CUDA_FOUND、CUDA_NVCC_EXECUTABLE等结果；
2. 若用户显式USE_CUDA=1却找不到 CUDA，则FATAL_ERROR；否则回退为警告并关闭CAFFE2_USE_CUDA（第 30~46 行）；
3. 随后走 CMake 原生 CUDA 路径：enable_language(CUDA)+find_package(CUDAToolkit REQUIRED)（第 49~62 行），并校验 nvcc 版本与头文件版本一致（第 64~127 行，含对 nvcc/头文件版本不一致的FATAL_ERROR诊断）；
4. 通过find_package(CUDNN)（第 189 行）定位 cuDNN，同样会经由包含本目录的模块搜索路径解析到同目录的 FindCUDNN.cmake。

顺带可见 PyTorch 对构建版本的强约束逻辑也在该文件中：CUDA_VERSION VERSION_LESS 12.6会直接报FATAL_ERROR（第 73~75 行）——这属于当前仓库源码反映的构建前提，与 Modules_CUDA_fix 的历史兼容定位互为补充：前者解决"旧 CMake + 新特性"的版本缝隙，后者约束"当代 CUDA 工具链"的版本下限。

七、维护约定：如何安全地升级 upstream 目录

既然是回移，就存在"上游又修了新 bug，如何同步"的维护问题。upstream/README.md（以及主 README 的收尾段落）给出了明确的约定：

• 需要更新upstream/下任何文件时，建议先向 CMake 主线仓库提交 PR（即把修复合入 CMake 上游的Modules/FindCUDA.cmake）；
• 修复被主线接受后，再回移（backport）到本目录，以保证对更早 CMake 版本的兼容性。

也就是说，PyTorch 希望本目录的内容始终与 CMake 主线保持"可追踪"的同源关系：先上游、后回移，避免仓库内长期维护一份偏离主线的分支实现。对于希望借鉴此做法的读者，这套工作流同样值得参考——维护任何"领先官方发布的自有补丁"时，都应保留与上游的同步通道，而不是让补丁在私有分支里慢慢腐化。

八、给二次开发者与源码阅读者的提示

把本文要点与代码阅读路径做一次收束：

• 快速定位：想验证"include 目录生成器表达式如何展开"，看 upstream/FindCUDA.cmake 第 1334~1341 行与第 1567~1570 行；想看编译期 NVCC 包装脚本的生成，看FindCUDA/子目录下的 run_nvcc.cmake；
• 快速定位 VS2017 差异：看第 539~545 行（路径分支）、第 1302~1310 行（ccbin_flags）与第 1693~1701 行（追加-ccbin）；
• 理解新旧 CMake 兼容层：cmake_initialize_per_config_variable的定义与用法分别见 upstream/CMakeInitializeConfigs.cmake 和 upstream/FindCUDA.cmake 第 535 行；
• 理解接入时序：CMAKE_MODULE_PATH的注入发生在 cmake/public/cuda.cmake 第 8~10 行，任何对调用顺序的疑问都从这里开始追踪。

若在自有项目中复刻本方案，需要关注的边界条件包括：生成器表达式的展开时机（configure 期 vsfile(GENERATE)生成期）、多配置生成器（VS / Xcode）下构建类型宏的延迟展开、MSVC 工具链目录随版本的布局迁移，以及"先 init 后 include"的顺序约束——这四点正是 Modules_CUDA_fix 全部设计细节所围绕的核心问题域。

九、结语

cmake/Modules_CUDA_fix表面上只是几段不起眼的 CMake 脚本，但它浓缩了一类颇具代表性的开源工程问题：如何在"必须支持的旧工具版本"与"上游刚修复的新能力"之间架桥。PyTorch 的答案是把上游修复连同其新依赖一起回移进仓库，再用一层薄薄的 wrapper 解决装载顺序与子模块不可改动两大约束，最终通过CMAKE_MODULE_PATH无缝接入真实构建。理解这层机制，不仅能帮你读懂 PyTorch 的 CUDA 配置日志中那些"FindCUDA 相关"的细节，也能为其他遇到"官方发布滞后于需求"的 C/C++ 项目提供一套可复制的处理范式。

【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch