企业官网建设流程全解析

CUDA Samples 完整实战指南：从源码构建、交叉编译到自动化测试（CUDA Toolkit 13.3）

【免费下载链接】cuda-samplesSamples for CUDA Developers which demonstrates features in CUDA Toolkit项目地址: https://gitcode.com/GitHub_Trending/cu/cuda-samples

本指南以 NVIDIA CUDA Samples 官方仓库的 README.md 为骨架，系统讲解如何获取、构建、安装与测试这套面向 CUDA 开发者的官方示例集合。本仓库随附 CUDA Toolkit 13.3，覆盖 C++ 与 Python 两套样例，读者学完后将能够独立完成 Linux / Windows 平台的本地构建、Tegra / QNX / DriveOS 平台的交叉编译、定制化安装，以及使用run_tests.py对全部样例做自动化冒烟测试。

一、仓库概览：C++ 与 Python 双轨并行的样例体系

CUDA Samples 是一套用于演示 CUDA Toolkit 各项特性的官方示例代码仓库（当前版本面向 CUDA Toolkit 13.3）。它不是CUDA 的验证套件：不覆盖运行时/驱动 API 的边角情况，也不用于性能基准测试（见 README.md 的 "Running All Samples as Tests" 一节），其定位是让开发者通过可运行、可修改的代码理解 CUDA 的编程模型与库 API。

从仓库根目录的 CMakeLists.txt 可以看出项目的最小构建骨架：

cmake_minimum_required(VERSION 3.20) project(cuda-samples LANGUAGES C CXX CUDA) find_package(CUDAToolkit REQUIRED) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CUDA_STANDARD 17) set(CMAKE_CUDA_ARCHITECTURES 75 80 86 87 89 90 100 110 120) include(cmake/InstallSamples.cmake) add_subdirectory(cpp)

几个值得注意的工程细节：

• 架构列表覆盖范围广：CMAKE_CUDA_ARCHITECTURES从75（Turing）一路列到120（Blackwell 后续架构），覆盖 Volta 之后的历代 GPU 架构，源码级佐证位于 CMakeLists.txt；
• 默认开启行号信息：默认编译带-lineinfo（便于 profiler 定位源码行），仅当开启调试时才替换为-G（见 CMakeLists.txt）；
• MSVC 专用预处理标志：Windows 上为 CUDA 编译增加-Xcompiler=/Zc:preprocessor，以满足 CUDA 13.2 起 CCCL 对标准预处理器的要求（对应 CHANGELOG.md 中 CUDA 13.2 条目）；
• C++ 与 Python 分目录组织：cpp/是传统 C++/CUDA 样例，python/是新增的 CUDA Python 样例；仓库根 CMakeLists.txt 只add_subdirectory(cpp)，Python 样例不参与 CMake 构建。

目录体系上，C++ 样例按主题划分为 10 个分区（由 cpp/CMakeLists.txt 中add_subdirectory的顺序可见）：

其中8_Platform_Specific/Tegra仅在开启BUILD_TEGRA时才会加入构建（cpp/CMakeLists.txt）。每个样例目录内都配有独立的README.md、CMakeLists.txt与数据文件，既可以随仓库整体构建，也可以单独进入任意样例目录构建。

二、环境准备与获取源码

2.1 前置条件

• 安装与平台匹配的CUDA Toolkit 13.3（下载与安装请参考 CUDA 官方 Linux / Windows 安装指南）；
• 若通过源码构建 C++ 样例，需要CMake 3.20 或更高版本；
• Python 样例需要Python 3.10+与匹配的 CUDA Python 包。

2.2 获取源码

使用 git 克隆：

git clone https://github.com/NVIDIA/cuda-samples.git

（在本仓库语境下即克隆当前项目GitHub_Trending/cu/cuda-samples。）如果不使用 git，也可在仓库页面点击 "Download ZIP" 下载压缩包后解压使用。

三、在 Linux 上构建

官方推荐的流程是：在仓库根目录创建独立的构建目录（保持源码目录干净），配置、编译、运行：

# 1. 安装 CMake（如尚未安装，以 Ubuntu 为例） sudo apt install cmake # 2. 进入仓库根目录，创建构建目录 mkdir build && cd build # 3. 配置 cmake .. # 4. 并行编译（-j$(nproc) 使用全部 CPU 核心） make -j$(nproc)

