CUDA Samples（原称 NVIDIA CUDA SDK Samples）是 NVIDIA 官方提供的一系列示例程序，涵盖 CUDA 核心技术（如并行计算、内存管理、流处理）、深度学习加速、图形渲染、异构计算等多个领域。这些示例不仅是学习 CUDA 编程的核心资料，也是验证 CUDA 环境是否正常工作的重要工具。此文档旨在在提供 CUDA Samples 的获取、环境准备、编译流程及常见问题解决的完整指导，适用于 Linux、Windows 主流操作系统。

一、前置条件

1.1 硬件要求

需搭载 NVIDIA 显卡，且显卡需支持 CUDA 架构（可通过 NVIDIA 官方文档查询显卡兼容性）。
建议显卡计算能力（Compute Capability）≥ 3.5（主流显卡均满足，如 GTX 10 系列及以上、Tesla 系列）。

1.2 软件环境要求

需完成「CUDA 工具链 + 编译工具」的环境搭建，不同系统的依赖如下：

系统类型	核心依赖组件	说明
Linux(CentOS)	CUDA Toolkit12.4、GCC/G++、Make、CMake	GCC 版本需与 CUDA 12.4 兼容（支持 GCC 12 及以下）
Linux(Rocky)	CUDA Toolkit12.8、GCC/G++、Make、CMake	GCC 版本需与 CUDA 12.8 兼容（支持 GCC 13 及以下）
Windows	CUDA Toolkit、Visual Studio	需安装 Visual Studio 2019 及以上（含 C++ 编译组件），且版本与 CUDA Toolkit 匹配

1.3 基于包管理器的依赖安装指导（Linux）

1.3.1 YUM 系列（CentOS - CUDA 12.4）

# 安装基础编译工具
$ sudo yum install -y gcc gcc-c++ make cmake

# 安装 EPEL 源（部分依赖需额外源）
$ sudo yum install -y epel-release

# 安装开发工具集（可选，用于多版本 GCC 管理）
$ sudo yum install -y centos-release-scl
$ sudo yum install -y devtoolset-12  # 对应 GCC 12 版本（兼容 CUDA 12.4）

# 安装 NVIDIA 驱动及 CUDA Toolkit 12.4（通过官方 repo）
$ sudo dnf config-manager --add-repo=https://developer.download.nvidia.com/compute/cuda/repos/rhel7/x86_64/cuda-rhel7.repo
$ sudo yum install -y cuda-toolkit-12-4  # 明确安装 CUDA 12.4

1.3.2 YUM 系列（Rocky Linux - CUDA 12.8）

# 安装基础编译工具
$ sudo dnf install -y gcc gcc-c++ make cmake

# 安装 EPEL 源
$ sudo dnf install -y epel-release

# 安装开发工具集
$ sudo dnf install -y rocky-release-scl
$ sudo dnf install -y devtoolset-13  # 对应 GCC 13 版本（兼容 CUDA 12.8）

# 安装 NVIDIA 驱动及 CUDA Toolkit 12.8（通过官方 repo）
$ sudo dnf config-manager --add-repo=https://developer.download.nvidia.com/compute/cuda/repos/rhel9/x86_64/cuda-rhel9.repo
$ sudo dnf install -y cuda-toolkit-12-8  # 明确安装 CUDA 12.8

1.3.3 APT 系列（Ubuntu、Debian等）

# 更新包索引
$ sudo apt update

# 安装基础编译工具
$ sudo apt install -y gcc g++ make cmake

# 安装 CUDA 12.4（适用于 Ubuntu 22.04）
$ wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-ubuntu2204.pin
$ sudo mv cuda-ubuntu2204.pin /etc/apt/preferences.d/cuda-repository-pin-600
$ wget https://developer.download.nvidia.com/compute/cuda/12.4.0/local_installers/cuda-repo-ubuntu2204-12-4-local_12.4.0-550.54.14-1_amd64.deb
$ sudo dpkg -i cuda-repo-ubuntu2204-12-4-local_12.4.0-550.54.14-1_amd64.deb
$ sudo cp /var/cuda-repo-ubuntu2204-12-4-local/cuda-*-keyring.gpg /usr/share/keyrings/
$ sudo apt update
$ sudo apt install -y cuda-toolkit-12-4

二、CUDA Samples 获取

获取 CUDA Samples 主要有两种方式，推荐通过 CUDA Toolkit 安装时同步获取，确保版本匹配。

2.1 方式 1：CUDA Toolkit 安装时自带（推荐）

安装 CUDA Toolkit 过程中，默认会勾选「CUDA Samples」组件，安装完成后可在以下路径找到：

