📚 课程目录第2章搭建IGX开发环境

2. 搭建IGX开发环境

IGX 平台上的并行与推理优化，第一步不是写 kernel，而是把“宿主机—目标机—工具链”三者关系理顺。IGX Orin 开发套件本质是一台 ARM64 的嵌入式 AI 计算机，其 GPU 为 Ampere 架构并集成 DLA、PVA 等加速单元。因此开发环境有两种典型形态：本机原生开发（直接在 IGX 上编译运行）和交叉编译开发（在 x86_64 Ubuntu 主机上编译，部署到 IGX 运行）。本节围绕 JetPack SDK 的组成、CUDA/cuDNN/TensorRT 的安装与校验、交叉编译工具链配置，以及远程调试链路搭建展开。

一、JetPack SDK 的组成与安装方式

JetPack 是 NVIDIA 为 Jetson/IGX 系列提供的统一 SDK，它并不是一个单独的安装包，而是一组组件的集合：底层是 L4T（Linux for Tegra），包含 Bootloader、Linux 内核、根文件系统与驱动；上层是 CUDA Toolkit、cuDNN、TensorRT、VisionWorks、Multimedia API 等计算与推理库。IGX 对应的 JetPack 版本通常与 IGX 软件栈（IGX OS + IGX Board Support Package）配套发布，安装前必须确认版本对应关系，否则会出现驱动与库不匹配。

安装方式主要有三种：

SDK Manager 刷机：在 x86_64 Ubuntu 主机上运行 NVIDIA SDK Manager，通过 USB-C 连接 IGX，选择目标型号与 JetPack 版本，一次性刷写 L4T 并安装主机侧交叉编译组件与目标侧运行库。这是最推荐的方式，能保证版本一致性。
预装镜像：IGX 出厂或厂商提供的镜像已包含完整 JetPack，开机即可用，适合快速验证。
apt 增量安装：在已运行的 IGX 上通过 NVIDIA 的 apt 源安装 nvidia-jetpack 元包，适合补装组件。

安装完成后，用以下命令确认基础环境：

# 查看 L4T 版本与 JetPack 版本
cat /etc/nv_tegra_release
# 输出示例：R35 (release), REVISION: 4.1, GCID: 32827747

# 查看 CUDA 编译器
nvcc --version
# 输出示例：Cuda compilation tools, release 11.4, V11.4.239

# 查看 GPU 与加速器
nvidia-smi        # 部分 IGX 镜像支持
ls /dev/nvhost-*  # 确认 nvhost 设备节点存在

二、CUDA Toolkit、cuDNN、TensorRT 的安装与校验

在 IGX 上，CUDA Toolkit 通常已随 JetPack 安装，路径为 /usr/local/cuda，并软链到具体版本如 /usr/local/cuda-11.4。需要把 bin 与 lib64 加入环境变量：

export PATH=/usr/local/cuda/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
export CUDA_HOME=/usr/local/cuda

cuDNN 是深度神经网络原语库，TensorRT 是推理优化与运行时引擎。二者在 JetPack 中通过 apt 安装，安装后应校验头文件与库文件是否齐全：

# cuDNN 校验
ls /usr/include/cudnn*.h
ls /usr/lib/aarch64-linux-gnu/libcudnn*

# TensorRT 校验
dpkg -l | grep tensorrt
ls /usr/lib/aarch64-linux-gnu/libnvinfer*

一个常见的坑是：TensorRT 的 Python 绑定与 C++ 库版本必须一致。若用 pip install tensorrt 覆盖了系统自带版本，容易出现 libnvinfer.so 找不到或 ABI 不匹配。建议优先使用 JetPack 自带的 TensorRT，并通过 python3 -c "import tensorrt; print(tensorrt.__version__)" 确认版本。

校验 CUDA 是否真正可用，不要只看 nvcc --version，应编译并运行一个最小 deviceQuery 或向量加法样例，确认 GPU 能被枚举、kernel 能启动。

三、交叉编译工具链配置

当宿主机是 x86_64、目标机是 IGX（aarch64）时，需要交叉编译。NVIDIA 提供 Bootlin 工具链（aarch64--glibc--stable）或使用 Ubuntu 的 gcc-aarch64-linux-gnu。交叉编译 CUDA 代码时，nvcc 需要指定目标架构与主机编译器：

# 安装交叉编译器
sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

# 交叉编译 CUDA 示例
nvcc -ccbin aarch64-linux-gnu-g++ \
     -gencode arch=compute_87,code=sm_87 \
     -o vecadd vecadd.cu \
     -I/usr/local/cuda/include \
     -L/usr/local/cuda/lib64 -lcudart

其中 compute_87/sm_87 对应 IGX Orin 的 Ampere GPU 计算能力。若目标机是其他型号，需按实际算力调整。交叉编译产物通过 scp 或 NFS 部署到 IGX，运行前确认目标机上的 CUDA 运行时版本与编译时一致。

四、远程调试配置

远程调试的核心是让宿主机上的 IDE（如 Nsight Eclipse、VS Code）或 gdb 能连到 IGX 上的进程。常用方案有两种：

gdbserver + 交叉 gdb：在 IGX 上运行 gdbserver :1234 ./app，宿主机用 aarch64-linux-gnu-gdb 连接 target remote <IGX_IP>:1234。
Nsight Systems / Nsight Compute 远程采集：在 IGX 上运行 nsys profile 或 ncu，生成报告后拷贝回宿主机分析；也可通过 SSH 隧道直接远程启动。

下面这张图概括了从宿主机到 IGX 的完整开发链路：左侧是 x86_64 宿主机上的交叉编译与调试工具，右侧是 IGX 上的运行环境，中间通过 SSH/SCP 与 gdbserver 连接。

五、环境验证与常见问题

环境搭好后，建议按“由底向上”的顺序验证：先确认 L4T 与驱动正常，再确认 CUDA 能编译运行，然后确认 cuDNN 与 TensorRT 能加载模型，最后确认远程调试链路通畅。常见问题包括：

现象	可能原因	处理方向
nvcc 找不到	PATH 未包含 /usr/local/cuda/bin	写入 ~/.bashrc 并 source
libcudart.so 找不到	LD_LIBRARY_PATH 未设置	加入 /usr/local/cuda/lib64
TensorRT 导入失败	Python 包与系统库版本不一致	卸载 pip 版本，用 JetPack 自带
交叉编译报 ccbin 错误	未指定 aarch64 主机编译器	加 -ccbin aarch64-linux-gnu-g++
gdbserver 连接被拒	防火墙或端口未开放	检查 IGX 的 1234 端口与 SSH 隧道

不要混用不同 JetPack 版本的 CUDA 与 TensorRT。IGX 上的库路径与 x86 主机不同，交叉编译时头文件与库必须来自同一版本，否则链接阶段可能通过，运行阶段才暴露问题。

完成本节配置后，你应当能够在宿主机上编译出 aarch64 可执行文件，部署到 IGX 运行，并通过 gdbserver 或 Nsight 工具观察 kernel 行为。这是后续 CUDA 并行优化与 TensorRT 推理优化的基础环境。