LeetCUDA 环境搭建（4090 服务器）

目标：在一台无 sudo、无系统级 CUDA Toolkit 的 RTX 4090 服务器（Ubuntu，驱动 570）上，为 LeetCUDA 搭建独立的 CUDA 12.4 开发环境，全部装进 conda env，不污染系统。

最终产物：conda env leetcuda（python 3.11 + torch 2.5.1+cu124 + nvcc 12.4 + cuDNN 9.1 + gcc-13），可编译运行全部 sm_89（4090 / Ada 架构）kernel。

---

0. 前置条件确认

项	情况
GPU	RTX 4090 D（24G），驱动 570 → 目标架构 sm_89
系统 gcc	14.2.0（nvcc 12.4 不支持，需 gcc-13）
系统级 CUDA Toolkit	无（无 nvcc）
sudo	无密码权限（不能 apt）
conda	miniconda3 已装

⚠️ 关键坑：非交互 shell 里 conda 命令可能不可用（.bashrc 提前 return）。所有脚本先执行：

source ~/miniconda3/etc/profile.d/conda.sh

1. Clone 仓库 + submodule

服务器直连 GitHub 不通时，用 ghfast.top 镜像（快且稳，submodule 同理）：

git clone https://ghfast.top/https://github.com/xlite-dev/LeetCUDA.git
cd LeetCUDA
git config submodule.third-party/cutlass.url https://ghfast.top/https://github.com/NVIDIA/cutlass.git
git config submodule.third-party/cudnn-frontend.url https://ghfast.top/https://github.com/NVIDIA/cudnn-frontend.git
git submodule update --init --recursive --force

2. conda / pip 换国内源

清华镜像的 anaconda/cloud/nvidia 和 pkgs/r 已 404。策略：defaults 走清华、nvidia / conda-forge 走官方 URL。

# pip 清华源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

.condarc 关键点：

default_channels:
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
# nvidia / conda-forge 不配镜像,装包时用 -c https://conda.anaconda.org/<channel> 完整 URL

3. 创建 conda env

conda create -y -n leetcuda python=3.11
conda activate leetcuda

4. 装 CUDA 12.4 全套（坑最多）

pip wheel + conda 官方 channel 混装，版本严格对齐 12.4。

4.1 pip 装 CUDA 运行库（清华源，快）

pip install --no-cache-dir \
  nvidia-cuda-runtime-cu12==12.4.127 \
  nvidia-cuda-nvrtc-cu12==12.4.127 \
  nvidia-cublas-cu12==12.4.5.8 \
  nvidia-cudnn-cu12==9.1.0.70 \
  nvidia-cuda-cccl-cu12==12.4.127.post1   # 提供 <nv/target> 头

wheel 装在 $CONDA_PREFIX/lib/python3.11/site-packages/nvidia/<组件>/，lib 在 xxx/lib/、头文件在 xxx/include/。

4.2 conda 装 nvcc（pip wheel 只有 ptxas！）

⚠️ pip 的 nvidia-cuda-nvcc-cu12 不带 nvcc 主程序，必须 conda 装官方 nvidia channel：

conda install -y -c https://conda.anaconda.org/nvidia "cuda-nvcc=12.4"
nvcc --version   # release 12.4, V12.4.131

4.3 conda 装 gcc-13（系统 gcc 14 太新）

conda install -y -c https://conda.anaconda.org/conda-forge "gcc_linux-64=13" "gxx_linux-64=13"
# 得到 $CONDA_PREFIX/bin/x86_64-conda-linux-gnu-g++ (13.4.0)

5. 修 pip wheel 的两个布局缺陷

5.1 给 .so 建主链接

pip wheel 只有 libxxx.so.12，没有 libxxx.so（-lxxx 链接需要后者），统一补软链：

