| name | llvm-subpackaging |
| description | LLVM 全平台分包（sub-packaging）规范 / 设计方案 / SOP。把上游单体 LLVM 工具链 carve 成两个自包含包——`llvm`（slim 自包含工具链 = 编译器 + lld + binutils + libc++ + compiler-rt）与 `llvm-tools`（clang-format/tidy/clangd）——并发布到 xlings-res 双镜像（GitHub gh + GitCode gtc）。用于新增/对齐某平台的 llvm 包、升级版本、保证 linux/macosx/windows 三平台一致。 |
LLVM 分包规范 / SOP（2 包模型）
把上游 1.4–2GB 单体 LLVM 整包 carve 成两个职责单一、自包含的包,让用户按需安装,
不必每次拖整包(还含 1.2GB 用不到的静态库 + lldb + 全部 extra 工具)。
详细清单与命令见:
references/split-manifest.md —— 两个包的二进制/库清单、平台矩阵、自包含事实references/publish-resources.md —— gh / gtc 双镜像发布 SOP、资产命名、sha256 校验
0) 背景事实(决定整套设计)
- 2 包,不是 3 包。 历史上曾拆成
llvm-core + llvm-libcxx + llvm-tools(commit
9db2ba94),但随后 99b004dc 主动把 libc++ 并回 llvm、删掉独立 llvm-libcxx,
让 llvm 成为一个自包含 toolchain。所以当前正确模型是:
llvm(core+libc++ 合并) + llvm-tools。release 上残留的 llvm-core-*/
llvm-libcxx-* 资产是被放弃的旧拆分,不再使用、不要复活。
- 上游没有现成分包。
github.com/llvm/llvm-project 全是单体整包
(mac LLVM-<ver>-macOS-<arch>.tar.xz≈1.45GB;win clang+llvm-<ver>-x86_64-pc-windows-msvc.tar.xz)。
两个包都是 xlings-res 下游 carve 的。
- 目标二进制静态自包含。 clang 驱动(
clang-<major>)、lld、clang-format/tidy/
clangd 都静态链接 LLVM,只依赖系统库;无共享 libLLVM。mac 的 libclang-cpp.dylib/
liblldb.dylib、win 的 libclang.dll/liblldb.dll 只服务 extra/lldb 工具 → 全部丢弃。
- 不做 strip。 LLVM release 二进制无 DWARF
debug_info,strip 只省 ~8–10%,不值得。
1) 包定义(三平台统一)
| 包 | 职责 | 关键内容 |
|---|
llvm | slim 自包含工具链(编译+链接+binutils+C++ 标准库) | bin/: clang-(+clang/clang++/clang-cl/clang-cpp 软链)、lld(+ld.lld/ld64.lld/lld-link/wasm-ld)、llvm-ar/nm/ranlib/strip/objcopy/objdump/readobj/readelf/symbolizer/profdata/cov/link/as/dis/size/rc/config/lib/dlltool/addr2line/...(权威 33 项见 manifest);lib/clang/<major>/include(builtin 头)+lib/clang/<major>/lib(compiler-rt);libc++(linux/mac):include/c++/v1、lib/ 的 libc++/libc++abi/libunwind、share/libc++/v1/std.cppm;libatomic(仅 linux,lib/<triple>/libatomic.so*+.a):libc++ 过度链接它(0 引用的幽灵 NEEDED)且 16 字节原子的 __atomic_* 退化调用需要它——漏带会让每个产物运行期挂 libatomic.so.1: cannot open、真用原子者无法链接,故必须随包。关键:它是 GCC 运行时库,LLVM 不构建它(Release.cmake DEFAULT_RUNTIMES 无 libatomic),上游 LLVM Linux release 也不带(实测 0 文件)——carve 时由 build-llvm-subpkg.sh 从构建机 GCC 取(gcc -print-file-name=libatomic.so.1)放进 lib/<triple>/。windows 无 libc++(用 MSVC STL),mac 无 libatomic(非 GNU 平台)。 |
llvm-tools | 编辑器/开发工具 | bin/: clang-format、clang-tidy、clangd;lib/clang/<major>/include(clangd resource-dir 需要) |
被丢弃(不进任何包):全部 .a 静态库(mac≈1.24GB)、libclang-cpp/liblldb* + lldb 工具、
clang extra 工具(clang-move/refactor/query/check/scan-deps/...)、MLIR、docs。
一致性铁律:三平台同名包职责一致,只允许平台差异化:
- 扩展名
.so(linux)/.dylib(mac)/.dll|.exe(win);库目录 linux/mac 用 lib/<triple>/(mac libc++ 直接在 lib/),win DLL 在 bin/
- 驱动名:win 多
clang-cl/lld-link/llvm-lib
- libc++ 仅 linux/mac;windows
llvm 是 core-only
2) 自包含校验(carve 验收红线)
放进包的每个二进制运行期只允许依赖①系统库②同包随附库。
- macOS:Mach-O
LC_LOAD_DYLIB 读取器(纯 Python,见 build-llvm-subpkg.sh),非
/usr/lib、/System 即不合格 → 中止。
- Linux:
ldd 只能是系统库(不应出现 libLLVM.so)。
- Windows:核心 exe 静态链接;
objdump -p 确认不 import LLVM-C.dll/libclang.dll/
liblldb.dll(实测 clang.exe/lld.exe 都不 import)→ 不打包那些 DLL。
3) Carve 工具
.agents/tools/build-llvm-subpkg.sh(manifest 驱动,从 build-llvm-tools.sh 泛化):
build-llvm-subpkg.sh --in <full.tar.xz|解压dir> --pkg llvm --version 22.1.8 --platform macosx --arch arm64
build-llvm-subpkg.sh --in <dir> --pkg tools --version 22.1.8 --platform windows --arch x86_64
--pkg llvm = core + libcxx(libc++ 缺失时自动跳过,如 windows)+ share/libc++。- 同源整包先解压一次成 dir,再对 dir 多次 carve(避免重复解压);见 stage 里的
carve.sh。
- macOS 自动跑自包含校验;不 strip;按平台默认格式打包(mac=tar.xz;win=tar.xz+zip)。
4) 发布到 xlings-res(双镜像,必须一致)
GLOBAL=github.com/xlings-res/llvm、CN=gitcode.com/xlings-res/llvm,tag=版本号。
- 命名:
<pkg>-<ver>-<platform>-<arch>.<ext>(pkg∈{llvm,llvm-tools};平台 linux-x86_64/
macosx-arm64/windows-x86_64;ext:mac=tar.xz、win=tar.xz+zip、linux=tar.gz+tar.xz)。
- GLOBAL:
gh release upload <tag> <file>... --clobber --repo xlings-res/llvm(支持覆盖)。
- CN:GitCode 不能覆盖;新资产名直接
gtc release upload;若是替换旧同名资产,
由维护者手动在网页删旧资产后我再上传(gtc 不能删)。
- 发布后从 GLOBAL、CN、carve 产物三方 sha256 比对一致;补旧版本时
latest 不倒退。
- 完整命令见
references/publish-resources.md。
5) 接线包索引(.lua 配方)
pkgs/l/llvm.lua:三平台 xpm。linux/win 用 "XLINGS_RES"(资源已就绪);mac 用显式
url={GLOBAL=...,CN=...}(沿用 llvm-tools.lua 的 macosx 写法)。不 pin sha256。
install() 把解压目录 os.mv 到 install_dir(),并按平台生成 clang.cfg/clang++.cfg
(sysroot 注入 + 指向本包内的 libc++ 头/库 —— libc++ 与 clang 同包,故路径自洽,
这正是 99b004dc 合并的理由)。windows 无 libc++ 不生成 libc++ cfg。pkgs/l/llvm-tools.lua:三平台,自包含,config() 注册 clang-format/tidy/clangd。- 版本骨架:
["latest"]={ref=...} + 每版本一条;某平台缺该版本资源(如 linux 22.1.8 待
自建)就不要给该平台加该版本条目 / 不要把 latest 指过去,否则 CI install 测试必挂。
- 隔离合规(
xpkg-creater):禁 os.exec("xvm ...")、禁改 PATH/profile;import 仅 xim.libxpkg.*。
6) 平台落地能力(谁能产哪个)
三平台都从上游全量 release carve,本机即可产出(同一 build-llvm-subpkg.sh 流程):
- macosx-arm64 ←
LLVM-<ver>-macOS-ARM64.tar.xz
- windows-x86_64 ←
clang+llvm-<ver>-x86_64-pc-windows-msvc.tar.xz
- linux-x86_64 ←
LLVM-<ver>-Linux-X64.tar.xz(含 libc++ / share/libc++ / compiler-rt,与 mac 同构;
clang 二进制运行期只依赖系统库,编译期目标由 llvm.lua 的 sysroot 注入 cfg 决定)
上游 Linux 全量约 1.9GB(carve 后 llvm≈150M xz)。早期误以为 linux 需"自建构建",
实测可直接 carve 上游,与 mac/win 完全一致。
7) 验收清单
