尧图网页设计 
Nixpkgs CUDA 支持完全指南包集合、构建配置与容器化使用的源码级解析【免费下载链接】nixpkgsNix Packages collection NixOS项目地址: https://gitcode.com/GitHub_Trending/ni/nixpkgsCUDACompute Unified Device Architecture是 NVIDIA 推出的并行计算平台与编程接口广泛用于高性能计算HPC和机器学习ML场景。本文以 Nixpkgs 官方文档 doc/languages-frameworks/cuda.section.md 为核心结合 Nixpkgs 仓库中 CUDA 模块的真实源码系统讲解 CUDA 包集合package sets的组织方式、如何为 Nixpkgs 配置 CUDA 支持、如何在包表达式中使用 CUDA 库、如何通过pkgsCuda与pkgsForCudaArch变体按架构选择构建产物以及如何在 Docker/Podman 容器中启用 CUDA。读完本文你将掌握从导入带 CUDA 配置的 Nixpkgs到写出可复用 CUDA 包表达式再到容器内运行 GPU 工作负载的完整实战路径并理解其背后的固定点fixed-point与包集合泄漏package set leakage实现原理。CUDA 包集合CUDA Package Sets的组织与命名约定在 Nixpkgs 中凡是 NVIDIA 提供的、依赖 CUDA 的包如libcublas、cudnn、tensorrt、nccl通常都被收纳进独立的CUDA package sets。Nixpkgs 为不同的 CUDA 发行版提供了多个相互独立、可并存的包集合顶层属性按以下三种命名约定暴露cudaPackages_x_y针对某个具体 CUDA 发行版的主版本.次版本包集合其中x、y分别是 CUDA 发行版的主、次版本号cudaPackages_x仅主版本命名的别名指向该主版本系列中被广泛支持的那个主次版本包集合cudaPackages不带版本号的别名指向主版本别名的最终目标即最新被广泛支持的 CUDA 发行版也被称为默认 CUDA 包集合。官方强烈建议优先使用不带版本号的cudaPackages。虽然版本化包集合如cudaPackages_12_8始终可用但它们会被周期性移除长期依赖会带来维护风险。命名约定背后的两个关键事实是最新不等于默认。别名并不机械地跟随 CUDA 官方最新版本而是跟随核心生态能正常构建的版本。例如若cudaPackages_12_9是 12.x 系列最新版但 OpenCV、ONNX Runtime 等核心库用它构建失败那么cudaPackages_12可能回退到cudaPackages_12_8同理若cudaPackages_13_1是最新版但 PyTorch、Torch Vision 等核心库构建失败cudaPackages可能回退指向cudaPackages_12。当前仓库的真实状态在 pkgs/top-level/all-packages.nix 中可以看到别名与包集合的实例化逻辑——cudaPackages_12 cudaPackages_12_9、cudaPackages_13 cudaPackages_13_3、cudaPackages recurseIntoAttrs cudaPackages_12即当前默认包集合是 CUDA 12.9且只有默认集合启用了递归求值见下文贡献部分对recurseForDerivations的说明。包集合的定义与清单manifests驱动机制所有 CUDA 包集合的实体都定义在 pkgs/top-level/cuda-packages.nix 中。当前仓库同时维护了cudaPackages_12_6、cudaPackages_12_8、cudaPackages_12_9、cudaPackages_13_0、cudaPackages_13_1、cudaPackages_13_2、cudaPackages_13_3、cudaPackages_13_4共 8 个版本化集合每个集合都通过mkCudaPackages调用 pkgs/development/cuda-modules/default.nix并传入一个manifests属性集——它由_cuda.lib.selectManifests manifestVersions从 NVIDIA 官方 redistributable 清单中选出对应版本。从源码可以看到每个集合为各可再分发组件挑选的具体版本。例如cudaPackages_12_8使用cuda 12.8.1、cudnn 9.22.0、tensorrt 10.16.1而cudaPackages_13_0使用cuda 13.0.3。更值得注意的是清单选择是条件化的cudnn与tensorrt会根据backendStdenv.hasJetsonCudaCapability、hostPlatform.isAarch64以及是否请求了 pre-Thor Jetson 能力hasPreThorJetsonCudaCapability来切换版本例如 Jetson 平台用cudnn 9.13.0、tensorrt 10.7.0这是因为 NVIDIA 对不同平台的支持周期并不一致。所有已支持可再分发组件的清单redistrib_*.json与对应 README 都存放在 pkgs/development/cuda-modules/_cuda/manifests 下。为 Nixpkgs 配置 CUDA 支持CUDA 支持在 Nixpkgs 中默认不开启。要在自己的配置中启用需要以类似下面的方式导入 Nixpkgs{ pkgs }: { allowUnfreePredicate pkgs._cuda.lib.allowUnfreeCudaPredicate; cudaCapabilities [ target-architectures ]; cudaForwardCompat true; cudaSupport true; }四个配置项的核心语义如下allowUnfreePredicate/allowUnfree绝大多数 CUDA 包都是 unfree 的受 NVIDIA 许可约束二者必须设置其一否则求值会因许可被拒。pkgs._cuda.lib.allowUnfreeCudaPredicate是一个预置谓词见 pkgs/development/cuda-modules/_cuda/lib/cuda.nix它对包的meta.license逐一检查——若为自由许可或属于nvidiaCuda、nvidiaCudaRedist等 NVIDIA 许可集合则放行新版复合许可带licenseType字段与旧版许可列表两种形式都被兼容处理。cudaSupport布尔开关供包表达式按条件启用 CUDA 专属功能是支持可编译/不可编译 CUDA 两用包如 OpenCV、PyTorch的标准开关。cudaCapabilitiesCUDA 能力compute capability列表例如面向 Ada Lovelace GPU 构建可设置cudaCapabilities [ 8.9 ];。包集合可以用它来控制设备代码生成启用架构专属优化、减少设备代码以加速编译、或精简闭包体积。cudaForwardCompat布尔值决定是否为未来硬件启用 PTX 前向兼容支持。默认能力集的推导逻辑源码级若不显式提供cudaCapabilities其默认值由每个包集合按 CUDA 版本自行计算。计算过程贯穿两个文件pkgs/development/cuda-modules/_cuda/db/bootstrap/cuda.nix 中的cudaCapabilityToInfo维护了每个能力如8.9、9.0a的元信息archName微架构名、minCudaMajorMinorVersion/maxCudaMajorMinorVersion支持该能力的最小/最大 CUDA 版本区间、isJetson是否 Jetson 嵌入式设备、isArchitectureSpecific是否为a后缀的架构专属特性集、isFamilySpecific是否为f后缀的家族专属特性集、dontDefaultAfterCudaMajorMinorVersion从哪个 CUDA 版本起不再默认构建通常对齐 TensorRT 放弃该架构的时间点。pkgs/development/cuda-modules/_cuda/lib/cuda.nix 中的_cudaCapabilityIsDefault定义默认资格能力必须是**基线baseline**能力即非 Jetson、非架构专属、非家族专属且尚未超过dontDefaultAfterCudaMajorMinorVersion阈值。然后由 pkgs/development/cuda-modules/backendStdenv/default.nix 先过滤出当前 CUDA 版本真正支持的能力supportedCudaCapabilities再进一步过滤出默认能力集defaultCudaCapabilities若用户显式给出cudaCapabilities则直接采用用户值。这一机制直接对应官方文档中的两条重要警示Jetson 家族能力默认不被构建例如8.7Jetson Orin属于isJetson true的能力见cuda.nix中8.7条目10.1Thor、11.0CUDA 13 的 Thor同样被标记为 Jetson。非基线特性集默认不被构建如9.0aHopper 专属特性集、10.0fBlackwell 家族专属特性集分别被isArchitectureSpecific/isFamilySpecific标记。需要这些能力时必须显式写入cudaCapabilities。在 pkgs/development/cuda-modules/backendStdenv/default.nix 中还有一组严格的求值断言assertion请求未知能力、请求对当前 CUDA 版本过老或过新的能力都会直接报错请求 Jetson 能力要求宿主平台是aarch64-linuxpre-SBSApre-ThorJetson 能力必须独占整个能力列表且要求 redistributable 系统为linux-aarch64而 post-SBSA Jetson 能力要求linux-sbsa。支持的 GPU 与宿主编译器数据库cudaCapabilityToInfo同时充当CUDA 版本 × 能力的支持矩阵。从当前仓库数据可以整理出以下代表性映射能力、微架构、最低 CUDA 版本CUDA 能力微架构最低 CUDA备注3.5/3.7Kepler10.0最高 11.85.0/5.2Maxwell10.0最高 12.96.0/6.1Pascal10.0最高 12.912.4 起不再默认7.0Volta10.0最高 12.97.2Volta10.0Jetson最高 12.27.5Turing10.0含 RTX 20 系列、Tesla T48.0/8.6Ampere11.2含 A100、RTX 30 系列8.7Ampere11.4Jetson Orin8.9Ada11.8含 RTX 40909.0/9.0aHopper11.8 / 12.0a为架构专属10.0/10.0aBlackwell12.710.0f需要 12.910.3/10.3aBlackwell12.9B30011.0/11.0aBlackwell13.0Jetson ThorCUDA 1312.0/12.0aBlackwell12.8含 RTX 5090GB20212.1/12.1aBlackwell12.9DGX Spark宿主编译器支持则由 pkgs/development/cuda-modules/_cuda/db/bootstrap/nvcc.nix 中的nvccCompatibilities数据库给出它按 CUDA 主次版本记录 NVCC 支持的 GCC / Clang 主版本区间例如 CUDA 12.6 支持 GCC 6–13、Clang 7–18CUDA 12.8 支持 GCC 6–14、Clang 7–19CUDA 13.4 支持 GCC 6–16、Clang 7–22。这些约束不适用于 Jetson。backendStdenv正是依据该数据库在构建时挑选兼容的宿主编译器优先复用当前 stdenv必要时从gccNStdenv/llvmPackages_N.stdenv中寻找可用版本并用stdenvAdapters.useLibsFrom沿用当前 stdenv 的libstdc以避免GLIBCXX_* not found链接错误。修改与扩展 CUDA 包集合包集合的内部构造一个 CUDA 包集合是通过对 pkgs/development/cuda-modules/default.nix 执行callPackage创建的传入包含各可再分发组件版本的manifests属性集。可再分发redistributable包由buildRedist辅助函数统一构建实现在 pkgs/development/cuda-modules/buildRedist/default.nix 中它会从 manifest 中挑选最通用的发布形态优先source其次linux-all再按hostRedistSystem选择具体系统并基于backendStdenv.mkDerivation构造派生式同时挂接autoAddCudaCompatRunpath、autoAddDriverRunpath、autoPatchelfHook、markForCudatoolkitRootHook、removeStubsFromRunpathHook等 CUDA 专属 setup hookhook 的实现分别位于 pkgs/development/cuda-modules/packages/autoAddCudaCompatRunpath、pkgs/development/cuda-modules/packages/markForCudatoolkitRootHook 等目录。_cuda包集合之外的固定点CUDA 包集合的大部分基础设施通过顶层属性集_cuda暴露它在 pkgs/top-level/all-packages.nix 中被定义为包集合之外的固定点。既然_cuda是固定点对它的修改就必须经由其extend属性进行。警示_cuda开头的下划线表明它是实现细节其稳定性与 API 不提供任何保证仅面向有经验的外部用户开放以便创建或修改 CUDA 包集合。对于包表达式的常规外部修改应使用overrideAttrs。注意_cuda早期曾暴露fixups一个把pname映射到callPackage兼容表达式的属性集用于在通用可再分发构建器结果上追加overrideAttrs。该功能已被移除取而代之的是为每个可再分发包提供完整包表达式以确保包集合成员身份在各 CUDA 版本、平台和配置间保持一致。用_cuda.extensions批量修改所有版本的包集合CUDA 包集合本身是 scope提供标准的overrideScope用于覆盖单个集合内的包属性。但更强大的机制是_cuda.extensions——一个受pythonPackagesExtensions启发的扩展列表会被应用到每个版本的 CUDA 包集合上无需知道集合名称、也无需逐一枚举修改。例如以下 overlay 可以在所有 CUDA 包集合中禁用cuda_compatfinal: prev: { _cuda prev._cuda.extend ( _: prevAttrs: { extensions prevAttrs.extensions [ (_: _: { cuda_compat null; }) ]; } ); }在 pkgs/development/cuda-modules/default.nix 中可以看到这些扩展如何被消费composedExtensions composeManyExtensions (optionals config.allowAliases [ aliases ] _cuda.extensions)随后通过lib.makeScopeWithSplicing构造出最终的cudaPackagesscopef extends composedExtensions cudaPackagesFixedPoint。在包表达式中使用cudaPackages要在包表达式中使用一个或多个 CUDA 包首先给表达式增加cudaPackages参数如果 CUDA 支持是可选的再增加config与cudaSupport参数{ config, cudaSupport ? config.cudaSupport, cudaPackages, }: package-expression官方同时强烈建议在派生的构建参数中设置以下两项{ __structuredAttrs true; strictDeps true; }这两项设置确保 CUDA 的各个 setup hook例如自动修补 RUNPATH、设置 CUDA 根目录能按预期工作。从 pkgs/development/cuda-modules/default.nix 的源码结构看可再分发包的构建完全依赖backendStdenv与这些 hook 的配合因此脱离标准构建阶段如在devShell中手工调用阶段很容易踩坑——这也是官方在使用cudaPackages一节开头特别给出的警示。当使用callPackage时可以传入不同的包集合变体例如某个包需要特定 CUDA 版本{ mypkg callPackage { cudaPackages cudaPackages_12_6; }; }警示为单个包覆盖 CUDA 包集合可能引入不一致——该覆盖不会影响其直接或间接依赖。结果很容易出现包本身用一套 CUDA 包集合、其依赖用另一套的混乱局面。如果可能官方建议全局修改默认 CUDA 包集合以保证环境一致性。Nixpkgs CUDA 变体cudaPackages.pkgs、pkgsCuda与pkgsForCudaArchNixpkgs CUDA 变体的存在意义主要是让用户能按属性路径直接挑选带 CUDA 的包而不必改动导入 Nixpkgs 时的config。例如pkgsForCudaArch集合允许你以pkgsForCudaArch.sm_89.opencv直接访问为 Ada Lovelace GPU 编译的 OpenCV。警示Nixpkgs 变体并非免费——每个变体都需要重新求值一次 Nixpkgs。在可能的情况下应只导入一次 Nixpkgs 并带上所需配置。三个变体的实现都集中在 pkgs/top-level/variants.nix 中cudaPackages.pkgs消灭包集合泄漏每个 CUDA 包集合都有一个pkgs属性它是一个把当前 CUDA 包集合设为默认的 Nixpkgs 变体。这样设计的首要目的是避免包集合泄漏package set leakage——即非默认包集合的成员直接或传递地依赖上默认包集合的成员。值得注意的是官方明确说明包集合泄漏是 Nixpkgs 中的普遍问题并不局限于 CUDA 包集合。从 pkgs/development/cuda-modules/default.nix 可以看到具体实现构造pkgs时若当前集合的 manifest 与默认集合含主版本别名、无版本别名完全一致则直接透传pkgs一个省去重新实例化的速度优化否则执行pkgs.extend把cudaPackages_x_y、cudaPackages_x、cudaPackages三个名字都指回当前正在构造的集合并置recurseForDerivations false。由此带来的额外好处是用非默认版本 CUDA 构建包变得和访问属性一样简单。例如cudaPackages_12_8.pkgs.opencv直接给出基于 CUDA 12.8 构建的 OpenCV而不必手动pkgs.extend。pkgsCuda默认能力的 CUDA 开关pkgsCuda是配置为cudaSupport true;且rocmSupport false的 Nixpkgs 变体用于便捷地访问以默认 CUDA 能力集配置的 Nixpkgs。其实现见 pkgs/top-level/variants.nix对应地pkgsRocm是反过来的镜像配置。pkgsForCudaArch按架构精确构建pkgsForCudaArch把每个 CUDA 架构名如sm_89对应 Ada Lovelace、sm_90a对应 Hopper 架构专属特性集映射到恰好支持该架构的 Nixpkgs 变体。例如pkgsForCudaArch.sm_89是pkgs的扩展并在config中设置{ cudaSupport true; cudaCapabilities [ 8.9 ]; cudaForwardCompat false; }注意在pkgsForCudaArch中cudaForwardCompat被置为false因为每个变体只支持恰好一个 CUDA 架构此外部分架构如sm_90a这类架构专属特性集本身就无法与前向兼容同时使用。从 pkgs/top-level/variants.nix 的实现可见pkgsForCudaArch由lib.listToAttrs对_cuda.db.cudaCapabilityToInfo中全部能力遍历生成每个条目名为_cuda.lib.mkRealArchitecture cudaCapability值为配置了cudaSupport true; cudaCapabilities [ cudaCapability ]; cudaForwardCompat false;的 Nixpkgs 实例。因此pkgsForCudaArch.sm_89.python3Packages.torch即可直接拿到为 Ada Lovelace 构建的 PyTorch。警示并非每个 CUDA 版本都支持每个架构例如 Blackwellsm_100的支持自 CUDA 12.8 才加入。假设默认 CUDA 包集合是 CUDA 12.6那么pkgsForCudaArch.sm_100这个变体就是无用的——pkgsForCudaArch.sm_100.opencv或pkgsForCudaArch.sm_100.python3Packages.torch会尝试为 CUDA 12.6 所不认识的sm_100生成代码。此时应改用pkgsForCudaArch.sm_100.cudaPackages_12_8.pkgs即组合本节介绍的两种机制。在 Docker / Podman 容器中启用 CUDA在容器里运行 CUDA 工作负载官方推荐的机制是 NVIDIA Container Toolkit。在 NixOS 上启用方式如下{ hardware.nvidia-container-toolkit.enable true; }这会自动启用一个服务基于自动检测到的硬件生成 CDI 规范位于/var/run/cdi/nvidia-container-toolkit.json。可以这样检查该服务$ systemctl status nvidia-container-toolkit-cdi-generator.service注意取决于系统里已经启用的其他设置可能需要重启机器CDI 生成器才能在开机时生成有效的 CDI 规范。一旦开机时生成了有效的 CDI 规范Podman 与 Docker 25只要传入--device标志即可使用该规范$ podman run --rm -it --devicenvidia.com/gpuall ubuntu:latest nvidia-smi -L GPU 0: NVIDIA GeForce RTX 4090 (UUID: REDACTED) GPU 1: NVIDIA GeForce RTX 2080 SUPER (UUID: REDACTED)$ docker run --rm -it --devicenvidia.com/gpuall ubuntu:latest nvidia-smi -L GPU 0: NVIDIA GeForce RTX 4090 (UUID: REDACTED) GPU 1: NVIDIA GeForce RTX 2080 SUPER (UUID: REDACTED)可以查看/var/run/cdi/nvidia-container-toolkit.json中为自动检测到的硬件生成的全部标识符$ nix run nixpkgs#jq -- -r .devices[].name /var/run/cdi/nvidia-container-toolkit.json 0 1 all指定暴露给容器的设备通过使用 CDI 规范中的标识符可以选择将哪些设备暴露给容器$ podman run --rm -it --devicenvidia.com/gpu0 ubuntu:latest nvidia-smi -L GPU 0: NVIDIA GeForce RTX 4090 (UUID: REDACTED)多卡环境下可以重复--device参数来逐个挑选要暴露的 GPU$ podman run --rm -it --devicenvidia.com/gpu0 --devicenvidia.com/gpu1 ubuntu:latest nvidia-smi -L GPU 0: NVIDIA GeForce RTX 4090 (UUID: REDACTED) GPU 1: NVIDIA GeForce RTX 2080 SUPER (UUID: REDACTED)注意默认情况下NVIDIA Container Toolkit 使用 GPU 索引来标识具体设备。可以通过 NixOS 属性hardware.nvidia-container-toolkit.device-name-strategy更改设备标识方式。在 docker-compose 中使用docker-compose环境同样可以暴露 GPU。一个完整的docker-compose.yaml示例如下services: some-service: image: ubuntu:latest command: sleep infinity deploy: resources: reservations: devices: - driver: cdi device_ids: - nvidia.com/gpuall同样也可以挑选具体设备services: some-service: image: ubuntu:latest command: sleep infinity deploy: resources: reservations: devices: - driver: cdi device_ids: - nvidia.com/gpu0 - nvidia.com/gpu1贡献指南维护 CUDA 包集合与编写测试警告本节属于进行中的文档欢迎通过 GitHub Issues 联系NixOS/cuda-maintainers反馈。包集合维护与 CUDA redistributablesCUDA Toolkit 是旨在提供 CUDA 加速应用开发环境的库与软件套件。在 CUDA 11.4 之前NVIDIA 只提供数 GB 大小的 runfile 安装器从 CUDA 11.4 起NVIDIA 开始提供CUDA redistributablesCUDA-redist——便于下游项目分发的独立 CUDA Toolkit 组件这些组件即存在于cudaPackages包集合中。虽然单体 runfile 安装器已不再提供但cudaPackages.cudatoolkit仍提供了一个用symlinkJoin拼合出来的近似产物便于兼容常见库。官方明确不建议使用cudaPackages.cudatoolkit所有新项目都应改用cudaPackages中的 CUDA redistributables后者更易于维护和更新。更新 redistributables每当新的 redistributable manifest 发布时查看 pkgs/development/cuda-modules/_cuda/manifests 下对应组件的README.md获取 vendoring manifest 所需的 URL更新 pkgs/top-level/cuda-packages.nix 中每个 CUDA 包集合使用的 manifest 版本更新 pkgs/development/cuda-modules/packages 中的包表达式。更新包表达式通常意味着针对新版本增加条件修复如新增或移除的依赖为新包增加包表达式更新passthru.brokenConditions与passthru.badPlatformsConditions中的各种约束例如新版本移除对某些架构的支持。更新支持的编译器与 GPU更新 pkgs/development/cuda-modules/_cuda/db/bootstrap/nvcc.nix 中的nvccCompatibilities纳入最新的 NVCC 版本及任何新支持的宿主编译器更新 pkgs/development/cuda-modules/_cuda/db/bootstrap/cuda.nix 中的cudaCapabilityToInfo纳入新版 CUDA 支持的 GPU。更新 CUDA 包集合注意更换默认 CUDA 包集合应放在独立的 PR 中进行以便留出额外测试时间。警告正如cudaPackages.pkgs一节所述当前对包集合泄漏的修复方式是为每个非默认 CUDA 包集合创建新的 Nixpkgs 实例。因此应限制设置recurseForDerivations true的 CUDA 包集合数量lib.recurseIntoAttrs应只应用于默认 CUDA 包集合对应 pkgs/top-level/all-packages.nix 中的cudaPackages recurseIntoAttrs cudaPackages_12;。更新流程如下在 pkgs/top-level/cuda-packages.nix 中加入新的cudaPackages_major_minor包集合并在 pkgs/top-level/all-packages.nix 中继承它成功构建新包集合的闭包必要时更新 pkgs/development/cuda-modules/packages 中的表达式。常见失败与对策如下无法……发生在……原因解决方案备注找到头文件configurePhase或buildPhase缺少对dev输出的依赖补上缺失依赖dev输出通常包含头文件找到库configurePhase缺少对dev输出的依赖补上缺失依赖dev输出通常包含 CMake 配置文件找到库buildPhase或patchelf缺少对lib或static输出的依赖补上缺失依赖lib或static输出通常包含库文件注意有两个工具派生式可简化包集合更新的测试cudaPackages.tests.redists-unpacked每个可再分发包的src解包后用symlinkJoin拼合cudaPackages.tests.redists-installed每个可再分发包的每个输出用symlinkJoin拼合。两者实现分别位于 pkgs/development/cuda-modules/packages/tests/redists-unpacked.nix 与 pkgs/development/cuda-modules/packages/tests/redists-installed.nix。运行产物失败的排查是最棘手的它通常是上述多种问题的组合典型场景是某库尝试加载/打开一个它依赖、却没有声明在DT_NEEDED段中的库。可按以下顺序调试首先确认依赖已通过autoAddDriverRunpath打过补丁对应 hook 见 pkgs/development/cuda-modules/packages/autoAddCudaCompatRunpath 等若仍失败尝试用nixGL或类似包装工具运行应用若这样能运行则大概率是应用试图加载不在二进制RPATH/RUNPATH中的库。编写测试警示passthru.testers与passthru.tests的存在应视为实现细节它们不是公开或稳定的接口。一般来说passthru中有两个用于构建和运行 CUDA 包测试的属性集passthru.testers和passthru.tests。每个属性集都可以再含一个名为cuda的子属性集用于存放 CUDA 专属派生式——把 CUDA 专属派生式与支持多种实现如 OpenCL、ROCm 等或不同许可证的通用派生式可参考magma包分开。注意派生式嵌套在cuda属性下源于一个 OfBorg 怪癖若求值失败例如因 unfree 许可整个外层属性集都会被丢弃导致集合中其他属性无法被发现、求值或构建。passthru.testers沙箱外测试加入passthru.testers的属性是产生可执行文件、运行测试的派生式。生成的可执行文件应当自行负责设置环境、创建临时目录等注册为派生式的meta.mainProgram以便直接运行。注意始终需要 CUDA 的 tester 应放在passthru.testers.cuda通用的放在passthru.testers。passthru.testers允许在 Nix 沙箱外运行测试其价值在于可用nixGL或nix-gl-host等工具包装后在非 NixOS 系统上运行可处理难以沙箱化的网络访问模式可自由产生非确定性输出如计时信息。passthru.tests沙箱内测试加入passthru.tests的属性是在 Nix 沙箱内运行测试的派生式。测试应当尽量复用passthru.testers生成的可执行文件避免重复测试逻辑包含requiredSystemFeatures [ cuda ];若是通用测试可按cudaSupport的值条件化确保只暴露了 CUDA 能力 GPU 的系统上运行。注意始终需要 CUDA 的测试应放在passthru.tests.cuda通用的放在passthru.tests。沙箱内测试适合确定性的用例如检查退出码且能够在沙箱中提供全部所需资源。小结Nixpkgs 的 CUDA 支持是一个由清单驱动的包集合 固定点基础设施 专属 setup hook构成的完整体系通过cudaPackages、cudaPackages_x、cudaPackages_x_y三级命名约定组织版本通过cudaSupport/cudaCapabilities/cudaForwardCompat等配置项控制构建行为通过_cuda.extensions实现跨所有版本的批量定制通过cudaPackages.pkgs、pkgsCuda、pkgsForCudaArch提供免改 config 的按架构访问路径并借助 NVIDIA Container Toolkit 与 CDI 规范让 Docker/Podman 容器平滑接入 GPU。理解这些机制不仅有助于正确使用也为深入 Nixpkgs 的 CUDA 维护与测试工作打下了基础。【免费下载链接】nixpkgsNix Packages collection NixOS项目地址: https://gitcode.com/GitHub_Trending/ni/nixpkgs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Nixpkgs CUDA 支持完全指南：包集合、构建配置与容器化使用的源码级解析
Nixpkgs CUDA 支持完全指南包集合、构建配置与容器化使用的源码级解析【免费下载链接】nixpkgsNix Packages collection NixOS项目地址: https://gitcode.com/GitHub_Trending/ni/nixpkgsCUDACompute Unified Device Architecture是 NVIDIA 推出的并行计算平台与编程接口广泛用于高性能计算HPC和机器学习ML场景。本文以 Nixpkgs 官方文档 doc/languages-frameworks/cuda.section.md 为核心结合 Nixpkgs 仓库中 CUDA 模块的真实源码系统讲解 CUDA 包集合package sets的组织方式、如何为 Nixpkgs 配置 CUDA 支持、如何在包表达式中使用 CUDA 库、如何通过pkgsCuda与pkgsForCudaArch变体按架构选择构建产物以及如何在 Docker/Podman 容器中启用 CUDA。读完本文你将掌握从导入带 CUDA 配置的 Nixpkgs到写出可复用 CUDA 包表达式再到容器内运行 GPU 工作负载的完整实战路径并理解其背后的固定点fixed-point与包集合泄漏package set leakage实现原理。CUDA 包集合CUDA Package Sets的组织与命名约定在 Nixpkgs 中凡是 NVIDIA 提供的、依赖 CUDA 的包如libcublas、cudnn、tensorrt、nccl通常都被收纳进独立的CUDA package sets。Nixpkgs 为不同的 CUDA 发行版提供了多个相互独立、可并存的包集合顶层属性按以下三种命名约定暴露cudaPackages_x_y针对某个具体 CUDA 发行版的主版本.次版本包集合其中x、y分别是 CUDA 发行版的主、次版本号cudaPackages_x仅主版本命名的别名指向该主版本系列中被广泛支持的那个主次版本包集合cudaPackages不带版本号的别名指向主版本别名的最终目标即最新被广泛支持的 CUDA 发行版也被称为默认 CUDA 包集合。官方强烈建议优先使用不带版本号的cudaPackages。虽然版本化包集合如cudaPackages_12_8始终可用但它们会被周期性移除长期依赖会带来维护风险。命名约定背后的两个关键事实是最新不等于默认。别名并不机械地跟随 CUDA 官方最新版本而是跟随核心生态能正常构建的版本。例如若cudaPackages_12_9是 12.x 系列最新版但 OpenCV、ONNX Runtime 等核心库用它构建失败那么cudaPackages_12可能回退到cudaPackages_12_8同理若cudaPackages_13_1是最新版但 PyTorch、Torch Vision 等核心库构建失败cudaPackages可能回退指向cudaPackages_12。当前仓库的真实状态在 pkgs/top-level/all-packages.nix 中可以看到别名与包集合的实例化逻辑——cudaPackages_12 cudaPackages_12_9、cudaPackages_13 cudaPackages_13_3、cudaPackages recurseIntoAttrs cudaPackages_12即当前默认包集合是 CUDA 12.9且只有默认集合启用了递归求值见下文贡献部分对recurseForDerivations的说明。包集合的定义与清单manifests驱动机制所有 CUDA 包集合的实体都定义在 pkgs/top-level/cuda-packages.nix 中。当前仓库同时维护了cudaPackages_12_6、cudaPackages_12_8、cudaPackages_12_9、cudaPackages_13_0、cudaPackages_13_1、cudaPackages_13_2、cudaPackages_13_3、cudaPackages_13_4共 8 个版本化集合每个集合都通过mkCudaPackages调用 pkgs/development/cuda-modules/default.nix并传入一个manifests属性集——它由_cuda.lib.selectManifests manifestVersions从 NVIDIA 官方 redistributable 清单中选出对应版本。从源码可以看到每个集合为各可再分发组件挑选的具体版本。例如cudaPackages_12_8使用cuda 12.8.1、cudnn 9.22.0、tensorrt 10.16.1而cudaPackages_13_0使用cuda 13.0.3。更值得注意的是清单选择是条件化的cudnn与tensorrt会根据backendStdenv.hasJetsonCudaCapability、hostPlatform.isAarch64以及是否请求了 pre-Thor Jetson 能力hasPreThorJetsonCudaCapability来切换版本例如 Jetson 平台用cudnn 9.13.0、tensorrt 10.7.0这是因为 NVIDIA 对不同平台的支持周期并不一致。所有已支持可再分发组件的清单redistrib_*.json与对应 README 都存放在 pkgs/development/cuda-modules/_cuda/manifests 下。为 Nixpkgs 配置 CUDA 支持CUDA 支持在 Nixpkgs 中默认不开启。要在自己的配置中启用需要以类似下面的方式导入 Nixpkgs{ pkgs }: { allowUnfreePredicate pkgs._cuda.lib.allowUnfreeCudaPredicate; cudaCapabilities [ target-architectures ]; cudaForwardCompat true; cudaSupport true; }四个配置项的核心语义如下allowUnfreePredicate/allowUnfree绝大多数 CUDA 包都是 unfree 的受 NVIDIA 许可约束二者必须设置其一否则求值会因许可被拒。pkgs._cuda.lib.allowUnfreeCudaPredicate是一个预置谓词见 pkgs/development/cuda-modules/_cuda/lib/cuda.nix它对包的meta.license逐一检查——若为自由许可或属于nvidiaCuda、nvidiaCudaRedist等 NVIDIA 许可集合则放行新版复合许可带licenseType字段与旧版许可列表两种形式都被兼容处理。cudaSupport布尔开关供包表达式按条件启用 CUDA 专属功能是支持可编译/不可编译 CUDA 两用包如 OpenCV、PyTorch的标准开关。cudaCapabilitiesCUDA 能力compute capability列表例如面向 Ada Lovelace GPU 构建可设置cudaCapabilities [ 8.9 ];。包集合可以用它来控制设备代码生成启用架构专属优化、减少设备代码以加速编译、或精简闭包体积。cudaForwardCompat布尔值决定是否为未来硬件启用 PTX 前向兼容支持。默认能力集的推导逻辑源码级若不显式提供cudaCapabilities其默认值由每个包集合按 CUDA 版本自行计算。计算过程贯穿两个文件pkgs/development/cuda-modules/_cuda/db/bootstrap/cuda.nix 中的cudaCapabilityToInfo维护了每个能力如8.9、9.0a的元信息archName微架构名、minCudaMajorMinorVersion/maxCudaMajorMinorVersion支持该能力的最小/最大 CUDA 版本区间、isJetson是否 Jetson 嵌入式设备、isArchitectureSpecific是否为a后缀的架构专属特性集、isFamilySpecific是否为f后缀的家族专属特性集、dontDefaultAfterCudaMajorMinorVersion从哪个 CUDA 版本起不再默认构建通常对齐 TensorRT 放弃该架构的时间点。pkgs/development/cuda-modules/_cuda/lib/cuda.nix 中的_cudaCapabilityIsDefault定义默认资格能力必须是**基线baseline**能力即非 Jetson、非架构专属、非家族专属且尚未超过dontDefaultAfterCudaMajorMinorVersion阈值。然后由 pkgs/development/cuda-modules/backendStdenv/default.nix 先过滤出当前 CUDA 版本真正支持的能力supportedCudaCapabilities再进一步过滤出默认能力集defaultCudaCapabilities若用户显式给出cudaCapabilities则直接采用用户值。这一机制直接对应官方文档中的两条重要警示Jetson 家族能力默认不被构建例如8.7Jetson Orin属于isJetson true的能力见cuda.nix中8.7条目10.1Thor、11.0CUDA 13 的 Thor同样被标记为 Jetson。非基线特性集默认不被构建如9.0aHopper 专属特性集、10.0fBlackwell 家族专属特性集分别被isArchitectureSpecific/isFamilySpecific标记。需要这些能力时必须显式写入cudaCapabilities。在 pkgs/development/cuda-modules/backendStdenv/default.nix 中还有一组严格的求值断言assertion请求未知能力、请求对当前 CUDA 版本过老或过新的能力都会直接报错请求 Jetson 能力要求宿主平台是aarch64-linuxpre-SBSApre-ThorJetson 能力必须独占整个能力列表且要求 redistributable 系统为linux-aarch64而 post-SBSA Jetson 能力要求linux-sbsa。支持的 GPU 与宿主编译器数据库cudaCapabilityToInfo同时充当CUDA 版本 × 能力的支持矩阵。从当前仓库数据可以整理出以下代表性映射能力、微架构、最低 CUDA 版本CUDA 能力微架构最低 CUDA备注3.5/3.7Kepler10.0最高 11.85.0/5.2Maxwell10.0最高 12.96.0/6.1Pascal10.0最高 12.912.4 起不再默认7.0Volta10.0最高 12.97.2Volta10.0Jetson最高 12.27.5Turing10.0含 RTX 20 系列、Tesla T48.0/8.6Ampere11.2含 A100、RTX 30 系列8.7Ampere11.4Jetson Orin8.9Ada11.8含 RTX 40909.0/9.0aHopper11.8 / 12.0a为架构专属10.0/10.0aBlackwell12.710.0f需要 12.910.3/10.3aBlackwell12.9B30011.0/11.0aBlackwell13.0Jetson ThorCUDA 1312.0/12.0aBlackwell12.8含 RTX 5090GB20212.1/12.1aBlackwell12.9DGX Spark宿主编译器支持则由 pkgs/development/cuda-modules/_cuda/db/bootstrap/nvcc.nix 中的nvccCompatibilities数据库给出它按 CUDA 主次版本记录 NVCC 支持的 GCC / Clang 主版本区间例如 CUDA 12.6 支持 GCC 6–13、Clang 7–18CUDA 12.8 支持 GCC 6–14、Clang 7–19CUDA 13.4 支持 GCC 6–16、Clang 7–22。这些约束不适用于 Jetson。backendStdenv正是依据该数据库在构建时挑选兼容的宿主编译器优先复用当前 stdenv必要时从gccNStdenv/llvmPackages_N.stdenv中寻找可用版本并用stdenvAdapters.useLibsFrom沿用当前 stdenv 的libstdc以避免GLIBCXX_* not found链接错误。修改与扩展 CUDA 包集合包集合的内部构造一个 CUDA 包集合是通过对 pkgs/development/cuda-modules/default.nix 执行callPackage创建的传入包含各可再分发组件版本的manifests属性集。可再分发redistributable包由buildRedist辅助函数统一构建实现在 pkgs/development/cuda-modules/buildRedist/default.nix 中它会从 manifest 中挑选最通用的发布形态优先source其次linux-all再按hostRedistSystem选择具体系统并基于backendStdenv.mkDerivation构造派生式同时挂接autoAddCudaCompatRunpath、autoAddDriverRunpath、autoPatchelfHook、markForCudatoolkitRootHook、removeStubsFromRunpathHook等 CUDA 专属 setup hookhook 的实现分别位于 pkgs/development/cuda-modules/packages/autoAddCudaCompatRunpath、pkgs/development/cuda-modules/packages/markForCudatoolkitRootHook 等目录。_cuda包集合之外的固定点CUDA 包集合的大部分基础设施通过顶层属性集_cuda暴露它在 pkgs/top-level/all-packages.nix 中被定义为包集合之外的固定点。既然_cuda是固定点对它的修改就必须经由其extend属性进行。警示_cuda开头的下划线表明它是实现细节其稳定性与 API 不提供任何保证仅面向有经验的外部用户开放以便创建或修改 CUDA 包集合。对于包表达式的常规外部修改应使用overrideAttrs。注意_cuda早期曾暴露fixups一个把pname映射到callPackage兼容表达式的属性集用于在通用可再分发构建器结果上追加overrideAttrs。该功能已被移除取而代之的是为每个可再分发包提供完整包表达式以确保包集合成员身份在各 CUDA 版本、平台和配置间保持一致。用_cuda.extensions批量修改所有版本的包集合CUDA 包集合本身是 scope提供标准的overrideScope用于覆盖单个集合内的包属性。但更强大的机制是_cuda.extensions——一个受pythonPackagesExtensions启发的扩展列表会被应用到每个版本的 CUDA 包集合上无需知道集合名称、也无需逐一枚举修改。例如以下 overlay 可以在所有 CUDA 包集合中禁用cuda_compatfinal: prev: { _cuda prev._cuda.extend ( _: prevAttrs: { extensions prevAttrs.extensions [ (_: _: { cuda_compat null; }) ]; } ); }在 pkgs/development/cuda-modules/default.nix 中可以看到这些扩展如何被消费composedExtensions composeManyExtensions (optionals config.allowAliases [ aliases ] _cuda.extensions)随后通过lib.makeScopeWithSplicing构造出最终的cudaPackagesscopef extends composedExtensions cudaPackagesFixedPoint。在包表达式中使用cudaPackages要在包表达式中使用一个或多个 CUDA 包首先给表达式增加cudaPackages参数如果 CUDA 支持是可选的再增加config与cudaSupport参数{ config, cudaSupport ? config.cudaSupport, cudaPackages, }: package-expression官方同时强烈建议在派生的构建参数中设置以下两项{ __structuredAttrs true; strictDeps true; }这两项设置确保 CUDA 的各个 setup hook例如自动修补 RUNPATH、设置 CUDA 根目录能按预期工作。从 pkgs/development/cuda-modules/default.nix 的源码结构看可再分发包的构建完全依赖backendStdenv与这些 hook 的配合因此脱离标准构建阶段如在devShell中手工调用阶段很容易踩坑——这也是官方在使用cudaPackages一节开头特别给出的警示。当使用callPackage时可以传入不同的包集合变体例如某个包需要特定 CUDA 版本{ mypkg callPackage { cudaPackages cudaPackages_12_6; }; }警示为单个包覆盖 CUDA 包集合可能引入不一致——该覆盖不会影响其直接或间接依赖。结果很容易出现包本身用一套 CUDA 包集合、其依赖用另一套的混乱局面。如果可能官方建议全局修改默认 CUDA 包集合以保证环境一致性。Nixpkgs CUDA 变体cudaPackages.pkgs、pkgsCuda与pkgsForCudaArchNixpkgs CUDA 变体的存在意义主要是让用户能按属性路径直接挑选带 CUDA 的包而不必改动导入 Nixpkgs 时的config。例如pkgsForCudaArch集合允许你以pkgsForCudaArch.sm_89.opencv直接访问为 Ada Lovelace GPU 编译的 OpenCV。警示Nixpkgs 变体并非免费——每个变体都需要重新求值一次 Nixpkgs。在可能的情况下应只导入一次 Nixpkgs 并带上所需配置。三个变体的实现都集中在 pkgs/top-level/variants.nix 中cudaPackages.pkgs消灭包集合泄漏每个 CUDA 包集合都有一个pkgs属性它是一个把当前 CUDA 包集合设为默认的 Nixpkgs 变体。这样设计的首要目的是避免包集合泄漏package set leakage——即非默认包集合的成员直接或传递地依赖上默认包集合的成员。值得注意的是官方明确说明包集合泄漏是 Nixpkgs 中的普遍问题并不局限于 CUDA 包集合。从 pkgs/development/cuda-modules/default.nix 可以看到具体实现构造pkgs时若当前集合的 manifest 与默认集合含主版本别名、无版本别名完全一致则直接透传pkgs一个省去重新实例化的速度优化否则执行pkgs.extend把cudaPackages_x_y、cudaPackages_x、cudaPackages三个名字都指回当前正在构造的集合并置recurseForDerivations false。由此带来的额外好处是用非默认版本 CUDA 构建包变得和访问属性一样简单。例如cudaPackages_12_8.pkgs.opencv直接给出基于 CUDA 12.8 构建的 OpenCV而不必手动pkgs.extend。pkgsCuda默认能力的 CUDA 开关pkgsCuda是配置为cudaSupport true;且rocmSupport false的 Nixpkgs 变体用于便捷地访问以默认 CUDA 能力集配置的 Nixpkgs。其实现见 pkgs/top-level/variants.nix对应地pkgsRocm是反过来的镜像配置。pkgsForCudaArch按架构精确构建pkgsForCudaArch把每个 CUDA 架构名如sm_89对应 Ada Lovelace、sm_90a对应 Hopper 架构专属特性集映射到恰好支持该架构的 Nixpkgs 变体。例如pkgsForCudaArch.sm_89是pkgs的扩展并在config中设置{ cudaSupport true; cudaCapabilities [ 8.9 ]; cudaForwardCompat false; }注意在pkgsForCudaArch中cudaForwardCompat被置为false因为每个变体只支持恰好一个 CUDA 架构此外部分架构如sm_90a这类架构专属特性集本身就无法与前向兼容同时使用。从 pkgs/top-level/variants.nix 的实现可见pkgsForCudaArch由lib.listToAttrs对_cuda.db.cudaCapabilityToInfo中全部能力遍历生成每个条目名为_cuda.lib.mkRealArchitecture cudaCapability值为配置了cudaSupport true; cudaCapabilities [ cudaCapability ]; cudaForwardCompat false;的 Nixpkgs 实例。因此pkgsForCudaArch.sm_89.python3Packages.torch即可直接拿到为 Ada Lovelace 构建的 PyTorch。警示并非每个 CUDA 版本都支持每个架构例如 Blackwellsm_100的支持自 CUDA 12.8 才加入。假设默认 CUDA 包集合是 CUDA 12.6那么pkgsForCudaArch.sm_100这个变体就是无用的——pkgsForCudaArch.sm_100.opencv或pkgsForCudaArch.sm_100.python3Packages.torch会尝试为 CUDA 12.6 所不认识的sm_100生成代码。此时应改用pkgsForCudaArch.sm_100.cudaPackages_12_8.pkgs即组合本节介绍的两种机制。在 Docker / Podman 容器中启用 CUDA在容器里运行 CUDA 工作负载官方推荐的机制是 NVIDIA Container Toolkit。在 NixOS 上启用方式如下{ hardware.nvidia-container-toolkit.enable true; }这会自动启用一个服务基于自动检测到的硬件生成 CDI 规范位于/var/run/cdi/nvidia-container-toolkit.json。可以这样检查该服务$ systemctl status nvidia-container-toolkit-cdi-generator.service注意取决于系统里已经启用的其他设置可能需要重启机器CDI 生成器才能在开机时生成有效的 CDI 规范。一旦开机时生成了有效的 CDI 规范Podman 与 Docker 25只要传入--device标志即可使用该规范$ podman run --rm -it --devicenvidia.com/gpuall ubuntu:latest nvidia-smi -L GPU 0: NVIDIA GeForce RTX 4090 (UUID: REDACTED) GPU 1: NVIDIA GeForce RTX 2080 SUPER (UUID: REDACTED)$ docker run --rm -it --devicenvidia.com/gpuall ubuntu:latest nvidia-smi -L GPU 0: NVIDIA GeForce RTX 4090 (UUID: REDACTED) GPU 1: NVIDIA GeForce RTX 2080 SUPER (UUID: REDACTED)可以查看/var/run/cdi/nvidia-container-toolkit.json中为自动检测到的硬件生成的全部标识符$ nix run nixpkgs#jq -- -r .devices[].name /var/run/cdi/nvidia-container-toolkit.json 0 1 all指定暴露给容器的设备通过使用 CDI 规范中的标识符可以选择将哪些设备暴露给容器$ podman run --rm -it --devicenvidia.com/gpu0 ubuntu:latest nvidia-smi -L GPU 0: NVIDIA GeForce RTX 4090 (UUID: REDACTED)多卡环境下可以重复--device参数来逐个挑选要暴露的 GPU$ podman run --rm -it --devicenvidia.com/gpu0 --devicenvidia.com/gpu1 ubuntu:latest nvidia-smi -L GPU 0: NVIDIA GeForce RTX 4090 (UUID: REDACTED) GPU 1: NVIDIA GeForce RTX 2080 SUPER (UUID: REDACTED)注意默认情况下NVIDIA Container Toolkit 使用 GPU 索引来标识具体设备。可以通过 NixOS 属性hardware.nvidia-container-toolkit.device-name-strategy更改设备标识方式。在 docker-compose 中使用docker-compose环境同样可以暴露 GPU。一个完整的docker-compose.yaml示例如下services: some-service: image: ubuntu:latest command: sleep infinity deploy: resources: reservations: devices: - driver: cdi device_ids: - nvidia.com/gpuall同样也可以挑选具体设备services: some-service: image: ubuntu:latest command: sleep infinity deploy: resources: reservations: devices: - driver: cdi device_ids: - nvidia.com/gpu0 - nvidia.com/gpu1贡献指南维护 CUDA 包集合与编写测试警告本节属于进行中的文档欢迎通过 GitHub Issues 联系NixOS/cuda-maintainers反馈。包集合维护与 CUDA redistributablesCUDA Toolkit 是旨在提供 CUDA 加速应用开发环境的库与软件套件。在 CUDA 11.4 之前NVIDIA 只提供数 GB 大小的 runfile 安装器从 CUDA 11.4 起NVIDIA 开始提供CUDA redistributablesCUDA-redist——便于下游项目分发的独立 CUDA Toolkit 组件这些组件即存在于cudaPackages包集合中。虽然单体 runfile 安装器已不再提供但cudaPackages.cudatoolkit仍提供了一个用symlinkJoin拼合出来的近似产物便于兼容常见库。官方明确不建议使用cudaPackages.cudatoolkit所有新项目都应改用cudaPackages中的 CUDA redistributables后者更易于维护和更新。更新 redistributables每当新的 redistributable manifest 发布时查看 pkgs/development/cuda-modules/_cuda/manifests 下对应组件的README.md获取 vendoring manifest 所需的 URL更新 pkgs/top-level/cuda-packages.nix 中每个 CUDA 包集合使用的 manifest 版本更新 pkgs/development/cuda-modules/packages 中的包表达式。更新包表达式通常意味着针对新版本增加条件修复如新增或移除的依赖为新包增加包表达式更新passthru.brokenConditions与passthru.badPlatformsConditions中的各种约束例如新版本移除对某些架构的支持。更新支持的编译器与 GPU更新 pkgs/development/cuda-modules/_cuda/db/bootstrap/nvcc.nix 中的nvccCompatibilities纳入最新的 NVCC 版本及任何新支持的宿主编译器更新 pkgs/development/cuda-modules/_cuda/db/bootstrap/cuda.nix 中的cudaCapabilityToInfo纳入新版 CUDA 支持的 GPU。更新 CUDA 包集合注意更换默认 CUDA 包集合应放在独立的 PR 中进行以便留出额外测试时间。警告正如cudaPackages.pkgs一节所述当前对包集合泄漏的修复方式是为每个非默认 CUDA 包集合创建新的 Nixpkgs 实例。因此应限制设置recurseForDerivations true的 CUDA 包集合数量lib.recurseIntoAttrs应只应用于默认 CUDA 包集合对应 pkgs/top-level/all-packages.nix 中的cudaPackages recurseIntoAttrs cudaPackages_12;。更新流程如下在 pkgs/top-level/cuda-packages.nix 中加入新的cudaPackages_major_minor包集合并在 pkgs/top-level/all-packages.nix 中继承它成功构建新包集合的闭包必要时更新 pkgs/development/cuda-modules/packages 中的表达式。常见失败与对策如下无法……发生在……原因解决方案备注找到头文件configurePhase或buildPhase缺少对dev输出的依赖补上缺失依赖dev输出通常包含头文件找到库configurePhase缺少对dev输出的依赖补上缺失依赖dev输出通常包含 CMake 配置文件找到库buildPhase或patchelf缺少对lib或static输出的依赖补上缺失依赖lib或static输出通常包含库文件注意有两个工具派生式可简化包集合更新的测试cudaPackages.tests.redists-unpacked每个可再分发包的src解包后用symlinkJoin拼合cudaPackages.tests.redists-installed每个可再分发包的每个输出用symlinkJoin拼合。两者实现分别位于 pkgs/development/cuda-modules/packages/tests/redists-unpacked.nix 与 pkgs/development/cuda-modules/packages/tests/redists-installed.nix。运行产物失败的排查是最棘手的它通常是上述多种问题的组合典型场景是某库尝试加载/打开一个它依赖、却没有声明在DT_NEEDED段中的库。可按以下顺序调试首先确认依赖已通过autoAddDriverRunpath打过补丁对应 hook 见 pkgs/development/cuda-modules/packages/autoAddCudaCompatRunpath 等若仍失败尝试用nixGL或类似包装工具运行应用若这样能运行则大概率是应用试图加载不在二进制RPATH/RUNPATH中的库。编写测试警示passthru.testers与passthru.tests的存在应视为实现细节它们不是公开或稳定的接口。一般来说passthru中有两个用于构建和运行 CUDA 包测试的属性集passthru.testers和passthru.tests。每个属性集都可以再含一个名为cuda的子属性集用于存放 CUDA 专属派生式——把 CUDA 专属派生式与支持多种实现如 OpenCL、ROCm 等或不同许可证的通用派生式可参考magma包分开。注意派生式嵌套在cuda属性下源于一个 OfBorg 怪癖若求值失败例如因 unfree 许可整个外层属性集都会被丢弃导致集合中其他属性无法被发现、求值或构建。passthru.testers沙箱外测试加入passthru.testers的属性是产生可执行文件、运行测试的派生式。生成的可执行文件应当自行负责设置环境、创建临时目录等注册为派生式的meta.mainProgram以便直接运行。注意始终需要 CUDA 的 tester 应放在passthru.testers.cuda通用的放在passthru.testers。passthru.testers允许在 Nix 沙箱外运行测试其价值在于可用nixGL或nix-gl-host等工具包装后在非 NixOS 系统上运行可处理难以沙箱化的网络访问模式可自由产生非确定性输出如计时信息。passthru.tests沙箱内测试加入passthru.tests的属性是在 Nix 沙箱内运行测试的派生式。测试应当尽量复用passthru.testers生成的可执行文件避免重复测试逻辑包含requiredSystemFeatures [ cuda ];若是通用测试可按cudaSupport的值条件化确保只暴露了 CUDA 能力 GPU 的系统上运行。注意始终需要 CUDA 的测试应放在passthru.tests.cuda通用的放在passthru.tests。沙箱内测试适合确定性的用例如检查退出码且能够在沙箱中提供全部所需资源。小结Nixpkgs 的 CUDA 支持是一个由清单驱动的包集合 固定点基础设施 专属 setup hook构成的完整体系通过cudaPackages、cudaPackages_x、cudaPackages_x_y三级命名约定组织版本通过cudaSupport/cudaCapabilities/cudaForwardCompat等配置项控制构建行为通过_cuda.extensions实现跨所有版本的批量定制通过cudaPackages.pkgs、pkgsCuda、pkgsForCudaArch提供免改 config 的按架构访问路径并借助 NVIDIA Container Toolkit 与 CDI 规范让 Docker/Podman 容器平滑接入 GPU。理解这些机制不仅有助于正确使用也为深入 Nixpkgs 的 CUDA 维护与测试工作打下了基础。【免费下载链接】nixpkgsNix Packages collection NixOS项目地址: https://gitcode.com/GitHub_Trending/ni/nixpkgs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考