Linux：/usr/local/cuda-[版本号]/samples（如 /usr/local/cuda-12.4/samples,如 /usr/local/cuda-12.8/samples）
Windows：C:\ProgramData\NVIDIA Corporation\CUDA Samples\[版本号]（如 C:\ProgramData\NVIDIA Corporation\CUDA Samples\12.4）

2.2 方式 2：GitHub 源码克隆

若未同步安装或需获取最新版本，可从 NVIDIA 官方 GitHub 仓库克隆：

# 克隆主仓库
$ git clone https://github.com/NVIDIA/cuda-samples.git
$ cd cuda-samples

# CentOS（CUDA 12.4）需切换到对应版本分支
$ git checkout branch-v12.4

# Rocky（CUDA 12.8）需切换到对应版本分支
$ git checkout branch-v12.8

# 或使用标签（精确版本匹配）
# CentOS: git checkout v12.4.127
# Rocky: git checkout v12.8.140

三、环境验证

在编译前需确认 CUDA 环境已正确配置，避免编译失败。

3.1 验证 CUDA Toolkit 安装

执行以下命令查看 CUDA 版本，确保输出正常：

# Linux/Windows（PowerShell）通用
$ nvcc --version

预期输出：包含 CUDA 版本、VCC 版本等信息（如"release 12.4, V12.4.127","release 12.8, V12.8.140"）。

3.2 验证 NVIDIA 驱动

驱动是 CUDA 程序运行的基础，需确保驱动版本与 CUDA Toolkit 兼容（驱动版本可通过 NVIDIA 官网查询匹配关系）：

Linux：

$ nvidia-smi

预期输出：显示显卡型号、驱动版本、CUDA 支持版本（如 Driver Version: 550.54.14 CUDA Version: 12.4）。

Windows：右键桌面 → 打开「NVIDIA 控制面板」→ 「帮助」→ 「系统信息」→ 查看「驱动程序版本」。

3.3 验证编译工具

Linux：确认 GCC、Make 已安装：

$ gcc --version
$ make --version

Windows：确认 Visual Studio 已安装 C++ 组件，可通过「Visual Studio Installer」检查「Desktop development with C++」选项是否勾选。

四、编译流程

CUDA Samples 支持两种编译方式：传统 Make 编译（Linux 推荐）和 CMake 编译（跨平台通用，支持 Windows/Linux）。

4.1 方式 1：Make 编译（Linux 专属）

4.1.1 进入 Samples 根目录

$ cd /usr/local/cuda-12.4/samples
$ cd /usr/local/cuda-12.8/samples

4.1.2 执行编译命令

全量编译（编译所有 Samples，耗时较长，约 10-30 分钟）：

$ make -j$(nproc)  # $(nproc) 表示使用所有 CPU 核心加速编译

增量编译（仅编译指定示例，推荐）：
进入具体示例目录（如 0_Simple/vectorAdd，向量加法示例），执行 make：

$ cd 0_Simple/vectorAdd
$ make

4.1.3 查看编译结果

编译成功后，可执行文件生成路径：

CentOS：/usr/local/cuda-12.4/samples/bin/x86_64/linux/release/
Rocky：/usr/local/cuda-12.8/samples/bin/x86_64/linux/release/

4.2 方式 2：CMake 编译（跨平台通用）

CMake 编译更灵活，支持自定义输出路径、选择编译示例，适用于 Windows 和 Linux 系统。注意：不同 CUDA 版本的 Samples 编译方式可能存在差异（如 CMake 最低版本要求、依赖组件等），请务必参考源码根目录的 README.md 文件获取对应版本的详细说明。

4.2.1 新建编译目录（避免污染源码）

# Linux/Windows（PowerShell）通用
$ cd cuda-samples  # 进入 Samples 根目录
$ mkdir build && cd build

4.2.2 生成编译配置

根据操作系统和 CUDA 版本选择对应的生成器（以 CUDA 12.2 为例）：

Linux（生成 Makefile）：

$ cmake .. -DCMAKE_BUILD_TYPE=Release \
         -DCMAKE_CUDA_COMPILER=/usr/local/cuda-12.4/bin/nvcc
或
$ cmake .. -DCMAKE_BUILD_TYPE=Release \
         -DCMAKE_CUDA_COMPILER=/usr/local/cuda-12.8/bin/nvcc

Windows（生成 Visual Studio 解决方案）：
需指定 Visual Studio 版本（如 2022）和架构（64 位）：

$ cmake .. -G "Visual Studio 17 2022" -A x64 \
         -DCMAKE_BUILD_TYPE=Release \
         -DCMAKE_CUDA_COMPILER="C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v12.4/bin/nvcc.exe"

4.2.3 执行编译

