📚 课程目录第4章 CUDA开发环境搭建

4. CUDA开发环境搭建：安装CUDA Toolkit，配置开发环境，编译运行第一个程序

4.1 核心原理：CUDA Toolkit的组成与版本匹配逻辑

CUDA开发环境的核心是CUDA Toolkit，它并非单一工具，而是一套完整的异构编译与运行体系。理解其内部组成，是避免后续配置混乱的前提。Toolkit主要包含四层关键组件：

NVCC编译器：负责将包含CUDA扩展（.cu）的源码分离编译为宿主（Host）代码与设备（Device）代码，并调用GPU驱动完成设备端二进制（cubin/PTX）的生成。
CUDA运行时库（cudart）：提供内存管理（cudaMalloc）、核函数启动（<<<>>>）、流同步等API，链接时需指定-lcudart。
CUDA驱动API（libcuda）：更底层的接口，直接与GPU驱动通信，通常由运行时库间接调用。
CUDA核心头文件与工具：如cuda_runtime.h、device_launch_parameters.h，以及性能分析工具nsight-compute、nsight-systems。

版本匹配是环境搭建中最易出错的一环。CUDA Toolkit版本必须与GPU驱动版本兼容，且需满足编译器（GCC/VS）的版本要求。例如，CUDA 12.x要求Linux内核驱动版本≥535.xx，且不支持过旧的GCC。下图展示了CUDA Toolkit、驱动与硬件之间的依赖关系：

从上图可以看出，驱动是向下兼容的：新驱动可以运行旧版CUDA编译的程序，但旧驱动无法运行新版CUDA编译的程序。因此，安装前务必使用nvidia-smi查看驱动版本，再选择匹配的Toolkit版本。

4.2 方法流程：从零搭建CUDA开发环境

以Ubuntu 22.04 + NVIDIA驱动 + CUDA 12.4为例，完整流程分为四步。每一步都有对应的验证方法，确保环境真正可用。

步骤1：确认GPU与驱动

# 查看GPU型号
lspci | grep -i nvidia

# 查看当前驱动版本（若未安装则无输出）
nvidia-smi

# 若驱动未安装，先通过系统包管理器安装（推荐使用官方runfile或apt源）
sudo apt update
sudo apt install -y nvidia-driver-550
sudo reboot

驱动安装成功后，nvidia-smi应显示GPU名称、驱动版本及CUDA版本（注意：此处显示的CUDA是驱动支持的最高版本，并非已安装的Toolkit版本）。

步骤2：下载并安装CUDA Toolkit

# 从NVIDIA官网获取对应版本的runfile（以12.4为例）
wget https://developer.download.nvidia.com/compute/cuda/12.4.0/local_installers/cuda_12.4.0_550.54.14_linux.run

# 执行安装（注意：不要安装驱动，因为已装好）
sudo sh cuda_12.4.0_550.54.14_linux.run --toolkit --silent --override

# 配置环境变量
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

步骤3：验证Toolkit安装

# 检查nvcc版本
nvcc --version

# 编译并运行设备查询示例
cd /usr/local/cuda-12.4/samples/1_Utilities/deviceQuery
sudo make
./deviceQuery

若输出包含Detected 1 CUDA Capable device(s)且最后显示PASSED，则Toolkit安装成功。

步骤4：配置IDE（以VS Code为例）

# 安装C/C++扩展与NVIDIA NSight扩展
code --install-extension ms-vscode.cpptools
code --install-extension nvidia.nsight-vscode-editor

# 在.vscode/c_cpp_properties.json中配置includePath
{
  "configurations": [{
    "name": "CUDA",
    "includePath": ["/usr/local/cuda-12.4/include"],
    "defines": [],
    "compilerPath": "/usr/local/cuda-12.4/bin/nvcc"
  }]
}

4.3 案例实战：编译运行第一个CUDA程序

下面通过一个向量加法程序，完整演示从源码到运行的流程。该程序包含核函数、内存管理、错误检查三个核心要素。

// vector_add.cu
#include <stdio.h>
#include <cuda_runtime.h>

// 核函数：每个线程计算一个元素
__global__ void vectorAdd(const float *a, const float *b, float *c, int n) {
    int i = blockIdx.x * blockDim.x + threadIdx.x;
    if (i < n) {
        c[i] = a[i] + b[i];
    }
}

