feat(pkg): 方案 C —— lib/ 预编译 rlib 完整闭包,消费方零重编
- release.sh step2.5: 出包前 cargo clean 隔离目录 + 关 lto/embed-bitcode (旧 profile 多 hash 残留会 head -1 选错;LLVM22 bitcode 让 macOS ld(libLTO21) 解析失败) - step3.2.5: lib/ 改为拷贝 deps/ 整目录(rlib+rmeta+proc-macro dylib+原生 a), 只 glob lib*.rlib 会漏 serde_derive/tokio_macros 的 dylib → E0463 - 修正 grep -m1 channel 误匹配注释行(工具链串显示成注释) - docs §6 重写:方案 C 机制 + 三条硬约束(编译器版本/lib 完整闭包/axum 同源)+ lto=false - 双自检通过:A path 依赖离线编译;B 消费方零编译平台闭包直链 rlib 包体 288M → 160M(bitcode-free rlib 426KB vs 2.3MB)。
This commit is contained in:
1 parent
f6c3ff64ee
commit
6ee0cd14d8
2 files changed
+254
-55
No files matched your search
@@ -220,20 +220,49 @@ bash scripts/perm-smoke-jnpf.sh # 面 B 18/18(官方形状没被改坏
|
||||
|
||||
## 6. 发布与消费方依赖写法(每版本出包,不依赖 git 仓)
|
||||
|
||||
> 🔴 **2026-11-05 依赖模型变更**:原 §6 的「发布期用 `git = { tag }` 锁版本」**已废弃**
|
||||
> (见 §6.5)。改为「平台仓每个版本打一个**自包含发布包**,消费方解包到 `vendor/` 后用
|
||||
> `path` 依赖吃进去」——消费方**不再直接依赖 git 仓**、不再每次构建都 clone 整个 monorepo
|
||||
> 并重新编译 20+ 个本地 crate。
|
||||
> 🔴 **2026-11-05 依赖模型变更(两次迭代,最终形态 = 方案 C)**:
|
||||
> - 原「发布期用 `git = { tag }` 锁版本」**已废弃**(见 §6.5)。
|
||||
> - 「包内源码 + `path` 依赖(消费方重编 17 个平台 crate)」**已升级**。
|
||||
> - **最终(方案 C)**:平台每版本打**自包含包**,内含**预编译 rlib 完整闭包** `lib/`;
|
||||
> 消费方用 `--extern` + `-L dependency` 直接喂给 rustc,**零重编平台闭包、零重编
|
||||
> axum/tokio/serde/**。消费方 `cargo build` 只编自己的 crate(技能仓实测 dev ≈5.7s、
|
||||
> release ≈11s)。
|
||||
|
||||
### 6.1 为什么「纯预编译 rlib」不可行(务必理解)
|
||||
### 6.1 方案 C 的机制与三条硬约束(务必理解,否则链接期/类型期炸)
|
||||
|
||||
带类型的库 crate(如 `sspf`,消费方要 `use sspf::Platform`)**Cargo 原生不支持当依赖消费
|
||||
预编译 rlib**,且 `use sspf::*` 需要接口元数据(`.rmeta`)。⇒ 「消费方完全不编译平台库」在
|
||||
Rust 现状下**做不到**。
|
||||
**机制**:Cargo 原生不支持把预编译 rlib 当依赖,但消费方**可以不把 sspf 声明为 cargo 依赖**,
|
||||
改用 `.cargo/config.toml` 的 `rustflags` 直接把 rlib 喂给 rustc:
|
||||
|
||||
本包的形态是:**「预编译的 `sspf-admin` 二进制(字面)+ 平台 crate 的自包含源码 + `Cargo.lock`」**。
|
||||
消费方依赖包内**源码路径**——平台库仍会编译一次(Rust 库常态),但**不再碰 git、不再 clone
|
||||
monorepo、不再重编 20+ crate**。预编译二进制留给「直接跑平台」运行态模式。
|
||||
```toml
|
||||
[build]
|
||||
rustflags = [
|
||||
"--extern", "sspf=…/lib/libsspf-<hash>.rlib",
|
||||
"--extern", "axum=…/lib/libaxum-<hash>.rlib", # 见约束 ③
|
||||
"-L", "dependency=…/lib",
|
||||
]
|
||||
```
|
||||
|
||||
**三条硬约束**(全部实测踩过):
|
||||
|
||||
1. **编译器版本必须一致**:rlib 的 ABI 取决于产出它的 rustc。全仓锁 `rustc 1.95.0`
|
||||
(包内 `rust-toolchain.toml`)。消费方必须同版本,否则链接失败。
|
||||
2. **`lib/` 必须是构建产物 `deps/` 的完整副本**:不只是 `.rlib`,还必须含
|
||||
`.rmeta`(类型元数据)和 **proc-macro 的 `.dylib`**(`serde_derive`/`tokio_macros`/…,
|
||||
编译期展开宏要用)+ 原生 `.a`(pglite 等)。少一样就 `E0463 can't find crate for sspf`。
|
||||
平台 `release.sh` 已按整目录拷贝(422 个文件)。
|
||||
3. **公共 API 涉及的外部 crate 必须与消费方同源**:sspf 的签名里带 `axum::Json` /
|
||||
`http::HeaderMap` / `bytes::Bytes` 等类型。若消费方自己再编一份 axum,就是「同名 crate
|
||||
的两个实例」(同 version、不同 hash)→ 跨 sspf 边界传参必报 `E0308 mismatched types`
|
||||
(`multiple different versions of crate 'axum'`)。⇒ 消费方对 **sspf + axum + tokio +
|
||||
serde + serde_json + http + bytes** 全部走 `--extern` 取 `lib/` 里那一份,**不要在
|
||||
Cargo.toml 声明这些依赖**。
|
||||
|
||||
**两个平台侧实现细节**(消费方不用管,但遇到报错要知道根因):
|
||||
- `lib/` 的 rlib 是 **bitcode-free** 的(出包时 `--config profile.release.lto=false
|
||||
--config profile.release.embed-bitcode=false`)。因为 macOS 的 `ld`(libLTO 21)解析不了
|
||||
rustc 1.95 产出的 LLVM22 bitcode,带 bitcode 会 `could not parse bitcode object file`。
|
||||
- 因此消费方 **release profile 必须 `lto = false`**(见 §6.4),否则 LTO 找不到 `__bitcode`
|
||||
段报 `failed to get bitcode from object file for LTO`。
|
||||
|
||||
### 6.2 平台仓出包
|
||||
|
||||
@@ -249,38 +278,58 @@ bash scripts/release.sh 0.5.1 # 或显式指定版本(覆盖 crates/sspf
|
||||
| 路径 | 用途 |
|
||||
|---|---|
|
||||
| `bin/sspf-admin` | 🔴 预编译二进制(字面,平台侧已 release 编译),可直接跑 |
|
||||
| `crates/*` | 🔴 平台 crate 自包含源码(sspf 门面 + 其 path 依赖闭包,共 17 个) |
|
||||
| `src/backend/` | 🔴 内核 lib(`ssw-platform`)—— sspf 的 path 依赖 |
|
||||
| `Cargo.toml` | 🔴 workspace 根(`version.workspace = true` 继承靠它) |
|
||||
| `Cargo.lock` | 🔴 锁定整个闭包,消费方 `--offline` 也能编译 |
|
||||
| `rust-toolchain.toml` | 工具链版本(信息性;消费方需自带同名文件) |
|
||||
| `lib/` | 🔴 **预编译产物完整闭包**(方案 C 核心):sspf 内部 crate + 16 个 registry 依赖 + 全部传递依赖,逐字节等同构建产物 `deps/`(`.rlib`+`.rmeta`+proc-macro `.dylib`+原生 `.a`,共 422 个)。**bitcode-free**,ABI 锁 rustc 1.95.0。消费方靠 `--extern` + `-L dependency` 直链,零重编 |
|
||||
| `crates/*` | 平台 crate 自包含源码(sspf 门面 + 其 path 依赖闭包,共 17 个;dev 回退用) |
|
||||
| `src/backend/` | 内核 lib(`ssw-platform`)—— sspf 的 path 依赖(dev 回退用) |
|
||||
| `Cargo.toml` | workspace 根(`version.workspace = true` 继承靠它;dev 回退用) |
|
||||
| `Cargo.lock` | 锁定整个闭包,消费方 `--offline` 也能编译(dev 回退用) |
|
||||
| `rust-toolchain.toml` | 🔴 工具链版本(1.95.0;消费方**必须**复制到仓库根) |
|
||||
| `docs/SSPF-PLATFORM-PACKAGE.md` | 本文件 |
|
||||
| `README.md` | 包自述与消费步骤 |
|
||||
| `frontend/` | 平台前端源码(不含 node_modules/dist,可选随包) |
|
||||
|
||||
脚本最后会**自检验证**:构造最小消费方,`cargo build --offline` 确认包内 path 依赖闭包
|
||||
可被离线编译通过,再落盘 tar.gz。
|
||||
脚本落盘前跑**两个自检**:
|
||||
- **自检 A(dev 回退可用性)**:构造最小消费方,`cargo build --offline`,确认包内 path 依赖源码闭包能离线编译。
|
||||
- **自检 B(方案 C 零重编)**:构造只声明自身直依赖、用 `--extern sspf` + `-L dependency=lib`
|
||||
的最小消费方,`cargo build` 确认**平台闭包不重编、直接链接预编译 rlib**。
|
||||
|
||||
### 6.3 消费方怎么接
|
||||
### 6.3 消费方怎么接(方案 C,推荐路径)
|
||||
|
||||
1. 把 `dist/sspf-vX.Y.Z.tar.gz` 解包到消费方仓库的 `vendor/sspf-vX.Y.Z/`。
|
||||
(技能仓:`bash scripts/fetch-platform.sh vX.Y.Z` 自动下载/解包。)
|
||||
2. `Cargo.toml`(建议放 `[workspace.dependencies]`,成员一律 `sspf = { workspace = true }`):
|
||||
1. 把 `dist/sspf-vX.Y.Z.tar.gz` 解包到 `vendor/sspf-vX.Y.Z/`。
|
||||
(技能仓:`bash scripts/fetch-platform.sh vX.Y.Z` 自动解包 + 生成 config。)
|
||||
2. **复制工具链锁**:`cp vendor/sspf-vX.Y.Z/rust-toolchain.toml ./`(确保 rustc 1.95.0)。
|
||||
3. **生成 `.cargo/config.toml`**(含本机绝对路径,**不要提交**,加进 `.gitignore`):
|
||||
|
||||
```toml
|
||||
# 升版本 = 改这一行(路径 + version 一起改),不许在任何成员里写第二份
|
||||
sspf = { path = "vendor/sspf-vX.Y.Z/crates/sspf", version = "0.5" }
|
||||
[build]
|
||||
rustflags = [
|
||||
"--extern", "sspf=vendor/sspf-vX.Y.Z/lib/libsspf-<hash>.rlib",
|
||||
"--extern", "axum=vendor/sspf-vX.Y.Z/lib/libaxum-<hash>.rlib",
|
||||
"--extern", "tokio=vendor/sspf-vX.Y.Z/lib/libtokio-<hash>.rlib",
|
||||
"--extern", "serde=vendor/sspf-vX.Y.Z/lib/libserde-<hash>.rlib",
|
||||
"--extern", "serde_json=vendor/sspf-vX.Y.Z/lib/libserde_json-<hash>.rlib",
|
||||
"--extern", "http=vendor/sspf-vX.Y.Z/lib/libhttp-<hash>.rlib",
|
||||
"--extern", "bytes=vendor/sspf-vX.Y.Z/lib/libbytes-<hash>.rlib",
|
||||
"-L", "dependency=vendor/sspf-vX.Y.Z/lib",
|
||||
]
|
||||
```
|
||||
|
||||
3. `.gitignore` 加 `vendor/`。
|
||||
4. `cargo build` 即可(`--offline` 也行,包自带 `Cargo.lock`)。
|
||||
`<hash>` 每版本会变(用 `ls lib/libsspf-*.rlib` 取实际名)。`fetch-platform.sh` 已自动生成。
|
||||
4. **`Cargo.toml` 不要声明** `sspf` / `axum` / `tokio` / `serde` / `serde_json`(全部来自 `lib/`,
|
||||
见 §6.1 约束 ③)。只声明自己仓库的 path 依赖;若确实需要 sspf 闭包里没有的第三方 crate,
|
||||
才正常声明并编译它(它不会跨 sspf 边界,无实例冲突)。
|
||||
5. `.gitignore` 加 `vendor/` 与 `.cargo/config.toml`。
|
||||
6. release profile 设 **`lto = false`**(见 §6.4)。
|
||||
7. `cargo build` —— 平台闭包与 axum/tokio 全部**不编译**,直接链接 `lib/` 预编译 rlib。
|
||||
|
||||
### 6.4 业务仓侧必须同步配合的 4 件事(仍适用)
|
||||
|
||||
1. 补 `rust-toolchain.toml` 锁 `1.95.0`(rustup 按 cwd 选版本,平台侧代劳不了)。
|
||||
2. **删掉 `[profile.release] panic = "abort"`**:单进程链接后 release profile 由业务仓根决定,
|
||||
`abort` 会让 `catch_unwind` 抓不到 panic ⇒ 契约 §6.5 破、进程直接死。同时照抄本仓 release 设置
|
||||
(`opt-level=2` / `lto="thin"` / `strip="symbols"` / `codegen-units=16`,**不设** `panic`)。
|
||||
`abort` 会让 `catch_unwind` 抓不到 panic ⇒ 契约 §6.5 破、进程直接死。
|
||||
其余照抄本仓 release 设置(`opt-level=2` / `strip="symbols"` / `codegen-units=16`,**不设** `panic`),
|
||||
但 **`lto` 必须 `false`**(不是 `"thin"`):平台预编译 rlib 是 bitcode-free 的,
|
||||
开 LTO 会因找不到 `__bitcode` 段直接失败(§6.1)。平台 rlib 已 opt-level=2,损失很小。
|
||||
3. 补 `[profile.dev] incremental = false`(本地已有未提交改动,勿覆盖)。
|
||||
4. 冻结对外契约基线:132 条端点(`docs/contract.md`)、12 个测试二进制、五把尺子
|
||||
(`smoke.sh` / `check-boundary.sh` / `check-contract.sh` / `check-entity.sh` / `check-upstream-tests.sh`),
|
||||
|
||||
Reference in new issue
Block a user