编译完成后，可执行文件位于build/下各样例对应的子目录中，直接进入相应目录运行即可。这套流程同样适用于从仓库任意子目录或单个样例目录发起构建——每个样例的CMakeLists.txt都是自洽的，例如 cpp/0_Introduction/vectorAdd/CMakeLists.txt 独立声明了project(vectorAdd LANGUAGES C CXX CUDA)、架构列表与setup_samples_install()安装钩子。

四、在 Windows 上构建

Windows 上有两种方式：

方式一：Visual Studio 集成（推荐）

Visual Studio 2019 16.5 及以上版本内置 CMake 语言服务，可直接从仓库根目录、任意子目录或单个样例目录导入项目。打开后选择配置（Debug 或 Release），按F7（Build Solution）即可编译。

方式二：命令行

使用 Visual Studio 提供的x64 Native Tools Command Prompt for VS：

mkdir build && cd build cmake .. -G "Visual Studio 16 2019" -A x64

然后打开生成的解决方案文件CUDA_Samples.sln，选择配置后按F7构建；运行产物位于 Visual Studio 指定的输出目录。由于是 multi-config 生成器，构建类型在编译/安装时通过--config指定（见下文安装章节）。

五、平台相关构建选项与片上调试

5.1 启用 GPU 片上调试（cuda-gdb）

NVIDIA GPU 支持通过 cuda-gdb 进行片上调试，但开启调试会禁用部分编译器优化，显著影响运行性能，因此默认关闭。开关由 nvcc 的-G选项控制，在 CMake 层面通过ENABLE_CUDA_DEBUG宏开启：

cmake -DENABLE_CUDA_DEBUG=True ...

对应的实现逻辑见 CMakeLists.txt：开启后追加-G，关闭时则追加-lineinfo（二者互斥，-lineinfo为调试工具保留行号信息）。

5.2 平台特定样例开关

部分样例仅面向特定平台，需要通过 CMake 变量显式开启，仓库定义的核心平台开关为：

• BUILD_TEGRA：构建 Tegra 平台相关样例（cuDLA、NvMedia、NvSci、OpenGL ES 等）

cmake -DBUILD_TEGRA=True ..

该变量既可在命令行传入，也可在 CMake GUI 中设置；未开启时，cpp/CMakeLists.txt 中8_Platform_Specific/Tegra整棵子树都不会进入构建。

六、面向嵌入式与车载平台的交叉编译

6.1 交叉编译到 Tegra（aarch64 Linux）

先安装 NVIDIA 提供的 Tegra 交叉编译工具链，然后使用仓库自带的 toolchain 文件配置：

mkdir build && cd build cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/toolchain-aarch64-linux.cmake -DTARGET_FS=/path/to/target/system/file/system make -j$(nproc)

关键参数说明：

• CMAKE_TOOLCHAIN_FILE：指向 cmake/toolchains/toolchain-aarch64-linux.cmake，该文件指定了aarch64-linux-gnu-gcc/g++交叉编译器、CMAKE_CROSSCOMPILING TRUE，以及 CUDA 编译时的-ccbin宿主编译器标志；
• TARGET_FS：目标文件系统根路径。toolchain 文件会将其用作CMAKE_SYSROOT，并自动探测 CUDA Toolkit 在目标端的安装位置（优先aarch64-linux，回退sbsa-linux，见 toolchain-aarch64-linux.cmake），同时为链接器追加-rpath-link指向目标端的/usr/lib等库目录。

编译产物为 aarch64 架构，需传输到 Tegra 设备上执行。

6.2 从 DriveOS Docker 容器交叉构建 Automotive Linux 平台

面向 DriveOS 容器环境构建时，需要先把目标 Root Filesystem（RFS）挂载进容器，使 CMake 能正确找到 CUDA 与系统库路径：

