2、环境搭建：NVSHMEM 安装、编译选项、与CUDA和GDRCopy的依赖关系

环境搭建这事儿，说简单也简单，说坑也多。我刚开始接触NVSHMEM时，以为就是个普通的库，装上去就能用。结果呢？折腾了两天才跑通第一个示例。今天我把这些经验掰开揉碎讲给你听。

2.1 前置依赖：CUDA Toolkit 和 GDRCopy

NVSHMEM不是孤立的。它依赖两个核心组件：CUDA Toolkit 和 GDRCopy。说白了，CUDA提供GPU计算能力，GDRCopy提供GPU与网卡之间的直接数据通道。

为什么会这样？因为NVSHMEM的设计哲学就是「让GPU直接访问远端GPU的显存」。没有GDRCopy，数据就得先拷贝到CPU内存，再通过网络发出去——那延迟就上去了。

2.2 安装步骤：从源码编译 NVSHMEM

我个人习惯从源码编译，这样能控制编译选项。官方也提供预编译包，但生产环境我建议自己编译。

先下载源码：

git clone https://github.com/NVIDIA/nvshmem.git
cd nvshmem
git checkout v2.6.0  # 选一个稳定版本

然后配置编译选项。这里有个坑：一定要指定 CUDA 路径和 GDRCopy 路径。我遇到过有人没设路径，编译出来跑不了。

mkdir build && cd build
cmake .. \
  -DCMAKE_INSTALL_PREFIX=/usr/local/nvshmem \
  -DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda-11.8 \
  -DGDRCOPY_ROOT=/usr/local/gdrcopy \
  -DNVSHMEM_BUILD_TESTS=ON

make -j$(nproc)
make install

2.3 编译选项详解

NVSHMEM 的 CMake 选项很多，我挑几个关键的讲：

编译选项	默认值	说明
NVSHMEM_BUILD_TESTS	OFF	是否编译测试用例。我建议开启，方便验证安装是否正确。
NVSHMEM_USE_GDRCOPY	ON	是否启用 GDRCopy。如果没装 GDRCopy，记得关掉，否则编译会报错。
NVSHMEM_USE_NCCL	OFF	是否集成 NCCL。如果你做多节点通信，建议开启。
NVSHMEM_MPI_SUPPORT	ON	是否支持 MPI 启动。我建议开启，方便调试。

嗯，这里要注意：GDRCopy 和 NCCL 的选项是互斥的吗？ 不是。它们可以同时开启。GDRCopy 负责单节点内的 GPU 内存访问，NCCL 负责多节点间的集合通信。两者分工不同。

2.4 与 CUDA 的依赖关系

NVSHMEM 和 CUDA 的关系，就像发动机和汽油。没有 CUDA，NVSHMEM 就是个空壳。

具体来说：

• 编译时：NVSHMEM 需要 CUDA 的 nvcc 编译器和 cuda_runtime.h 头文件。
• 运行时：NVSHMEM 调用 CUDA 的 cudaMemcpy、cudaMalloc 等 API 来管理显存。
• 版本兼容性：NVSHMEM 2.6 要求 CUDA ≥ 11.0。我试过 CUDA 10.2，编译直接报错。

2.5 与 GDRCopy 的依赖关系

GDRCopy 是个轻量级库，但它的作用很大。它允许 CPU 通过 PCIe 直接读写 GPU 显存，不需要经过 CUDA 驱动。

安装 GDRCopy 也很简单：

git clone https://github.com/NVIDIA/gdrcopy.git
cd gdrcopy
make
sudo make install

装完后，检查一下 /dev/gdrdrv 设备是否存在。如果没有，说明内核模块没加载。我遇到过这种情况，重启一下就好了。

NVSHMEM 和 GDRCopy 的交互流程是这样的：

1. NVSHMEM 调用 nvshmem_malloc 分配显存。
2. GDRCopy 将这块显存映射到 CPU 的虚拟地址空间。
3. 网卡通过 RDMA 直接读写这个映射后的地址。

说白了，GDRCopy 就是一座桥，让 GPU 显存和网卡直接对话。

2.6 验证安装：跑一个简单的测试

装完之后，跑个测试验证一下：

cd build
mpirun -np 2 ./test/simple/simple_put

如果看到类似这样的输出，说明安装成功：

Rank 0: put value 42 to rank 1
Rank 1: got value 42 from rank 0
PASSED

如果报错，先检查环境变量：

• LD_LIBRARY_PATH 是否包含 NVSHMEM 和 CUDA 的 lib 路径。
• CUDA_VISIBLE_DEVICES 是否设置了正确的 GPU 编号。
• GDRCopy 的内核模块是否加载（lsmod | grep gdr）。

2.7 知识体系结构图

下面这张图展示了 NVSHMEM 环境搭建的完整依赖链：

从这张图可以看得很清楚：NVSHMEM 站在 CUDA 和 GDRCopy 的肩膀上，而这两者又依赖底层的 GPU、网卡和 PCIe 总线。任何一个环节出问题，NVSHMEM 都跑不起来。

2.8 常见问题与避坑

最后，我总结几个我踩过的坑：

• GDRCopy 内核模块没加载：运行 sudo modprobe gdrdrv 手动加载，或者加到 /etc/modules 里开机自启。
• CUDA 版本不匹配：NVSHMEM 编译时用的 CUDA 版本和运行时必须一致。我建议用 nvcc --version 和 nvidia-smi 双重确认。
• MPI 启动参数不对：多节点运行时，记得用 --hostfile 指定节点列表，否则 MPI 会报错。
• 权限问题：GDRCopy 需要 root 权限加载内核模块。如果普通用户跑测试，记得 chmod 666 /dev/gdrdrv。

---