Skip to content

Commit 6e62e39

Browse files
AlAuAuAlAuAu
authored
Merge branch 'develop' into apifix2.3
2 parents 5ff6506 + e65807d commit 6e62e39

File tree

1,247 files changed

+63184
-10459
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,247 files changed

+63184
-10459
lines changed

‎.agents/skills/paddle-build/SKILL.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
---
2+
name: paddle-build
3+
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.
4+
---
5+
6+
# Paddle 源码编译
7+
8+
## 概览
9+
10+
Paddle 使用 CMake + Ninja 构建。典型流程：cmake 配置 → ninja 编译 → whl 打包安装。修改 C++/CUDA 代码后需重新编译才能生效。
11+
12+
## 编译流程
13+
14+
### 1. 环境准备（venv）
15+
16+
```bash
17+
cd /workspace/Paddle
18+
uv venv --relocatable --seed --python 3.10 # 首次创建
19+
source .venv/bin/activate
20+
uv pip install -r python/requirements.txt
21+
uv pip install func_timeout pandas numpy "numpy<2.0"
22+
```
23+
24+
若 `.venv` 已存在，直接 `source .venv/bin/activate` 即可。
25+
26+
### 2. CMake 配置
27+
28+
```bash
29+
mkdir -p build && cd build
30+
cmake .. \
31+
-GNinja \
32+
-DCMAKE_BUILD_TYPE=Release \
33+
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
34+
-DPY_VERSION=3.10 \
35+
-DPADDLE_VERSION=0.0.0 \
36+
-DCUDA_ARCH_NAME=Auto \
37+
-DWITH_GPU=ON \
38+
-DWITH_DISTRIBUTE=ON \
39+
-DWITH_CINN=ON \
40+
-DWITH_UNITY_BUILD=OFF \
41+
-DWITH_TESTING=OFF
42+
```
43+
44+
配置只需首次执行或 CMake 选项变更时重新执行。
45+
46+
### 3. 编译
47+
48+
```bash
49+
ninja -j$(nproc)
50+
```
51+
52+
Ninja 自动增量编译，仅重编变更文件及其依赖。
53+
54+
### 4. 安装
55+
56+
```bash
57+
cd /workspace/Paddle
58+
uv pip install build/python/dist/*.whl --no-deps --force-reinstall
59+
```
60+
61+
`--no-deps` 跳过依赖解析加速安装，`--force-reinstall` 确保覆盖旧版。
62+
63+
## 常用 CMake 选项
64+
65+
| 选项 | 默认 | 说明 |
66+
|------|------|------|
67+
| `WITH_GPU` | ON(有CUDA时) | GPU 支持 |
68+
| `WITH_DISTRIBUTE` | OFF | 分布式训练 |
69+
| `WITH_CINN` | OFF | CINN 编译器 |
70+
| `WITH_TESTING` | ON | C++ 单测（关闭可加速编译） |
71+
| `WITH_UNITY_BUILD` | OFF | 合并编译单元加速（可能掩盖头文件问题） |
72+
| `CUDA_ARCH_NAME` | Auto | GPU 架构，Auto 自动检测当前卡 |
73+
| `CMAKE_BUILD_TYPE` | Release | Debug 可调试但更慢 |
74+
| `CMAKE_EXPORT_COMPILE_COMMANDS` | OFF | 生成 `compile_commands.json` 供 clangd 使用 |
75+
| `WITH_TENSORRT` | OFF | TensorRT 推理加速 |
76+
| `WITH_ROCM` | OFF | AMD ROCm 支持 |
77+
| `WITH_XPU` | OFF | 百度昆仑 XPU 支持 |
78+
79+
## 增量编译策略
80+
81+
```dot
82+
digraph incremental {
83+
"修改了什么?" [shape=diamond];
84+
"Python 代码" [shape=box, label="无需编译\n同步源码到构建目录后测试"];
85+
"C++/CUDA kernel" [shape=box, label="ninja → 安装 whl"];
86+
"CMakeLists / cmake 选项" [shape=box, label="重新 cmake → ninja → 安装 whl"];
87+
"YAML (ops/backward)" [shape=box, label="ninja（触发代码生成）→ 安装 whl"];
88+
89+
"修改了什么?" -> "Python 代码" [label="python/"];
90+
"修改了什么?" -> "C++/CUDA kernel" [label="paddle/phi/"];
91+
"修改了什么?" -> "CMakeLists / cmake 选项" [label="cmake/"];
92+
"修改了什么?" -> "YAML (ops/backward)" [label="ops.yaml 等"];
93+
}
94+
```
95+
96+
- **仅改 Python**：无需编译。如果直接在 `build/python` 下编辑测试，改动即时生效。也可以在源码目录编辑后通过 `cp python/<src> build/python/<src>` 或者 `cp test/<src> build/test/<src>` 同步到构建目录。
97+
- **改 C++/CUDA**：`cd build && ninja -j$(nproc)` + 重新安装 whl。
98+
- **改 CMake 配置**：需重新 `cmake ..` 再 `ninja`。
99+
- **改 YAML（ops.yaml / backward.yaml）**：ninja 会自动触发代码生成脚本。
100+
101+
## 检查已有构建产物
102+
103+
复用已有 build 可大幅节约时间：
104+
105+
```bash
106+
# 检查是否已有 whl
107+
ls build/python/dist/*.whl 2>/dev/null && echo "已有构建产物" || echo "需要编译"
108+
109+
# 检查 compile_commands.json（clangd 需要）
110+
ls build/compile_commands.json 2>/dev/null
111+
```
112+
113+
## 常见编译问题
114+
115+
| 症状 | 原因 | 解决 |
116+
|------|------|------|
117+
| `ninja: error: loading 'build.ninja'` | 未执行 cmake 配置 | 先执行 cmake 命令 |
118+
| CUDA arch 不匹配 | `CUDA_ARCH_NAME` 与实际 GPU 不符 | 设为 `Auto` 或指定具体架构 |
119+
| 链接时 OOM | 并行链接占用过多内存 | `ninja -j4` 减少并行度 |
120+
| protobuf 版本冲突 | 系统 protobuf 与编译版本不一致 | 在 venv 内编译，隔离系统包 |
121+
| `ccache` 缓存失效导致全量重编 | 头文件路径变更 | 清理 ccache: `ccache -C` |
122+
| whl 安装后 import 报错 | 旧 .so 残留 | `--force-reinstall` 或清理 `site-packages/paddle` |
123+
124+
## 完整一键编译示例
125+
126+
```bash
127+
cd /workspace/Paddle
128+
source .venv/bin/activate
129+
cd build
130+
ninja -j$(nproc) && cd .. && uv pip install build/python/dist/*.whl --no-deps --force-reinstall
131+
```
132+
133+
## 调试编译（Debug 模式）
134+
135+
需要 gdb 调试 C++ 代码时，将 `CMAKE_BUILD_TYPE` 改为 `Debug`：
136+
137+
```bash
138+
cmake .. -GNinja -DCMAKE_BUILD_TYPE=Debug [其他选项...]
139+
ninja -j$(nproc)
140+
```
141+
142+
Debug 模式编译产物更大、运行更慢，仅在需要调试时使用。
143+
144+
## 关键目录
145+
146+
| 目录 | 说明 |
147+
|------|------|
148+
| `build/` | 构建产物根目录 |
149+
| `build/python/dist/` | 生成的 whl 文件 |
150+
| `build/compile_commands.json` | clangd 索引文件 |
151+
| `paddle/phi/kernels/` | PHI kernel 源码 |
152+
| `paddle/phi/ops/yaml/` | 算子 YAML 定义 |
153+
| `cmake/` | CMake 模块和工具链 |
154+
155+
## 平台特定指南
156+
157+
| 平台 | 参考文档 |
158+
|------|---------|
159+
| macOS (Apple Silicon) CPU 编译 | [references/mac-build.md](references/mac-build.md) |