# 1. 创建临时挂载点 mkdir /drive/<temp> # <temp> 为任意临时目录，例如 /drive/temp # 2. 挂载目标文件系统镜像 mount /drive/drive-linux/filesystem/targetfs-images/dev_nsr_desktop_ubuntu-24.04_thor_rfs.img /drive/temp # 3. 配置 mkdir build && cd build cmake .. -DBUILD_TEGRA=True \ -DCMAKE_CUDA_COMPILER=/usr/local/cuda/bin/nvcc \ -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/toolchain-aarch64-linux.cmake \ -DTARGET_FS=/drive/temp \ -DCMAKE_LIBRARY_PATH=/drive/temp/usr/local/cuda-13.1/thor/lib64/ \ -DCMAKE_INCLUDE_PATH=/drive/temp/usr/local/cuda-13.1/thor/include/

注意事项（README 明确提示的已知限制）：DriveOS dev-nsr 目标文件系统中未预装libdrm-dev与Vulkan，会导致 CMake 报错，相关样例（依赖 Vulkan / libdrm 的simpleGL、simpleVulkan、simpleVulkanMMAP、simpleGLES_EGLOutput）无法构建。缓解手段有两种：

# 方式一：make 时忽略错误继续 make -j$(nproc) --ignore-errors # 或 --keep-going

# 方式二：注释掉父目录 CMakeLists 中对应的 add_subdirectory # 在 cpp/5_Domain_Specific/CMakeList.txt 中： # add_subdirectory(simpleGL) # add_subdirectory(simpleVulkan) # add_subdirectory(simpleVulkanMMAP) # 在 cpp/8_Platform_Specific/Tegra/CMakeList.txt 中： # add_subdirectory(simpleGLES_EGLOutput)

6.3 QNX 平台交叉编译

CUDA 13.0 起支持通过 CMake 交叉编译 QNX，面向 Tegra Thor QNX 平台的典型配置如下：

mkdir build && cd build QNX_HOST=/path/to/qnx/host \ QNX_TARGET=/path/to/qnx/target \ cmake .. \ -DBUILD_TEGRA=True \ -DCMAKE_CUDA_COMPILER=/usr/local/cuda-13.3/bin/nvcc \ -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/toolchain-aarch64-qnx.cmake \ -DCMAKE_LIBRARY_PATH=/usr/local/cuda-13.3/thor/targets/aarch64-qnx/lib/stubs/ \ -DCMAKE_INCLUDE_PATH=/usr/local/cuda-13.3/thor/targets/aarch64-qnx/include/

其中QNX_HOST/QNX_TARGET环境变量由 toolchain-aarch64-qnx.cmake 在配置阶段使用；CMAKE_LIBRARY_PATH/CMAKE_INCLUDE_PATH指向 Thor QNX 目标的 CUDA stub 库与头文件。QNX 平台上的窗口系统为 Screen（见依赖章节），相关样例的依赖随根文件系统提供。

6.4 新旧驱动共存的前向兼容（Forward Compatibility）

使用新版 CUDA Toolkit（CUDA 13.0+）与新版 UMD（版本 580+）搭配旧版 KMD（版本 550 及更早）构建样例时，需要指定CMAKE_PREFIX_PATH指向新驱动库：

cmake -DCMAKE_PREFIX_PATH=/usr/local/cuda/lib64/stubs/ ..

其作用是在配置阶段优先搜索新版驱动提供的 stub 库，避免链接到旧版 KMD 对应的过时符号。

七、安装样例：目录结构与自定义路径

7.1 默认安装路径结构

安装系统会自动按三维度组织输出目录（实现细节见 cmake/InstallSamples.cmake）：

• 目标架构${CMAKE_SYSTEM_PROCESSOR}：如x64、aarch64、amd64；
• 目标 OS：linux、windows、darwin、qnx；
• 构建类型：release、debug等。

默认安装路径为：

build/bin/${TARGET_ARCH}/${TARGET_OS}/${BUILD_TYPE}

具体示例：

从源码看（cmake/InstallSamples.cmake），该模块会自动检测架构（小写化CMAKE_SYSTEM_PROCESSOR）、操作系统（含 QNX 特判）与构建类型（multi-config 生成器在安装时用$<LOWER_CASE:$<CONFIG>>求值，单配置生成器默认Release），并生成安装脚本。

7.2 自定义安装路径

两个 CMake 变量控制安装位置：

• CMAKE_INSTALL_PREFIX：修改安装根目录（默认build/bin）：

cmake -DCMAKE_INSTALL_PREFIX=/custom/path .. # 安装到 /custom/path/${TARGET_ARCH}/${TARGET_OS}/${BUILD_TYPE}

