第3章环境搭建与编译

3、环境搭建与编译：NVSHMEM库安装、CUDA环境配置、nvcc编译选项、链接NVSHMEM

说实话，环境搭建这块，我见过太多人卡在这里了。

明明代码逻辑没问题，编译死活过不去。或者跑起来就段错误，查半天发现是库没链接对。嗯，这节课咱们就把这些坑一个个填平。

3.1 NVSHMEM库安装——别走弯路

NVSHMEM的安装，说白了就两种方式：要么用预编译包，要么自己从源码编译。我个人强烈建议你走预编译路线，除非你有特殊需求。

预编译安装（推荐）

NVSHMEM被打包在NVIDIA HPC SDK里。你直接去NVIDIA官网下载对应版本的HPC SDK就行。我记得有一次项目赶进度，团队里有人非要自己编译，折腾了两天没搞定。最后换成HPC SDK，半小时就完事了。

# 下载并安装HPC SDK（以Ubuntu 20.04为例）
wget https://developer.download.nvidia.com/hpc-sdk/24.5/nvhpc_2024_245_Linux_x86_64_cuda_12.4.tar.gz
tar xzf nvhpc_2024_245_Linux_x86_64_cuda_12.4.tar.gz
cd nvhpc_2024_245_Linux_x86_64_cuda_12.4
sudo ./install

安装完成后，设置环境变量。这一步很多人会忘，然后编译时报找不到nvshmem.h。

export NVSHMEM_HOME=/opt/nvidia/hpc_sdk/Linux_x86_64/24.5/comm_libs/nvshmem
export PATH=$NVSHMEM_HOME/bin:$PATH
export LD_LIBRARY_PATH=$NVSHMEM_HOME/lib:$LD_LIBRARY_PATH

小技巧：把上面三行加到你的~/.bashrc里，一劳永逸。我每次新装机器第一件事就是干这个。

3.2 CUDA环境配置——版本匹配是命门

CUDA版本和NVSHMEM版本必须匹配。这个坑我踩过，而且踩得很惨。

我曾经在一个集群上，CUDA 11.8配了NVSHMEM 2.8，结果跑大规模测试时随机出现数据错误。查了三天，最后发现是版本不兼容导致的隐式类型转换问题。

版本对应关系大致如下：

NVSHMEM版本	最低CUDA版本	推荐CUDA版本
2.8.x	11.4	11.8
3.0.x	12.0	12.2
3.1.x	12.2	12.4

检查你的CUDA版本：

nvcc --version

如果版本不对，别硬上。去NVIDIA官网下载匹配的CUDA Toolkit，或者换个NVSHMEM版本。你想想看，底层通信库出问题，上层代码写得再好也白搭。

3.3 nvcc编译选项——这些参数必须加

编译NVSHMEM程序，nvcc的参数有讲究。不是随便写个-lnvshmem就完事的。

我习惯用这样的编译命令模板：

nvcc -arch=sm_80 -rdc=true -ccbin g++ \
     -I$NVSHMEM_HOME/include \
     -L$NVSHMEM_HOME/lib \
     -lnvshmem -lcuda -lcudart \
     -o my_app my_app.cu

几个关键点，我一个个说：

-arch=sm_80：指定GPU架构。A100用sm_80，V100用sm_70，H100用sm_90。别图省事写个sm_50，性能会差很多。
-rdc=true：这个必须加。NVSHMEM需要可重定位设备代码，不加的话链接阶段会报一堆undefined reference。
-ccbin g++：指定主机编译器。我建议用g++，兼容性最好。
-I和-L：指向NVSHMEM的头文件和库文件路径。

注意：千万别忘了-rdc=true。我见过有人抄代码时漏了这个参数，然后花了两小时排查链接错误。嗯，那个人就是我。

3.4 链接NVSHMEM——动态还是静态？

链接方式有两种：动态链接和静态链接。怎么选？看场景。

动态链接（默认）：

-lnvshmem

运行时需要libnvshmem.so在LD_LIBRARY_PATH里。好处是库更新了不用重新编译程序。

静态链接：

-lnvshmem -static-nvshmem

把NVSHMEM直接编进可执行文件。部署时省心，但文件体积会大一些。

我个人习惯在开发阶段用动态链接，方便调试。部署到生产环境时换成静态链接，避免库版本冲突。

验证链接是否成功：

ldd my_app | grep nvshmem

如果输出里有libnvshmem.so，说明动态链接成功了。如果啥都没有，那就是静态链接或者没链接上。

3.5 完整示例——从零跑通一个NVSHMEM程序

光说不练假把式。咱们写个最简单的Hello World，验证整个环境。

// hello_nvshmem.cu
#include <nvshmem.h>
#include <stdio.h>

int main() {
    int my_pe, n_pes;
    
    nvshmem_init();
    my_pe = nvshmem_my_pe();
    n_pes = nvshmem_n_pes();
    
    printf("Hello from PE %d of %d\n", my_pe, n_pes);
    
    nvshmem_finalize();
    return 0;
}

编译：

nvcc -arch=sm_80 -rdc=true -ccbin g++ \
     -I$NVSHMEM_HOME/include \
     -L$NVSHMEM_HOME/lib \
     -lnvshmem -lcuda -lcudart \
     -o hello_nvshmem hello_nvshmem.cu

运行（需要多进程）：

mpirun -np 4 ./hello_nvshmem

如果输出类似下面这样，恭喜你，环境搭好了：

Hello from PE 0 of 4
Hello from PE 1 of 4
Hello from PE 2 of 4
Hello from PE 3 of 4

避坑指南：如果运行时报错"cannot open shared object file"，检查LD_LIBRARY_PATH有没有设对。我曾经在SLURM集群上忘了在提交脚本里export这个变量，结果所有节点都报找不到库。

3.6 知识体系一览

我把这节的核心逻辑画了张图，方便你理解整个环境搭建的脉络：

这张图把整个流程串起来了。从硬件到CUDA，再到NVSHMEM库，最后到编译链接。每一步都有对应的参数和配置。你照着这个流程走，基本不会出大问题。

好了，环境搭建这块就讲这么多。记住一句话：版本匹配是底线，-rdc=true不能忘，环境变量要设对。这三条做到了，剩下的就是写代码的事了。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录

3、环境搭建与编译：NVSHMEM库安装、CUDA环境配置、nvcc编译选项、链接NVSHMEM

3.1 NVSHMEM库安装——别走弯路

3.2 CUDA环境配置——版本匹配是命门

3.3 nvcc编译选项——这些参数必须加

3.4 链接NVSHMEM——动态还是静态？

3.5 完整示例——从零跑通一个NVSHMEM程序

3.6 知识体系一览