# XCE 第三方依赖清单

> 建立：2026-10-20（build/de-nix 分支）。背景与决策见 gaps.md "六、构建/分发系统"。
>
> **原则**：系统库优先（apt/发行版包），发行版没有的用 meson wrap subproject 从源码构建；
> 运行期需要自带的库由打包脚本 bundle（`$ORIGIN` RPATH），不引入 /nix/store 或任何
> 内容寻址二进制闭包。glibc/libm/libpthread/pthread 永不 bundle。

## 构建工具链

| 工具 | 最低版本 | 获取 | 备注 |
|---|---|---|---|
| gcc | 13 | 系统包 | `apt install gcc`（glibc 2.39+ 基线） |
| meson | 1.5 | `pip install meson` / `apt install meson`(≥1.3 时 pip 补) | src/meson.build 要求 >=1.5 |
| ninja | 1.11 | `apt install ninja-build` | meson 默认 backend |
| pkg-config | 0.29 | `apt install pkg-config` | |
| go | 1.22 | 上游 tarball / `apt install golang-go` | apiserver/xcecli 已 vendor 全部模块，构建离线 |
| capnp (capnproto) | 1.0.1 | `apt install capnproto`（含 libcapnp-dev） | schema 编译器 + C++ 运行时（pycapnp 链接用） |
| packcc | 2.2 | wrap subproject（Ubuntu 24.04 无包） | 3 个 .peg 解析器（lib/section, rusage, xce_resreq, xce_select） |
| python3 | 3.10 | 系统自带 | xceadmin 构建/测试；no-fork rule 检查脚本 |
| swag | latest | `go install github.com/swaggo/swag/cmd/swag@latest` | 仅 apiserver 文档再生成时需要，非构建必需 |

## C 库依赖

### apt 可直接安装（11 个）

| 依赖 (meson 名) | apt 包 | 版本下限 | 用途 |
|---|---|---|---|
| libuv | libuv1-dev | >=1.44 | 所有 daemon 事件循环 |
| openssl | libssl-dev | >=3.0 | TLS（controller 互联、apiserver）、SHA256 |
| libedit | libedit-dev | >=3.1 | xce_test REPL（BSD 许可，替代 GPL readline） |
| sqlite3 | libsqlite3-dev | >=3.37 | worker 本地状态 |
| hwloc | libhwloc-dev | >=2.8 | worker 拓扑/槽位 |
| libcgroup | libcgroup-dev | >=2.0 | worker cgroup v2 限额 |
| libtirpc | libtirpc-dev | >=1.3 | rpc 头文件 |
| libcyaml | libcyaml-dev | >=1.2 | YAML 配置读取 |
| yaml-0.1 | libyaml-dev | >=0.2.5 | 同上（libcyaml 依赖） |
| zlib | zlib1g-dev | >=1.2.11 | 压缩 |
| threads/math/rt | (libc) | — | 无需安装 |

### apt 没有 → meson wrap subproject（源码随 repo 拉取构建，6 个）

| 依赖 (meson 名) | 上游 | 版本 | 用途 / 备注 |
|---|---|---|---|
| c-capnproto | github:shen390s/c-capnproto（pin e45ff68） | — | Cap'n Proto C runtime（libCapnC_Runtime）+ capnpc-c 代码生成器；32 个源文件 include capnp_c.h |
| librtti | git+ssh gitea rshen/librtti（pin 2149f778） | 0.0.2 | C 运行时类型信息库；上游本身是零依赖 meson 项目；93 个源文件消费 |
| struct2json | xbuild channel 源码 vendor | 1.0.0 | cJSON + s2j 封装（纯静态库）；6 个 meson 消费点 |
| tinylog | xbuild channel 源码 vendor | 1.0.0 | 轻量异步日志（-ltlog + tlog.h）；13 个源文件消费 |
| unity | xbuild channel 源码 vendor（上游 ThrowTheSwitch/Unity） | 2.6.1 | 单元测试框架（libunity.a + unity/unity.h）；仅测试目标链接 |
| packcc | 上游 arithy/packcc | >=2.2 | PEG 解析器生成器；构建工具而非链接库 |

