chore(memory): 记 armv7 交叉编译链与三个坑

This commit is contained in:
admin committed 2026-11-12 20:19:54 +08:00
1 parent 39201143c5
commit 7da10f71f5
1 file changed
+60
+60
View File
@@ -0,0 +1,60 @@
# 2026-11-12
## armv7(32 位 ARM hard-float)交叉编译与发布 —— 完成
### 背景
平台后端把 PostgreSQL 引擎(`libpglite.a`)**静态链进二进制**。上游 `Midwess/pglite-rs`
只发布 aarch64/x86_64 四架构引擎,**没有 armv7** ⇒ `pglite-rs-sys` 的 build.rs 下不到
`pglite-armv7-*.tar.gz` 会 404 ⇒ 必须自建引擎。
### 路线选择
| 路线 | 结论 |
|---|---|
| A. `docker run --platform linux/arm/v7` 原生编译 | ❌ qemu 模拟,apt 装依赖 9 分钟未完,PG 全量 make 要数小时 |
| B. amd64 容器 + `gcc-arm-linux-gnueabihf` 交叉工具链 | ✅ **采用** |
Rust 侧用 **zig cc** 当 linker(zig 0.14.1 自带 lld + armv7 libc,免装交叉 libc)。
### 三个坑(根因都在离报错很远的地方)
1. **`strip="symbols"` 破坏静态库全局符号**:仓库根 `[profile.release]` 的 strip 让 rustc 在链接前
**重建** native 静态库(落 `deps/rustcXXXX/libpglite.a`),把 `ProcessStartupPacket` 从 `T` 降级为 `t`、
`pgl_shmem_reset` 直接消失 ⇒ 链接期 undefined symbol。量化:重建归档比原件小 **3228 字节**
(4 个 ARM 符号 × 24 字节)。规避:`CARGO_PROFILE_RELEASE_STRIP=none`。
2. **PG configure 交叉时跳过 `--export-dynamic` 探测**:`cross_compiling=yes` 时直接假定不支持
⇒ `postgres` 动态导出 **0** 符号(官方 10802)⇒ 扩展模块 `dlopen` 报 `undefined symbol: CurrentMemoryContext`。
规避:cache 变量**必须带 `pg` 前缀**(`pgac_cv_prog_cc_LDFLAGS_EX_BE__Wl___export_dynamic=yes`,
用 `ac_cv_...` 无效)+ make 直传 `LDFLAGS_EX_BE="-Wl,--export-dynamic"`。
3. **runtime tar 缺 libpq + 缺 RPATH**:上游把「造引擎」(`build-libpglite.sh`)与
「runtime 可移植化」(`relocate-runtime.sh`:RPATH + 打包 libpq + libz)**拆成两个脚本**。
交叉脚本只做前者 ⇒ `initdb: error while loading shared libraries: libpq.so.5`。
规避:新增 `scripts/relocate-runtime-cross.sh`。
另:上游 tarball 无 `.git` ⇒ **`git apply` 静默失效**,必须用 `patch -p1`。
### 产物与验证
- `dist/pglite-engine-armv7/`:`libpglite.a` 11M + `pglite-runtime.tar` 13M + `pglite_native.h` + `sysroot/`(armhf libc + zlib)
- `target/armv7-unknown-linux-gnueabihf/release/sspf-admin`(ARM EABI5,~70 MB)
- `dist/sspf-v0.5.0-armv7-unknown-linux-gnueabihf.tar.gz`(160M)
- `dist/pglite-armv7-unknown-linux-gnueabihf.tar.gz`(10M,命名对齐上游)+ `.sha256`
arm/v7 容器内实测全通过:initdb Success、单用户模式退出码 0、pglite 读写探针、
sspf-admin 启动 + 14255 条示例数据(1709 文件)、`/api/oauth/Login` 返回 token、
`/api/oauth/CurrentUser` 返回 99 菜单节点 + 6 路由。**从发布包 tar 解出的二进制端到端复测同样通过。**
### 🔴 关键认知
- **runtime 是内嵌进二进制的**:`pglite-rs` 用 `include_bytes!(OUT_DIR/pglite-runtime.tar)`
⇒ 发布包**自包含**,目标机不需要额外引擎文件。
- **`postmaster.pid` 残留导致的 `boot failed: backend main returned 1, expected 99` 不是 armv7 缺陷**:
是 kill -9 留下的状态,x86_64 同样。排查先 `rm -f <datadir>/postmaster.pid`。
- 复用已有数据目录启动**正常**(WAL `automatic recovery in progress` 后起服务)。
### 发布
Gitea Release `v0.5.0`(id=81)追加三个 asset:
`sspf-v0.5.0-armv7-unknown-linux-gnueabihf.tar.gz`、`pglite-armv7-unknown-linux-gnueabihf.tar.gz`、
`pglite-armv7-unknown-linux-gnueabihf.tar.gz.sha256`。两个包均已**流式下载回验 sha256 一致**。
### 脚本(本次新增/改动)
`scripts/build-pglite-engine.sh`(编排)、`build-libpglite-cross.sh`、`relocate-runtime-cross.sh`、
`zig-cc-armv7.sh`(改写 `-Wl,/abs/path` + 注入 sysroot)、`build-armv7.sh`(一键入口)、
`release.sh`(新增 `--target`;**解包目录名带 target 后缀**,同版本多平台互不覆盖)。
文档:`docs/armv7-build.md`。