• CUDA_SAMPLES_INSTALL_DIR：指定精确的最终安装目录（覆盖上述分层结构）：

cmake -DCUDA_SAMPLES_INSTALL_DIR=/exact/install/path ..

7.3 Linux 安装

前提是先完成配置与构建，然后在build/目录执行：

cd build/ make install

安装脚本会把三类文件复制到目标目录（对应 cmake/InstallSamples.cmake 的实现）：可执行文件（Unix 下按test -x判定，Windows 下按.exe扩展名）、数据文件（.fatbin、.ptx、.bc、.raw、.ppm等，保留可读权限但不带执行权限）、共享库（Windows 的.dll、Linux 的.so），并会跳过.cu/.cpp/.h等源码与 CMake 中间产物。

7.4 Windows 安装

命令行方式（在x64 Native Tools Command Prompt for VS中）：

cd build cmake --build . --config Release cmake --install . --config Release

注意：Visual Studio 属于 multi-config 生成器，--config决定安装的构建类型，将Release换成Debug即可安装调试版。

Visual Studio IDE 方式：

1. 打开CUDA_Samples.sln；
2. 选择配置（Release 或 Debug）；
3. 构建解决方案（F7）；
4. 在 Solution Explorer 的CMakePredefinedTargets下右键INSTALL目标，选择 "Build"。

八、CUDA Python 样例：cuda.core 驱动的脚本化示例

自 CUDA 13.2 起（见 CHANGELOG.md），仓库新增python/目录，提供cuda.core 导向的 Python 样例：使用 CUDA Python 生态中的cuda.core管理设备、程序、launch 与内存，并结合 NumPy / CuPy / 框架互操作。

目录布局与 C++ 样例主题一一对应：

运行方式：顶层 CMake 构建不会编译这些脚本。每个样例需要独立创建 Python 3.10+ 环境并安装依赖：

cd python/<category>/<sampleName> pip install -r requirements.txt python <sampleScript>.py

仓库根目录提供统一的 python/requirements.txt 说明整体依赖版本。各样例的README.md会给出前置条件、CLI 选项与预期输出——例如 python/1_GettingStarted/vectorAdd/README.md 详细列出了cuda-python、cuda-core、cupy-cuda13x的版本要求（CUDA 13.x 对应cupy-cuda13x），以及--elements、--device、--no-verify等自定义参数用法。

九、用 run_tests.py 一键运行全部样例

仓库明确声明样例不是CUDA 验证套件，但当需要快速做一次全量冒烟检查时，可以用根目录的 run_tests.py 脚本。

9.1 工作方式与命令行参数

脚本会递归扫描指定目录下所有可执行文件，依据 test_args.json 中的配置匹配应用名（Windows 上忽略.exe后缀），逐个运行并捕获输出。支持的参数：

脚本成功返回 0，失败则返回第一个非零错误码，并打印失败样例的简明列表。从源码看（run_tests.py），每个测试实例有 5 分钟超时；退出码 2（EXIT_WAIVED）被特殊对待为"waived"（硬件/需求不满足），不计入失败；启动时会通过nvidia-smi -L探测 GPU 数量（探测不到时回退读取CUDA_VISIBLE_DEVICES，见 run_tests.py），无 GPU 则直接退出。

9.2 三种配置模式

（1）Skip —— 跳过执行

适用于依赖图形界面、不适合自动化运行的样例（如流体/GL 演示）：

"fluidsGL": { "skip": true }

输出：Skipping fluidsGL (marked as skip in config)

（2）Single Run —— 单次运行

args列表中的每项会以空格分隔追加到命令行；所有应用都从自身所在目录执行，因此路径均相对应用位置。无需参数的应用可以省略该配置项，未匹配到配置的可执行文件会以./application直接运行。

"ptxgen": { "args": [ "test.ll", "-arch=compute_75" ] }

输出：

Running ptxgen Command: ./ptxgen test.ll -arch=compute_75 Test completed with return code 0

（3）Multiple Runs —— 多组参数多次运行

通过runs列表指定任意多组参数：

"recursiveGaussian": { "runs": [ { "args": [ "-sigma=10", "-file=data/ref_10.ppm" ] }, { "args": [ "-sigma=14", "-file=data/ref_14.ppm" ] }, { "args": [ "-sigma=18", "-file=data/ref_18.ppm" ] }, { "args": [ "-sigma=22", "-file=data/ref_22.ppm" ] } ] }