int main() {
    int n = 1 << 20;  // 1,048,576 个元素
    size_t bytes = n * sizeof(float);

    // 1. 分配主机内存并初始化
    float *h_a = (float*)malloc(bytes);
    float *h_b = (float*)malloc(bytes);
    float *h_c = (float*)malloc(bytes);
    for (int i = 0; i < n; i++) { h_a[i] = 1.0f; h_b[i] = 2.0f; }

    // 2. 分配设备内存
    float *d_a, *d_b, *d_c;
    cudaMalloc(&d_a, bytes);
    cudaMalloc(&d_b, bytes);
    cudaMalloc(&d_c, bytes);

    // 3. 拷贝数据到设备
    cudaMemcpy(d_a, h_a, bytes, cudaMemcpyHostToDevice);
    cudaMemcpy(d_b, h_b, bytes, cudaMemcpyHostToDevice);

    // 4. 配置网格与块并启动核函数
    int threads = 256;
    int blocks = (n + threads - 1) / threads;
    vectorAdd<<<blocks, threads>>>(d_a, d_b, d_c, n);

    // 5. 拷贝结果回主机
    cudaMemcpy(h_c, d_c, bytes, cudaMemcpyDeviceToHost);

    // 6. 验证结果
    float max_err = 0.0f;
    for (int i = 0; i < n; i++) {
        max_err = fmax(max_err, fabs(h_c[i] - 3.0f));
    }
    printf("最大误差: %f\n", max_err);

    // 7. 释放内存
    cudaFree(d_a); cudaFree(d_b); cudaFree(d_c);
    free(h_a); free(h_b); free(h_c);
    return 0;
}

编译与运行命令如下：

# 编译（-arch指定计算能力，sm_86对应RTX 30系列）
nvcc -arch=sm_86 -o vector_add vector_add.cu

# 运行
./vector_add
# 预期输出：最大误差: 0.000000

下表总结了该程序的关键API及其作用，便于对照理解：

API / 语法	作用	注意事项
`__global__`	声明核函数，由GPU执行	必须返回void，不能是类成员
`<<<blocks, threads>>>`	配置网格维度与块维度	threads通常取128~256的倍数
`cudaMalloc()`	在设备端分配全局内存	需检查返回值是否为`cudaSuccess`
`cudaMemcpy()`	主机与设备间数据拷贝	方向参数不可写反
`cudaFree()`	释放设备内存	与cudaMalloc成对出现

4.4 误区与复盘：环境搭建中的常见陷阱

陷阱1：误将nvidia-smi显示的CUDA版本当作已安装的Toolkit版本。
该版本仅表示驱动支持的最高CUDA版本。若未安装Toolkit，执行nvcc --version会提示“command not found”。正确做法是分别验证驱动与Toolkit。

陷阱2：编译时未指定-arch导致运行失败。
默认情况下nvcc会生成兼容性较好的PTX代码，但性能可能不佳。若指定了错误的架构（如sm_90用于旧卡），会报“invalid device function”错误。建议使用-arch=native自动检测（需CUDA 11.5+）。

复盘建议：每次编译前先执行nvcc --version确认环境变量生效；运行程序前用deviceQuery确认GPU可见。若遇到“unable to load dynamic library libcudart.so”，说明LD_LIBRARY_PATH未正确配置。

另一个高频错误是忘记检查CUDA API返回值。在调试阶段，建议封装一个错误检查宏：

#define CHECK_CUDA(call) do { \
    cudaError_t err = (call); \
    if (err != cudaSuccess) { \
        fprintf(stderr, "CUDA错误 %s:%d: %s\n", __FILE__, __LINE__, \
                cudaGetErrorString(err)); \
        exit(EXIT_FAILURE); \
    } \
} while(0)

// 使用方式
CHECK_CUDA(cudaMalloc(&d_a, bytes));

最后，务必注意主机与设备内存的生命周期。在核函数尚未执行完毕时释放设备内存，或未同步就读取结果，都会导致未定义行为。正确做法是在cudaMemcpy回拷结果前，确保核函数已完成（cudaMemcpy本身具有隐式同步功能）。