‎.agents/skills/paddle-build/references/mac-build.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# macOS (Apple Silicon) 源码编译
2+
3+
在 macOS Apple Silicon (M1/M2/M3/M4 等) 上从源码编译 Paddle 的完整流程。仅支持 CPU 模式（无 GPU/CUDA）。
4+
5+
## 前置依赖
6+
7+
通过 Homebrew 安装：
8+
9+
```bash
10+
brew install cmake ninja uv
11+
```
12+
13+
需要的工具和最低版本：
14+
- **cmake** >= 3.19.2（Apple Silicon 支持从此版本开始）
15+
- **ninja**（推荐，比 make 快很多）
16+
- **uv**（Python 环境管理）
17+
- **Xcode Command Line Tools**：`xcode-select --install`
18+
19+
## 编译流程
20+
21+
### 1. 创建 Python 虚拟环境
22+
23+
```bash
24+
cd /path/to/Paddle
25+
PY_VERSION=3.10
26+
VENV_DIR=venvs/paddle-py${PY_VERSION//./}
27+
28+
uv venv --seed ${VENV_DIR} --python=${PY_VERSION}
29+
source ${VENV_DIR}/bin/activate
30+
uv pip install -r python/requirements.txt
31+
```
32+
33+
### 2. 获取 Python 路径
34+
35+
macOS 上需要显式指定 Python 库和头文件路径：
36+
37+
```bash
38+
PY_LIB_DIR=$(python -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
39+
PY_INCLUDE_DIR=$(python -c "import sysconfig; print(sysconfig.get_paths()['include'])")
40+
PY_LIBRARY=${PY_LIB_DIR}/libpython${PY_VERSION}.dylib
41+
```
42+
43+
### 3. CMake 配置
44+
45+
```bash
46+
mkdir -p build && cd build
47+
rm -rf CMakeCache.txt CMakeFiles/ # 首次或切换配置时需要清理
48+
49+
cmake .. \
50+
-GNinja \
51+
-DPY_VERSION=${PY_VERSION} \
52+
-DPYTHON_INCLUDE_DIR=${PY_INCLUDE_DIR} \
53+
-DPYTHON_LIBRARY=${PY_LIBRARY} \
54+
-DWITH_GPU=OFF \
55+
-DWITH_ARM=ON \
56+
-DWITH_AVX=OFF \
57+
-DWITH_TESTING=ON \
58+
-DWITH_DISTRIBUTE=OFF \
59+
-DCMAKE_BUILD_TYPE=Release \
60+
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON
61+
```
62+
63+
关键选项说明：
64+
65+
| 选项 | 值 | 原因 |
66+
|------|----|------|
67+
| `WITH_GPU` | OFF | macOS 无 CUDA |
68+
| `WITH_ARM` | ON | Apple Silicon 是 ARM 架构 |
69+
| `WITH_AVX` | OFF | ARM 无 AVX 指令集，`WITH_ARM=ON` 时自动禁用 |
70+
| `WITH_DISTRIBUTE` | OFF | macOS 不支持 NCCL 等分布式通信库 |
71+
| `WITH_TESTING` | ON/OFF | ON 编译测试二进制（更慢），OFF 跳过（更快） |
72+
| `CMAKE_EXPORT_COMPILE_COMMANDS` | ON | 生成 `compile_commands.json` 供 clangd/IDE 使用 |
73+
74+
### 4. 编译
75+
76+
```bash
77+
ninja -j$(sysctl -n hw.ncpu)
78+
```
79+
80+
macOS 使用 `sysctl -n hw.ncpu` 获取 CPU 核数（Linux 用 `nproc`）。
81+
82+
首次全量编译约需 30-60 分钟（取决于机器配置和 `WITH_TESTING` 开关）。后续增量编译通常几秒到几分钟。
83+
84+
### 5. 安装
85+
86+
```bash
87+
cd /path/to/Paddle
88+
uv pip install build/python/dist/*.whl --no-deps --force-reinstall
89+
```
90+
91+
### 6. 验证
92+
93+
```bash
94+
python -c "import paddle; print(paddle.__version__); paddle.utils.run_check()"
95+
```
96+
97+
## 一键脚本
98+
99+
```bash
100+
#!/bin/bash
101+
set -e
102+
103+
PY_VERSION=${1:-3.10}
104+
PADDLE_DIR=$(pwd)
105+
VENV_DIR=${PADDLE_DIR}/venvs/paddle-py${PY_VERSION//./}
106+
107+
# 环境准备
108+
if [ ! -d ${VENV_DIR} ]; then
109+
uv venv --seed ${VENV_DIR} --python=${PY_VERSION}
110+
fi
111+
source ${VENV_DIR}/bin/activate
112+
uv pip install -r python/requirements.txt
113+
114+
# Python 路径
115+
PY_LIB_DIR=$(python -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
116+
PY_INCLUDE_DIR=$(python -c "import sysconfig; print(sysconfig.get_paths()['include'])")
117+
118+
# CMake 配置 + 编译
119+
mkdir -p build && cd build
120+
rm -rf CMakeCache.txt CMakeFiles/
121+
cmake .. \
122+
-GNinja \
123+
-DPY_VERSION=${PY_VERSION} \
124+
-DPYTHON_INCLUDE_DIR=${PY_INCLUDE_DIR} \
125+
-DPYTHON_LIBRARY=${PY_LIB_DIR}/libpython${PY_VERSION}.dylib \
126+
-DWITH_GPU=OFF \
127+
-DWITH_ARM=ON \
128+
-DWITH_AVX=OFF \
129+
-DWITH_TESTING=OFF \
130+
-DWITH_DISTRIBUTE=OFF \
131+
-DCMAKE_BUILD_TYPE=Release \
132+
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON
133+
ninja -j$(sysctl -n hw.ncpu)
134+
135+
# 安装
136+
cd ${PADDLE_DIR}
137+
uv pip install build/python/dist/*.whl --no-deps --force-reinstall
138+
python -c "import paddle; print(paddle.__version__)"
139+
```
140+
141+
## macOS 特有的常见问题
142+
143+
| 症状 | 原因 | 解决 |
144+
|------|------|------|
145+
| `Ignoring CMAKE_OSX_SYSROOT` + 配置失败 | pip 安装的 cmake 无法找到系统 SDK | 用 `brew install cmake` 的系统 cmake，不要用 venv 中的 |
146+
| `failed to recurse into submodule` | git worktree 残留导致 submodule config 中路径失效 | 修复 `.git/modules/*/config` 中的 `worktree` 路径，或 `git submodule deinit -f . && git submodule update --init --recursive` |
147+
| `CMakeCache.txt directory is different` | build 目录从别的路径（如 worktree）复制过来 | `rm -rf CMakeCache.txt CMakeFiles/` 清理缓存后重新 cmake |
148+
| `WITH_AVX` 相关编译错误 | 未设置 `WITH_ARM=ON` 导致尝试使用 x86 指令集 | 添加 `-DWITH_ARM=ON -DWITH_AVX=OFF` |
149+
| 链接时 `symbol not found` | SDK 或系统库版本不匹配 | 确保 Xcode CLT 是最新版本：`xcode-select --install`，并检查 `SDKROOT` 设置（如 `export SDKROOT=$(xcrun --show-sdk-path)`） |
150+
| `libpython*.dylib not found` | Python 路径不正确 | 用 `sysconfig` 动态获取路径，不要硬编码 |
151+
152+
## 与 Linux 编译的主要差异
153+
154+
| 方面 | Linux (x86_64 + CUDA) | macOS (Apple Silicon) |
155+
|------|----------------------|----------------------|
156+
| 架构标志 | 默认 x86_64 | `-DWITH_ARM=ON -DWITH_AVX=OFF` |
157+
| GPU | `-DWITH_GPU=ON` | `-DWITH_GPU=OFF` |
158+
| BLAS | MKL | Apple Accelerate（自动检测） |
159+
| CPU 核数 | `nproc` | `sysctl -n hw.ncpu` |
160+
| Python lib | `.so` | `.dylib` |
161+
| 分布式 | NCCL 支持 | 不支持 |

0 commit comments

Comments
 (0)