输出：

Running recursiveGaussian (run 1/4) Command: ./recursiveGaussian -sigma=10 -file=data/ref_10.ppm Test completed with return code 0 Running recursiveGaussian (run 2/4) Command: ./recursiveGaussian -sigma=14 -file=data/ref_14.ppm Test completed with return code 0 ...

除了 README 展示的这三种模式，仓库内的 test_args.json 还实际使用了两个额外的配置键，体现脚本的扩展能力：

• min_gpus：声明样例所需 GPU 数量（如simpleP2P、conjugateGradientMultiDeviceCG、simpleCUFFT_MGPU等要求"min_gpus": 2），脚本会在 GPU 数不足时自动跳过（run_tests.py）；
• python配置段：为 Python 样例提供args与launcher（如multiGPUGradientAverage通过mpirun --allow-run-as-root -np 2启动，reductionMultiBlockCG通过--cuda-include-dir指定 CUDA 头文件路径）。

9.3 完整示例：构建并测试全部样例

# 1. 构建 mkdir build cd build cmake .. make -j$(nproc) # 2. 回到仓库根目录运行测试脚本 cd .. python3 run_tests.py --output ./test --dir ./build/cpp --config test_args.json

全部成功时输出类似（具体数量取决于构建类型与系统配置）：

Test Summary: Ran 199 test runs for 180 executables. All test runs passed!

部分失败时输出类似：

Test Summary: Ran 199 test runs for 180 executables. Failed runs (2): bicubicTexture (run 1/5): Failed (code 1) Mandelbrot (run 1/2): Failed (code 1)

排查方法：查看输出目录下的 stdout 日志（命名规则为APM_<application_name>.txt，多组参数时为APM_<application_name>.run<n>.txt）。若确认是样例本身在特定系统上的错误，可在样例仓库提交 issue 反馈。

十、依赖说明：第三方库与 CUDA 特性

部分样例依赖第三方库或 CUDA Toolkit / Driver 提供的特性。若某样例的第三方依赖在系统中存在但未安装，该样例会在构建时自我放弃（waive）。每个样例的依赖列在其 README 的 Dependencies 一节。

10.1 第三方依赖

仓库的Common/目录已随附部分构建期依赖：如 Common/GL/ 下的 GLEW/GLUT 头文件、Common/lib/x64 下的freeglut.lib与glew64.lib、Common/data 下的共享测试数据（.raw、.pgm）。

10.2 CUDA 特性依赖

十一、其他仓库资源

• 版本历史：仓库演进记录见 CHANGELOG.md，从 CUDA 9.2（GitHub 首版）到 13.3，可追溯每个样例的新增、移除与 API 迁移（例如 CUDA 13.0 将废弃的cudaDeviceProp字段替换为cudaDeviceGetAttribute，以及cuCtxCreate→cuCtxCreate_v4、cudaGraphAddNode→cudaGraphAddNode_v2等 API 升级）；
• 贡献指南：仓库欢迎 issue 与建议，但当前阶段暂不接受外部代码贡献；源码遵循 Google C++ Style Guide（见 README.md 的 Contributors Guide 一节）；
• 常见问题与参考：CUDA 常见问题可参考 NVIDIA 官方 FAQ 与 CUDA Toolkit Release Notes；深入学习可阅读 CUDA Programming Guide 与 Accelerated Computing Blog（均为 README 引用的官方资料）。

结语

围绕这套 CUDA Samples 仓库，本文完整覆盖了从获取源码、Linux/Windows 原生构建、Tegra/QNX/DriveOS 交叉编译、定制化安装，到基于 run_tests.py 与 test_args.json 的全量自动化冒烟测试，并深入到根 CMakeLists.txt、cmake/InstallSamples.cmake 与 toolchain 文件的实现细节。无论是入门 CUDA 编程、学习库 API 用法，还是为嵌入式/车载平台搭建样例构建环境，本文都可以作为按图索骥的起点。

【免费下载链接】cuda-samplesSamples for CUDA Developers which demonstrates features in CUDA Toolkit项目地址: https://gitcode.com/GitHub_Trending/cu/cuda-samples