MAD Designer iconMAD

静态库:Compressor 构建系统

本页介绍应用链接的第三方 C 库,以及生成它们的 Compressor 构建系统。

撰写于原定日期;当前状态事实已于 2026-11-22 核实。

本文档介绍应用链接的第三方静态库,以及生成它们的构建系统——描述的是实际构建方式, 而非计划。改造前的状态(两代重叠的脚本、已提交的二进制文件、按平台划分的 目录)压缩在文末附录中。

长期约束: 在构建系统完成所有组合的构建、且应用能针对新产物构建并 通过测试之前,Compressor/library 中所有早于本次改造的内容都不会被删除。 清理放在最后,每个提交只处理一项。


1. 系统是什么

一个声明式矩阵、一个驱动器、每个库一份配方、每次构建一份清单。

Compressor/
  matrix.conf                  # the single place version/source/platforms/deps live
  build.sh                     # the driver: ensure (default) / --all / --rebuild /
                               #   --verify / --platforms ios,simulator,macosx
  sqlite3.xcconfig             # the single place SQLite compile options live
  lib/common.sh                # download cache, per-arch compile helpers, lipo,
                               #   xcframework creation, manifest writer, lock
  lib/recipes/<lib>.sh         # one recipe per library (configure/cmake + install)
  lib/verify/<lib>.sh          # optional per-library artifact checks
  patches/                     # local modifications to upstream sources, captured
                               #   as diffs (none current; zint's 2.4.2 patch retired)
  media/<sha256>-<archive>     # content-addressed download cache (gitignored)
  src/  build/                 # extracted sources and build trees (gitignored)
  library/
    <lib>.xcframework/         # the single artifact Xcode links (gitignored)
    <lib>/include/             # the canonical header dir consumers name (gitignored)
    manifests/<lib>.json       # version, source hash, flags, slice SHAs (gitignored)

矩阵(matrix.conf)

面向行,可被 bash 解析:

lib        version  sha256  url   ios-archs  sim-archs  mac-archs  min-ios  min-mac  deps

sha256 是下载归档的哈希——每个库都锁定。deps 命名驱动器会优先构建的其他矩阵行。 库构建的其他一切都不在别处:每库标志位于配方中,并被回显到清单里, 因此“哪些标志构建了它?”仅凭清单就能回答。

驱动器(build.sh)

构建由 build/.ensure.lock.d 上的锁串行化(一种带过期所有者恢复的 mkdir 锁 ——macOS 上没有 flock),因为工作区构建期间多个 Xcode 目标可能 并行运行 ensure 阶段。

下载落在内容寻址的 media/ 缓存中,因此锁定的来源只会下载一次,并在每次使用时 按哈希校验。首次构建需要网络访问;失败信息会说明这一点并指出具体的 tarball。

配方

每份配方把锁定的来源解压到 build/<lib>/source,按架构构建、 按平台 lipo,并调用 finish_library——它创建 xcframework、 安装规范 include 目录并写入清单。每个 xcframework 切片标识符只能对应一个库, 这是 -create-xcframework 的硬性约束,因此多组件库会合并:openssl 把 crypto+ssl 合并为 libopenssl.a, freetds 把 ct+sybdb+tds 合并为 libfreetds.a,mariadb 则是单一 libmariadbclient.a(Connector/C 的 libmariadb 目标在 UNIX 上硬编码为共享库,因此配方构建 mariadbclient 静态目标)。切片由库的 Mach-O 加载命令推断(各平台的 -m*-version-min 标志),这也是为什么不需要 -platform 提示。

改动配方时值得了解的备注:

清单(library/manifests/<lib>.json)

{
  "library": "openssl", "version": "3.5.0",
  "source": { "url": "…", "sha256": "…" },
  "toolchain": { "xcode": "…", "clang": "…" },
  "headers": "ios",
  "flags": "configure: no-shared no-asm no-async; opt: -O3",
  "built": "…",
  "slices": { "ios": { "archs": "…", "sha256": "…" }, … }
}

headers 记录规范 include 目录采用了哪个平台生成的 头文件(freetds 按平台生成 tds_sysdep_public.h;ios 副本是 规范副本,正如旧布局所选)。


2. Xcode 如何消费这些库

每个消费目标都通过文件引用链接一个或多个 xcframework,在其头文件搜索路径中 指定规范的 Compressor/library/<lib>/include,并在其构建阶段最前面运行一个 Ensure Libraries shell 阶段:

set -euo pipefail
"${SRCROOT}/../Compressor/build.sh" --platforms ios,simulator <lib>

当清单是最新时,该阶段在毫秒内空操作,否则只构建缺失的部分; 每个带该阶段的目标都固定了 ENABLE_USER_SCRIPT_SANDBOXING = NO。平台被固定为 ios,simulator,因为目前没有目标为 macOS 构建——矩阵的 macOS 切片已为 UIKit 解耦落地时做好准备(参见 ROADMAP.md Track 2)。