### 特殊：ttyd（预编译二进制，源码待入库）

交互作业启动器（worker TTY/DISPLAY 模式经它拉起会话，`inter_job_utils.c` 按
`/proc/self/exe` 同目录解析）。**不是官方 release**：是 rshen 修改过的 ttyd
（版本串 `1.7.7-eccebc6`，与上游 1.7.7 不同），当前环境里已构建好的那一份也是
这个修改版。现阶段打包脚本直接拾取该预编译静态二进制进 tarball
（`bin/ttyd`）；源码后续提供后入库并转为 meson 目标构建，届时删除本条。
**合规注意**：ttyd 上游是 MIT，但修改版引入的改动未审计，商业分发前需确认
全部改动兼容 MIT 并保留版权声明。

### 特殊：libelogind → libsystemd

worker 的 systemd transient unit 管理（`sd_bus_*`，263 处调用）目前链 nix 的 elogind 255.5。
Ubuntu 24.04 无 elogind 包，但有 **libsystemd-dev 255.4**——sd-bus API 同源兼容。
构建默认 `dependency('libsystemd')`，保留 `-Duse_elogind=true` 选项供非 systemd 平台。
（Step 2 实施时验证；这是本迁移唯一有 ABI 行为风险的替换点，worker 单测兜底。）

### Python（xceadmin）

`src/xceadmin/pyproject.toml` 已声明全部运行依赖：click>=8.0, pycapnp>=1.3, PyYAML>=6.0,
jsonschema>=4.0。构建用普通 venv（**不要** --system-site-packages——那是 nix 环境的产物）：
`python3 -m venv .venv && .venv/bin/pip install .`。pycapnp 的 C 扩展链系统的
capnproto C++ 运行时（apt capnproto/libcapnp-dev 提供版本 1.0.1；pycapnp>=1.3 兼容）。

## 为什么不用 nix store（决策记录）

nix 把依赖闭包做成内容寻址的 /nix/store 路径 + mount namespace，要求闭包出现在**每一台
运行机器**上，且 patchelf 重定位后 ldd/gdb/stack trace 全部变形（t2/t3 master 进程 argv 是
`ld-linux... --library-path /opt/newxce/app/nix/store/...`，人读不懂）。EDA 客户环境没有
/nix/store，这条路在产品定义上不可用。本 repo 依赖只有十来个中小型库，"自包含"的正确形态
是**源码闭包**（wrap subproject）+ 运行期 bundle 清单，不需要二进制 store。此外 nix 的
LD_LIBRARY_PATH 泄漏会导致系统工具崩溃（t2/t3 的 ls/head segfault 实录）。

## 运行期 bundle 规则（打包脚本用）

- **bundle**：libuv、libcapnp/libCapnC_Runtime、librtti、libtlog、libstruct2json、
  libcyaml、libyaml、libtirpc、libedit、libcgroup、libhwloc、libssl/libcrypto（若目标基线 <3.0）
- **永不 bundle**：libc/libm/libpthread/libdl/librt（glibc）、libsystemd（按目标发行版）
- 判定方法：对每个产物 `ldd`，凡路径不在 {/lib, /usr/lib, /lib64} 的（即 wrap 构建产物）
  一律复制进 `lib/`，二进制设 `$ORIGIN/../lib` RPATH。

> **license 合规备忘（2026-10-21，用户提出）**：bundle 清单里 libhwloc 是 BSD-3，
> 但它静态/动态再分发时需保留版权与许可声明（tarball 目前未附第三方 license
> 文本）；libedit 是 BSD（特意选它替代 GPL readline）；libtirpc 历史上是
> BSD/Sun RPC 混合许可。**开发测试阶段沿用现分发策略没问题；商业环境发布前
> 须逐项做 license 审计**（至少：附第三方 LICENSE 汇总文件、确认 hwloc 各传递
> 依赖许可）。记录在案，暂不阻塞当前 rollout。