paddle-build

name: paddle-build description: Use when needing to compile, rebuild, or install Paddle from source after code changes. Covers cmake configuration, ninja incremental build, wheel packaging, and common build failure diagnosis.

Paddle 源码编译

概览

Paddle 使用 CMake + Ninja 构建。典型流程：cmake 配置 → ninja 编译 → whl 打包安装。修改 C++/CUDA 代码后需重新编译才能生效。

编译流程

1. 环境准备（venv）

cd /workspace/Paddle
uv venv --relocatable --seed --python 3.10   # 首次创建
source .venv/bin/activate
uv pip install -r python/requirements.txt
uv pip install func_timeout pandas numpy "numpy<2.0"

若 .venv 已存在，直接 source .venv/bin/activate 即可。

2. CMake 配置

mkdir -p build && cd build
cmake .. \
  -GNinja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
  -DPY_VERSION=3.10 \
  -DPADDLE_VERSION=0.0.0 \
  -DCUDA_ARCH_NAME=Auto \
  -DWITH_GPU=ON \
  -DWITH_DISTRIBUTE=ON \
  -DWITH_CINN=ON \
  -DWITH_UNITY_BUILD=OFF \
  -DWITH_TESTING=OFF

配置只需首次执行或 CMake 选项变更时重新执行。

3. 编译

ninja -j$(nproc)

Ninja 自动增量编译，仅重编变更文件及其依赖。

4. 安装

cd /workspace/Paddle
uv pip install build/python/dist/*.whl --no-deps --force-reinstall

--no-deps 跳过依赖解析加速安装，--force-reinstall 确保覆盖旧版。

常用 CMake 选项

增量编译策略

digraph incremental {
  "修改了什么?" [shape=diamond];
  "Python 代码" [shape=box, label="无需编译\n同步源码到构建目录后测试"];
  "C++/CUDA kernel" [shape=box, label="ninja → 安装 whl"];
  "CMakeLists / cmake 选项" [shape=box, label="重新 cmake → ninja → 安装 whl"];
  "YAML (ops/backward)" [shape=box, label="ninja（触发代码生成）→ 安装 whl"];

  "修改了什么?" -> "Python 代码" [label="python/"];
  "修改了什么?" -> "C++/CUDA kernel" [label="paddle/phi/"];
  "修改了什么?" -> "CMakeLists / cmake 选项" [label="cmake/"];
  "修改了什么?" -> "YAML (ops/backward)" [label="ops.yaml 等"];
}

• 仅改 Python：无需编译。如果直接在 build/python 下编辑测试，改动即时生效。也可以在源码目录编辑后通过 cp python/<src> build/python/<src> 或者 cp test/<src> build/test/<src> 同步到构建目录。
• 改 C++/CUDA：cd build && ninja -j$(nproc) + 重新安装 whl。
• 改 CMake 配置：需重新 cmake .. 再 ninja。
• 改 YAML（ops.yaml / backward.yaml）：ninja 会自动触发代码生成脚本。

检查已有构建产物

复用已有 build 可大幅节约时间：

# 检查是否已有 whl
ls build/python/dist/*.whl 2>/dev/null && echo "已有构建产物" || echo "需要编译"

# 检查 compile_commands.json（clangd 需要）
ls build/compile_commands.json 2>/dev/null

常见编译问题

完整一键编译示例

cd /workspace/Paddle
source .venv/bin/activate
cd build
ninja -j$(nproc) && cd .. && uv pip install build/python/dist/*.whl --no-deps --force-reinstall

调试编译（Debug 模式）

需要 gdb 调试 C++ 代码时，将 CMAKE_BUILD_TYPE 改为 Debug：

cmake .. -GNinja -DCMAKE_BUILD_TYPE=Debug [其他选项...]
ninja -j$(nproc)

Debug 模式编译产物更大、运行更慢，仅在需要调试时使用。

关键目录

平台特定指南