SP=$CONDA_PREFIX/lib/python3.11/site-packages/nvidia
for d in cuda_nvrtc cublas cudnn cuda_runtime cuda_cupti cusparse cusolver cufft curand nccl nvjitlink nvtx; do
  libdir="$SP/$d/lib"; [ -d "$libdir" ] || continue
  for so in "$libdir"/*.so.*; do
    [ -f "$so" ] || continue
    base=$(echo "$so" | sed -E 's/(\.so\.[0-9]+)+$//')
    ln -sf "$(basename "$so")" "$base.so"
  done
done

5.2 cudadevrt / cudart_static 空桩（最大坑）

conda 和 pip 都不提供 libcudadevrt.a 和 libcudart_static.a，但 nvcc 默认要链。若代码不实际引用 devrt 符号，空桩即可过链接：

mkdir -p .stubs
ar rcs .stubs/libcudadevrt.a      # 空 archive
ar rcs .stubs/libcudart_static.a

编译时再配 --cudart shared（用动态 cudart）+ -Xlinker -rpath,... 内嵌库路径。

6. 装 PyTorch + ninja

pip install --no-cache-dir "torch==2.5.1"   # PyPI 该版本默认 cu124 build
pip install --no-cache-dir numpy
pip install --no-cache-dir ninja             # ⚠️ torch JIT 编译必需

验证：torch.cuda.is_available() 为 True、device_count() 正确。

7. 改造编译脚本

仓库自带的 build 脚本写死了 /usr/local/cuda 路径，在 conda env 里要改四点：

1. nvcc：从 $CUDA_HOME/bin/nvcc 找（export CUDA_HOME=$CONDA_PREFIX）
2. host 编译器：-ccbin $CONDA_PREFIX/bin/x86_64-conda-linux-gnu-g++（gcc-13）
3. include：把所有 nvidia wheel 的 xxx/include 全部 -I 补齐（runtime/nvcc/cudnn/cublas/cccl/nvrtc），否则连环报头文件找不到
4. lib：各 wheel 的 xxx/lib + 系统目录（libcuda 在系统）；链接 --cudart shared + 空桩 + rpath

8. 验证

export CUDA_HOME=$CONDA_PREFIX
./build_patched.sh --clean && ./build_patched.sh --arch sm_89   # ~150s
./notes_v2_cute_sm89.bin           # 全部 kernel 数值正确性通过

最终环境清单（env: leetcuda）

组件	版本	来源
python	3.11	conda
torch	2.5.1+cu124	pip
ninja	1.13	pip（JIT 必需）
nvcc	12.4.131	conda 官方 nvidia
cuda runtime / cuBLAS / nvrtc	12.4.x	pip wheel
cuDNN	9.1.0.70	pip wheel
cccl	12.4.127.post1	pip wheel
gcc-13	13.4.0	conda 官方 conda-forge
libcuda（驱动）	570	系统自带

踩坑总结

1. GitHub 直连不通 → ghfast.top 镜像（主仓 + submodule 都要改）
2. 清华 conda 的 nvidia/r 镜像 404 → 装包用官方完整 URL -c https://conda.anaconda.org/<channel>
3. pip 的 nvcc wheel 不带 nvcc → conda 装 cuda-nvcc
4. 系统 gcc 14 太新 → conda 装 gcc-13 + -ccbin 指定
5. pip wheel 头文件分散 → 编译脚本全部 -I 补齐
6. pip wheel 只有 .so.12 无 .so → 批量建软链
7. libcudadevrt.a / libcudart_static.a 无处可装 → 空桩 + --cudart shared + rpath
8. torch JIT 报 "Ninja is required" → pip install ninja（手动编译路径不需要，JIT 路径必需）

日常使用

conda activate leetcuda && export CUDA_HOME=$CONDA_PREFIX
export TORCH_CUDA_ARCH_LIST="8.9"   # JIT 只编 sm_89

# JIT 编译跑简单 kernel
python elementwise.py

# 手动编译跑复杂 kernel（依赖 cutlass / Tensor Core）
./build_patched.sh --arch sm_89
./notes_v2_cute_sm89.bin --bench --mnk 4096,4096,4096 --bhnd 1,32,16384,128