faster linux build

docs/publishing.md

@@ -234,3 +234,58 @@ root = distribution("orisys").locate_file("orisys")   # site-packages/orisys
 
 如果以后需要离线 API 参考，加一个只包含 `docs/api.md` 的窄条目即可，不要整个 `docs/` 都塞进去。
 
+---
+
+## 6. 缩短 manylinux 构建时间
+
+`python build/run.py manylinux` 走 `build/wheel/docker/run.ps1` → 容器内 `entrypoint.sh`，对 `cp310/cp311/cp312` **串行**各做一次 Nuitka 编译 + 打 wheel + auditwheel repair + 隔离 venv 校验。
+
+### 6.1 镜像里已经烘好的东西（所以每次构建不必再拉）
+
+`Dockerfile.manylinux` 在每个 ABI 下预置了两类内容：
+
+1. **构建工具**：`pip`/`setuptools`/`wheel`/`nuitka`/`ordered-set`/`zstandard`/`auditwheel`。
+   因此 `entrypoint.sh` 默认**不再**在每个 ABI 上重跑 `pip install --upgrade pip setuptools wheel auditwheel` —— 那是每次构建 3 次多余的 PyPI 往返，还会让容器里的工具版本与镜像不一致。需要用最新工具时显式开启：
+
+   ```powershell
+   docker run ... -e ORISYS_UPDATE_BUILD_TOOLS=1 ...
+   ```
+
+2. **每个 ABI 一个 wheelhouse**（`/opt/orisys-wheelhouse/<tag>`），内含 `numpy`/`scipy`/`opencv-python`/`numba` 及其依赖闭包，外加 `pip`/`setuptools`/`wheel`/`auditwheel` 的 wheel。
+
+   `--target pypi-linux` 会**强制**校验：为每个 ABI 建一个一次性 venv，再 `pip install` 刚构建的 wheel 和它声明的运行期依赖。镜像故意不把运行期依赖装进解释器（用户是凭 wheel 元数据装的），所以以前每次构建都要现下约 200 MB × 3。`entrypoint.sh` 现在用 `PIP_NO_INDEX=1` + `PIP_FIND_LINKS=<wheelhouse>` 把 pip 指向本地 wheelhouse：**venv 仍然是隔离的**（没有 `--system-site-packages`），依赖解析与安装依然真实发生，只是不走网络。
+
+   找不到 wheelhouse 时会打印警告并回退到联网，不会静默失败。镜像因此增大约 400–500 MB（一次性代价，换每次构建省三次下载）。
+
+### 6.2 不要为了省事直接重建镜像
+
+只改了源码（`src/`、`config/`、`sensors/`、`examples/`、`pyproject.toml`）时加 `-SkipImageBuild`：
+
+```powershell
+.\build\wheel\docker\run.ps1 -SkipImageBuild
+```
+
+Dockerfile 的 `RUN` 层要装 3 份工具链并下载 3 个 wheelhouse，缓存未命中就是数分钟。**改了 `Dockerfile.manylinux` 或需要更新 wheelhouse 时才重建镜像**。
+
+### 6.3 Nuitka 的排除列表必须完整
+
+`build/wheel/compile.py::NUITKA_NOFOLLOW_IMPORTS` 列出所有**不打进 wheel、运行期从用户环境解析**的第三方包。漏一个意味着 Nuitka 会尝试把它跟进来：编译时间暴涨，而且 wheel 内容开始取决于构建机上恰好装了什么 —— `torch`、`torchvision`（`src/orisys/tracker.py` 的 RAFT 追踪器）和 `pyvkfft`（`backend_availability.py`）就是这样漏掉的，之前只是靠「构建机上没装」才没出事。
+
+`tests/test_nuitka_nofollow.py` 会扫描 `src/orisys` 的全部第三方导入，任何不在排除列表里的都会让测试失败。**新增可选依赖时同步更新列表。**
+
+### 6.4 想要并行？先读这一段
+
+`--jobs` 的默认值是**全部 CPU 数**，单次编译的 C 阶段已经吃满所有核心。真正能靠并行省下的是 Nuitka 的单线程前端（分析/优化/代码生成）、scons 启动、`auditwheel` 与 venv 校验 —— 做法是 3 路并行 + 每个 build 限 `--jobs=<核数/3>`。
+
+但**现在不能直接并行**：`build/common/paths.py` 里的工作目录是写死的共享路径
+
+```
+build/nuitka/compile
+build/nuitka/wheel
+build/nuitka/wheel/repaired
+```
+
+而 `build/wheel/build.py` 每次开头都 `_reset_dir()`（`rmtree`）这两个目录，`auditwheel repair` 又会再 `rmtree` 一次 `repaired`。仓库是挂载进容器的（`-v ${RepoRoot}:/src`），所以无论「一个容器 3 路并行」还是「3 个容器并行」，只要共享同一个挂载点，三个 build 就会互相清空暂存目录 —— 表现为随机失败或 wheel 内容错乱。
+
+要并行必须先让工作目录带上 ABI 标签（如 `build/nuitka/<tag>/compile`）。输出路径不用动：`SDK/<version>/`、`dist/repaired/` 的文件名本来就按 ABI 区分，下游 `release preflight` 不受影响。另外 3 个 Nuitka 并行很吃内存，先把 Docker Desktop 内存调到 16 GB 以上再试。
+