Linux：

$ make -j$(nproc)  # 全量编译
 # 或编译指定示例（如 vectorAdd）
$ make vectorAdd

Windows：
方式 1：通过 Visual Studio 打开 build 目录下的 CUDA Samples.sln，点击「生成」→「生成解决方案」。
方式 2：通过命令行编译：

$ cmake --build . --config Release -j$(Get-CimInstance Win32_Processor).NumberOfCores

4.2.4 查看编译结果

Linux：可执行文件在 build/bin/Release/ 目录下。
Windows：可执行文件在 build\[示例目录]\Release\ 目录下（如 build\0_Simple\vectorAdd\Release\vectorAdd.exe）。

五、运行与验证

编译完成后，运行示例程序验证是否正常工作。以基础示例 vectorAdd（向量加法，验证 CUDA 设备计算能力）为例：

5.1 运行示例

Linux：

$ cd /usr/local/cuda-12.4/samples/bin/x86_64/linux/release
或
$ cd /usr/local/cuda-12.8/samples/bin/x86_64/linux/release
$ ./vectorAdd

Windows：

$ cd C:\ProgramData\NVIDIA Corporation\CUDA Samples\[版本号]\bin\win64\Release
$ .\vectorAdd.exe

5.2 验证输出

预期成功输出：

[Vector Addition Using CUDA]
Copy input data from the host memory to the CUDA device
CUDA kernel launch with 196 blocks of 256 threads
Copy output data from the CUDA device to the host memory
Test PASSED
Done

若显示「Test PASSED」，说明 CUDA 环境及编译流程均正常；若显示「Test FAILED」或设备无法识别，需排查驱动或 CUDA 配置问题。

六、常见问题与解决方案

6.1 编译报错：「nvcc: command not found」

原因：nvcc（CUDA 编译器）未添加到系统环境变量。
解决方案：
- Linux：在 ~/.bashrc 或 ~/.zshrc 中添加环境变量：

$ echo 'export PATH=/usr/local/cuda-12.4/bin:$PATH' >> ~/.bashrc
$ echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
$ source ~/.bashrc

Windows：在「系统属性」→「高级」→「环境变量」中，将 C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\[版本号]\bin 添加到 PATH 变量。

6.2 编译报错：「GCC version is higher than supported」

原因：GCC 版本超过 CUDA Toolkit 支持的最高版本（如 CentOS 用 GCC 13 编译 CUDA 12.4）。
解决方案：加载兼容版本 GCC：

# CentOS 切换到 GCC 12
$ scl enable devtoolset-12 bash

# Rocky 切换到 GCC 13
$ scl enable devtoolset-13 bash

6.3 运行报错：「no CUDA-capable device is detected」

原因：NVIDIA 驱动未安装、驱动版本过低，或显卡不支持 CUDA。
解决方案：
1. 执行 nvidia-smi 检查驱动是否正常加载，若提示「command not found」需重新安装驱动。
2. 确认显卡型号在 CUDA 兼容列表中。
3. 若使用虚拟机，需开启「GPU 直通」或「虚拟化 GPU」功能。

6.4 CMake 生成失败：「Could not find CUDA」

原因：CMake 未找到 CUDA Toolkit 安装路径。
解决方案：编译时指定 CUDA 路径：

$ cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_CUDA_COMPILER=/usr/local/cuda-[版本号]/bin/nvcc

七、扩展说明

7.1 Samples 目录结构解析

CUDA Samples 按功能分类，核心目录说明：

0_Simple：基础示例（向量加法、矩阵乘法等，入门首选）。
1_Utilities：工具类示例（设备查询、性能计时等）。
2_Graphics：图形渲染相关示例（结合 OpenGL、DirectX）。
3_Imaging：图像处理示例（卷积、直方图等）。
4_Finance：金融领域示例（蒙特卡洛模拟等）。
5_DL：深度学习加速示例（结合 cuDNN、TensorRT）。

7.2 自定义编译选项

指定 CUDA 架构：（如针对 Ampere 架构）：

# CUDA 12.4/12.8 通用
$ make NVCCFLAGS="-arch=sm_86"  # Make 编译
$ cmake .. -DCMAKE_CUDA_ARCHITECTURES=86  # CMake 编译

版本差异说明： CUDA 12.8 相比 12.4 增加了对新显卡架构的支持，部分 Samples（如 5_DL 目录下）需依赖更高版本的 cuDNN/TensorRT。编译前务必参考对应版本的 README.md，例如：

# 查看当前版本 Samples 的编译说明
$ cat /usr/local/cuda-12.4/samples/README.md  # CentOS
$ cat /usr/local/cuda-12.8/samples/README.md  # Rocky