目标 链接 Ensure 阶段
MADSqlite3 sqlite3.xcframework sqlite3
MAD libarchive.xcframework、bzip2.xcframework、zlib.xcframework libarchive
MADMySQL mariadb.xcframework、openssl.xcframework、zlib.xcframework mariadb
MADPostgres postgres.xcframework、openssl.xcframework postgres
MADTds freetds.xcframework、openssl.xcframework freetds
MADTdsClient 没有来自 Compressor 的内容(tds 符号经由 MADTds 提供) —
MADBarcodes libpng.xcframework、zlib.xcframework、zint.xcframework zint
MAD Designer 应用 openssl.xcframework openssl

值得记住的头文件事实:静态库 xcframework 不会可靠地 暴露其头文件,因此每个消费者都显式指定规范 include 目录 (头文件也会打包进 xcframework 以便存档完整)。zint.h、sqlite3.h 和 libpq-fe.h(及其伴随头文件) 是 Public 框架头文件,其文件引用指向规范 include 目录,因为公开的 MAD 头文件导入了 <MADBarcodes/zint.h>, MADSqlite3 导出 sqlite3.h, MADPostgres 导出 libpq-fe.h。

MAD Viewer 目标的遗留 LIBRARY_SEARCH_PATHS 列表和 Scrimpter(在工作区之外) 被刻意保持原样:查看器的链接失败是产品 决策(参见 BUGS.md),而非构建接线问题。


3. 首次运行、日常使用与版本升级

全新检出上的首次运行(或清空 Compressor/library/ 之后):在首次 Xcode 构建之前或 期间,先构建一次这些库:

Compressor/build.sh --all --platforms ios,simulator

下载需要网络访问,首次构建需要 30–90 分钟, 大部分时间花在较大的源码 tarball 上。 之后,Xcode 的 ensure 阶段便是空操作,正常构建得以继续。

校验产物:

Compressor/build.sh --verify --all --platforms ios,simulator

升级某个库: 编辑其 matrix.conf 行(版本、URL、新归档的 sha256), 然后 Compressor/build.sh --rebuild <lib>,并运行消费框架的测试 套件以及 --verify。每个提交只处理一个库。若新版本增加了 cmake 运行探查, mariadb 预设会显式失败并指出它——要明确回答,绝不要猜测。

zint/freetds/mariadb/postgres 配方带有按版本的知识(补丁、 已安装头文件的编辑、探查答案、插件类型名、安装布局、 仅客户端子树列表)。版本升级时,这些就是需要重新检查的地方。


4. 校验命令

# slice inventory
for f in Compressor/library/*.xcframework/*/lib*.a; do lipo -archs "$f"; done

# version strings (each library embeds its matrix version)
strings Compressor/library/openssl.xcframework/*/libopenssl.a | grep -m1 "OpenSSL 3.5.0"

# sqlite correctness, against the BUILT framework (the H7 gate)
nm MADSqlite3.framework/MADSqlite3 | grep -c sqlite3Fts5Init     # present
strings MADSqlite3.framework/MADSqlite3 | grep -x 'DEFAULT_PAGE_SIZE=8192\|DQS=0'

# wiring cleanliness -- expect "" bases plus the MAD Viewer legacy list only
grep -rn 'LIBRARY_SEARCH_PATHS' --include='*.pbxproj' .

# the fresh-clone simulation (proves portability + on-demand building)
git archive HEAD | tar -x -C /tmp/fresh
cd /tmp/fresh
Compressor/build.sh --all --platforms ios,simulator     # bootstrap path (a)
xcodebuild build -workspace Reports.xcworkspace -scheme "MAD Designer" -destination …
Compressor/build.sh --verify --all --platforms ios,simulator
# path (b): wipe library/ xcframeworks and build in Xcode only -- the ensure
# phases rebuild everything

附录:改造前的状态(供参考)

2026-10-04 之前,这些库由两代重叠的工具构建——每库一个 Compressor/build_*.sh 脚本,以及一个 1,293 行的 compressor.sh 驱动器(无法运行:未定义变量导致 set -e 下 404 下载; 其声明的版本已过时多年)——而结果被提交:99 个 .a 文件(约 350 MB)、所有头文件, 以及 9.2 MB 的 sqlite3.c amalgamation 位于 Compressor/library/, 此外 MADBarcodes 内还有 53 个 vendored Zint 源码文件。Xcode 仅通过文件引用和 依赖 SDK 的搜索路径消费它们,这也是 macOS 始终无法接线的原因 (PBXFileReference.path 不依赖 SDK——BUGS.md 中的该条目 已由 xcframework 重新接线关闭)。旧脚本和已提交的目录树 在清理阶段移除,且只在新系统完成所有组合的构建、 应用能构建并针对新产物通过测试之后。

矩阵起步时的基线版本及其目标更新 记录在 TASKS.md §6。

本页为英文原文的简体中文翻译;如有出入,以英文原文为准。