面向 CUDA 开发者的示例程序，展示了 CUDA 工具包中的功能。此版本支持 CUDA Toolkit 13.1。
本节仅描述 GitHub 上 CUDA 示例的发行说明。
为您的对应平台下载并安装 CUDA Toolkit。
关于 CUDA 工具包的系统要求和安装说明，请参阅 Linux 安装指南 和 Windows 安装指南。
使用 git 克隆 CUDA 示例仓库，命令如下：
git clone https://github.com/NVIDIA/cuda-samples.git
如果不使用 git，最简单的方法是点击仓库页面上的 "Download ZIP" 按钮下载包含当前版本的 zip 文件。然后解压整个压缩包即可使用示例。
CUDA 示例使用 CMake 构建。请按照以下说明在 Linux、Windows 上构建，以及为 Tegra 设备进行交叉编译。
确保已安装 CMake（版本 3.20 或更高）。如有需要，请使用包管理器安装：
例如：
sudo apt install cmake
导航到克隆的仓库根目录并创建构建目录：
mkdir build && cd build
使用 CMake 配置项目：
cmake ..
构建示例：
make -j$(nproc)
从构建文件夹中各自的目录运行示例。您也可以从示例仓库的任何子目录或任何单个示例内部遵循此过程。
CMake 的语言服务在 Visual Studio 2019 版本 16.5 或更高版本中可用，您可以直接从根级别或任何子目录或单个示例导入 CUDA 示例仓库。
要从命令行构建，请打开 Visual Studio 安装附带的 x64 Native Tools Command Prompt for VS。
导航到克隆的仓库根目录并创建构建目录：
mkdir build && cd build
使用 CMake 配置项目 - 例如：
cmake .. -G "Visual Studio 16 2019" -A x64
在 Visual Studio 中打开生成的解决方案文件 CUDA_Samples.sln。通过选择所需的配置（例如，Debug 或 Release）并按 F7（生成解决方案）来构建示例。
从 Visual Studio 中指定的输出目录运行示例。
NVIDIA GPU 支持通过 cuda-gdb 进行 GPU 调试。启用此功能可能会显著影响应用程序性能，因为在此配置中某些编译器优化被禁用，因此默认情况下不启用。设备上调试的启用通过 nvcc 的 -G 开关控制。
要为示例构建启用 cuda-gdb，请在 CMake 命令行上定义 ENABLE_CUDA_DEBUG 标志。例如：
cmake -DENABLE_CUDA_DEBUG=True ...
一些 CUDA 示例针对特定平台，需要向 CMake 传递标志来启用。特别是，我们定义了以下平台特定标志：
BUILD_TEGRA - 用于 Tegra 特定示例要构建这些示例，请在命令行或通过 CMake GUI 设置变量。例如：
cmake -DBUILD_TEGRA=True ..
按照 Tegra 开发指南中的描述，安装 NVIDIA 工具链和 Tegra 设备的交叉编译环境。
确保已安装 CMake（版本 3.20 或更高）。
导航到克隆的仓库根目录并创建构建目录：
mkdir build && cd build
使用 CMake 配置项目，指定 Tegra 工具链文件。您可以使用 -DTARGET_FS 指向目标文件系统根路径，以获取必要的头文件和库文件：
cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/toolchain-aarch64-linux.cmake -DTARGET_FS=/path/to/target/system/file/system
构建示例：
make -j$(nproc)
将构建好的二进制文件传输到 Tegra 设备并在那里执行。
要从 DriveOS Docker 容器中为目标平台构建 CUDA 示例，请使用以下说明。
在容器中挂载目标根文件系统（RFS），以便 CUDA cmake 进程能够正确访问构建示例所需的 CUDA 和其他系统库路径。
创建一个临时目录，<temp> 是您选择的任何临时目录，例如，您可以使用 /drive/temp：
$ mkdir /drive/<temp>
通过运行以下命令挂载文件系统：
$ mount /drive/drive-linux/filesystem/targetfs-images/dev_nsr_desktop_ubuntu-24.04_thor_rfs.img /drive/temp
通过运行以下 cmake 命令配置项目：
$ 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/
请注意，以下库未预装在 DriveOS dev-nsr 目标文件系统中：
* libdrm-dev
* Vulkan
这会导致 cmake 命令抛出与缺失文件相关的错误，因此相关示例在后续步骤中将无法构建。此问题将在未来的 DriveOS 版本中解决。
要忽略上述错误构建示例，您可以使用 --ignore-errors/--keep-going，或者在父文件夹的 CMakeLists.txt 中注释掉需要 Vulkan 和 libdrm_dev 的示例对应的 add_subdirectory 命令：
$ make -j$(nproc) --ignore-errors # 或 --keep-going
# 在 Samples/5_Domain_Specific/CMakeList.txt 中
# add_subdirectory(simpleGL)
# add_subdirectory(simpleVulkan)
# add_subdirectory(simpleVulkanMMAP)
# 在 Samples/8_Platform_Specific/Tegra/CMakeList.txt 中
# add_subdirectory(simpleGLES_EGLOutput)
从 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-safe-13.0/bin/nvcc \
-DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/toolchain-aarch64-qnx.cmake \
-DCMAKE_LIBRARY_PATH=/usr/local/cuda-safe-13.0/thor/targets/aarch64-qnx/lib/stubs/ \
-DCMAKE_INCLUDE_PATH=/usr/local/cuda-safe-13.0/thor/targets/aarch64-qnx/include/
要使用新的 CUDA 工具包（CUDA 13.0 或更高版本）和 UMD（版本 580 或更高版本）以及旧的 KMD（版本 550 或更早版本）构建示例，您需要为使用新的驱动程序库设置 CMAKE_PREFIX_PATH，命令可能如下所示：
cmake -DCMAKE_PREFIX_PATH=/usr/local/cuda/lib64/stubs/ ..
安装系统根据以下内容自动将示例组织成结构化的目录布局：
- 目标架构：${CMAKE_SYSTEM_PROCESSOR}，例如 x64、aarch64、amd64 等。
- 目标操作系统：linux、windows、darwin、qnx
- 构建类型：release、debug 等。
默认安装路径为：build/bin/${TARGET_ARCH}/${TARGET_OS}/${BUILD_TYPE}
示例：
- Linux x86_64 Release：build/bin/x64/linux/release
- Linux aarch64 Release：build/bin/aarch64/linux/release
- Windows amd64 Release：build/bin/amd64/windows/release
您可以在配置步骤中使用 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 ..
前提条件： 您必须首先按照 构建 CUDA 示例 - Linux 或 [构建] 部分所述，使用 CMake 配置项目。
配置和构建后，安装示例：
cd build/
make install
前提条件： 您必须首先按照 构建 CUDA 示例 - Windows 部分所述，使用 CMake 配置项目。
使用 CMake 配置后，从 x64 Native Tools Command Prompt for VS 构建并安装：
cd build
cmake --build . --config Release
cmake --install . --config Release
注意： 如果要安装调试版本，请将 Release 替换为 Debug。对于多配置生成器（如 Visual Studio），--config 标志决定安装哪种构建类型。
或者，在 Visual Studio 中打开生成的解决方案文件 CUDA_Samples.sln：
1. 选择所需的配置（Release 或 Debug）
2. 生成解决方案（F7 或 生成 > 生成解决方案）
3. 在解决方案资源管理器中右键单击 CMakePredefinedTargets 下的 INSTALL 目标
4. 选择“生成”
需要注意的是，CUDA 示例并非用作 CUDA 的验证套件。它们不涵盖边界情况，不完整覆盖运行时和驱动程序 API，也不用于性能基准测试等。尽管如此，有时将所有示例作为快速完整性检查运行可能很有用，我们提供了一个脚本来执行此操作，即 run_tests.py。
这个 Python3 脚本在您选择的子目录中查找所有可执行文件，并根据 test_args.json 中指定的命令行参数匹配应用程序名称。它接受以下命令行参数：
| 开关 | 用途 | 示例 |
|---|---|---|
| --dir | 指定搜索可执行文件的根目录（递归） | --dir ./build/Samples |
| --config | 可执行文件参数的 JSON 配置文件 | --config test_args.json |
| --output | 测试结果的输出目录（stdout 保存为 .txt 文件 - 如果目录不存在将被创建） | --output ./test |
| --args | 传递给所有可执行文件的全局参数（当前未使用） | --args arg_1 arg_2 ... |
| --parallel | 并行执行的应用程序数量。 | --parallel 8 |
应用程序配置从 test_args.json 加载，并与可执行文件名匹配（在 Windows 上忽略 .exe 扩展名）。
脚本在成功时返回 0，在测试期间遇到第一个非零错误代码时返回失败。如果任何示例失败，它还会打印一个简化的失败示例列表。
主要有三种配置模式：
跳过
配置为 "skip" 的可执行文件将不会被执行。这些示例通常依赖于已连接的图形显示器，不适合此类自动化。
配置示例：
"fluidsGL": {
"skip": true
}
您将看到：
Skipping fluidsGL (marked as skip in config)
单次运行
对于只需运行一次且带有参数的可执行文件，请将每个参数指定为列表条目。JSON 文件中的每个条目都将附加到命令行，用空格分隔。
所有应用程序都在其当前目录下执行，因此所有路径都相对于应用程序的位置。
请注意，如果应用程序不需要参数，此条目是可选的。在 JSON 中找不到匹配条目的可执行文件将仅从其当前目录运行 ./application。
配置示例：
"ptxgen": {
"args": [
"test.ll",
"-arch=compute_75"
]
}
您将看到：
Running ptxgen
Command: ./ptxgen test.ll -arch=compute_75
Test completed with return code 0
多次运行
对于需要使用不同命令行参数运行多次的可执行文件，请在 "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
Running recursiveGaussian (run 3/4)
Command: ./recursiveGaussian -sigma=18 -file=data/ref_18.ppm
Test completed with return code 0
Running recursiveGaussian (run 4/4)
Command: ./recursiveGaussian -sigma=22 -file=data/ref_22.ppm
Test completed with return code 0
以下是一组构建和测试所有示例的命令示例。
首先，构建：
mkdir build
cd build
cmake ..
make -j$(nproc)
现在，返回到示例根目录并运行测试脚本：
cd ..
python3 run_tests.py --output ./test --dir ./build/Samples --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），以帮助从输出日志中确定可能出错的地方。如果您认为某个示例在您的系统上错误地失败，请针对示例仓库提交问题。
面向初学者的基础 CUDA 示例，说明了使用 CUDA 和 CUDA 运行时 API 的关键概念。
实用工具示例，演示如何查询设备功能和测量 GPU/CPU 带宽。
演示 CUDA 相关概念和常见问题解决技术的示例。
演示 CUDA 功能（协作组、CUDA 动态并行性、CUDA 图等）的示例。
演示如何使用 CUDA 平台库（NPP、NVJPEG、NVGRAPH、cuBLAS、cuFFT、cuSPARSE、cuSOLVER 和 cuRAND）的示例。
针对特定领域（图形、金融、图像处理）的示例。
演示性能优化的示例。
演示 libNVVVM 和 NVVM IR 使用的示例。
针对特定平台（Tegra、cuDLA、NvMedia、NvSci、OpenGL ES）的示例。
一些 CUDA 示例依赖于第三方应用程序和/或库，或者 CUDA 工具包和驱动程序提供的功能，以便构建或执行。这些依赖项如下所列。
如果示例具有系统上可用但未安装的第三方依赖项，该示例将在构建时自行放弃。
每个示例的依赖项在其 README 的 Dependencies 部分中列出。
这些第三方依赖项是一些 CUDA 示例所必需的。如果可用，这些依赖项要么自动安装在您的系统上，要么可以通过系统的包管理器（Linux）或第三方网站安装。
FreeImage 是一个开源图像库。通常可以使用 Linux 发行版的包管理器