本文说明本地源码适配、构建、打包和验证流程。除非另有说明,所有命令均在 zig-patch 仓库根目录执行。
zig-bootstrap 子模块固定在官方 0.17.0 正式发布标签、0.17.x 分支的
以下提交:
b12ab1fbafc3a290d6a13c42b14e1c67dd826c0f
官方发布日期为 2026-10-01。官方版本索引
提供 bootstrap 归档及校验和;应用补丁后,
zig-bootstrap/ohos/manifest.json 中也记录了这些固定信息。
| 路径 | 用途 |
|---|---|
patch/zig-ohos-0.17.x.patch 及 .sha256 |
完整 OHOS 补丁及校验和 |
scripts/ |
仓库入口脚本和本地发布附件整理 |
zig-bootstrap/ohos/manifest.json |
版本、源码 revision、target/CPU 矩阵、QEMU 镜像校验和 |
zig-bootstrap/ohos/source-paths.txt |
导出补丁的源码范围 |
zig-bootstrap/scripts/ohos/ |
构建、维护与验证脚本实现 |
zig-bootstrap/zig/lib/libc/ohos/ |
OHOS libc overlay 和 OpenLibm binary128 源码 |
zig-bootstrap/zig/test/ohos/ |
运行库与编译器 smoke 测试 |
zig-bootstrap/out/、zig-bootstrap/dist/、dist/ |
生成的构建目录、归档和报告 |
子模块中的 OHOS 专用路径由补丁创建,执行 scripts/apply-ohos-patch.sh
后才可访问。应用补丁后的 ohos/README.md 也说明了内部脚本,其示例以
子模块根目录为工作目录。
本地需要 Git、C/C++ 编译器、CMake、Ninja、jq、ripgrep、xz 和 Python 3, 使用类 Unix 构建环境。完整补丁包含 OHOS libc、头文件、OpenLibm 源码及 构建脚本,常规构建无需已有构建目录或外部 OHOS SDK 安装。重新生成 overlay 时才需要对应的 SDK 和 musl 源码。
git clone --branch 0.17.0 --recurse-submodules https://github.com/openharmony-zig/zig-patch.git
cd zig-patch
scripts/apply-ohos-patch.sh
CMAKE_GENERATOR=Ninja CMAKE_BUILD_PARALLEL_LEVEL=6 scripts/build-matrix.sh示例使用发布后的 0.17.0 标签;准备发布时可改为对应适配分支。
已有 clone 应先切换到需要的分支或标签,再执行
git submodule update --init --recursive,初始化该提交记录的子模块,
再应用补丁。应用脚本检查精确的 bootstrap 基线,并支持重复执行;根目录
的构建和测试入口也会先调用它。
完整矩阵包含四个宿主编译器和三个 OHOS 原生编译器。流程先构建宿主
LLVM/Clang/LLD 和 Zig,再构建目标依赖,最后构建并安装目标 Zig 编译器、
库文件及文档。安装前缀为 zig-bootstrap/out/zig-<target>-<cpu>/,xz 包和
校验文件输出到 zig-bootstrap/dist/。归档顶层目录与包名一致,ARMv7
明确使用 generic+v7a。
可选择分组或 manifest 中的目标名称:
scripts/build-matrix.sh --only host
scripts/build-matrix.sh --only native
scripts/build-matrix.sh --only host --targets arm64-macos,x64-linux-musl
scripts/build-matrix.sh --skip-build
scripts/build-matrix.sh --skip-package--skip-build 检查并打包已有前缀,包含已安装 OHOS 库源码是否过期的检查;
--skip-package 仅构建与检查。一次矩阵调用在首个目标成功后自动为后续
目标复用 zig-bootstrap/out/host。独立调用确认该宿主前缀来自同一源码后,
可设置 ZIG_BOOTSTRAP_SKIP_HOST=1。并行构建必须使用不同 target,不能
共享 out/build-llvm-<target>-<cpu>。
所有 OHOS 脚本默认将宿主临时文件放在 zig-bootstrap/out/tmp,可通过
OHOS_TMPDIR 改到其他磁盘。
python3 scripts/prepare-release.py脚本读取 zig-bootstrap/dist/ 的归档,核对 bootstrap 基线、归档校验和、
编译器是否存在、完整 manifest 及构建元数据,随后生成与 0.16.0 一致的
18 个附件:
- 七个
.tar.xz包及七个.tar.xz.sha256文件。 - 四个宿主
.tar.gz包,其解压后的 tar 数据与对应 xz 包完全一致。
上传附件目录为 dist/releases/0.17.0/assets/。旁边的 SHA256SUMS 和
release-assets.json 记录全部 18 个文件。GitHub 自动生成的两种源码
归档由发布标签提供。
使用本次已验证并保留的版本化归档时执行:
python3 scripts/prepare-release.py --source-dir zig-bootstrap/dist/0.17.0脚本还支持 --only、--targets 和 --output-dir;选择不同目标集合时,
请使用独立输出目录。构建产物与验证记录均为本地生成文件,全新 clone
不会包含它们。
修改 zig-bootstrap 中的适配源码后导出补丁:
scripts/refresh-patch.sh脚本使用临时 Git index 导出 zig-bootstrap/ohos/source-paths.txt 声明的
范围,同步更新补丁 SHA-256,不会改动子模块的真实暂存区。子模块保持在
官方基线提交,已应用的源码改动由导出补丁携带。
使用新构建的宿主编译器检查源码结构、Shell 语法、Zig 格式和三个目标探针:
zig-bootstrap/scripts/ohos/check-source.sh \
--zig zig-bootstrap/out/zig-aarch64-macos-none-baseline/zig升级 Zig 基线时,先对照目标 release 审查适配,再更新子模块 gitlink、
.gitmodules、应用与导出脚本中的基线常量、manifest 及源码检查,随后
重新导出补丁并在全新 checkout 上验证。当前补丁仅保证适用于固定基线。
0.17.0 适配包含 cc_dir API 迁移、PIE 策略入口整合、OHOS DNS 查询表
类型和 ARMv7 fortify 兼容修复、binary128 long double ABI 支持,以及
LLVM 隐藏 sret 参数计数修复。升级编译器时应保留相应 C/Zig ABI 回归测试。
OHOS 原生编译器通过 PATH 中的系统 binary-sign-tool 为 OHOS 目标的最终 ELF
可执行文件(包括 PIE)和共享库自签名。签名在链接器完成并关闭可写输出
之后、whole-cache manifest 提交之前执行;签名失败不会记录成功缓存。
缓存键区分 OHOS 原生构建与未签名的交叉构建,成功命中缓存时复用已签名
ELF。对象文件和静态库不签名。错误诊断包含工具退出状态及其输出,成功时
不显示工具日志。签名后恢复原文件权限,兼容工具替换输出文件的情况。
命令遵循 OpenHarmony 二进制签名工具接口。
原生目标检测保留 ohos/ohoseabi ABI,避免相同的动态链接器名称导致误识别
为 musl。显式指定的 GNU、musl、Android 目标保持不变,不触发签名。QEMU
回归覆盖默认/显式 OHOS 目标签名及其他平台 ELF 交叉产物不签名。
zig cc -nostdlib 显式关闭 libc 链接,避免 OHOS ABI 的默认 libc 要求
使无运行库链接仍隐式构建 libc。
无需设备或签名密钥即可运行签名策略及进程调用回归:
python3 zig-bootstrap/scripts/ohos/test-signing.py \
--zig zig-bootstrap/out/zig-aarch64-macos-none-baseline/zigOHOS libc 是相对 Zig musl 的 overlay,OHOS 头文件由固定 SDK 生成。
先准备 zig-bootstrap/ohos/manifest.json 记录的 musl revision 和 SDK
版本,再生成并比较,不修改已签入的 overlay:
zig-bootstrap/scripts/ohos/update-libc.sh \
--zig zig-bootstrap/out/zig-aarch64-macos-none-baseline/zig \
--musl-source /path/to/third_party_musl \
--sdk-native /path/to/ohos-sdk/native存在差异时命令返回非零,差异保存在
zig-bootstrap/out/ohos-maintenance/diff/。审查后重复命令并加 --apply
同步源码,此时需要 rsync。按需更新生成器 fixup 和编译器 glue,执行
源码与三架构运行检查,再刷新补丁;升级上游依赖时同步更新 manifest。
musl 许可文本位于 zig-bootstrap/zig/lib/libc/musl/COPYRIGHT。
OHOS x86_64 的 long double 为 IEEE binary128。OpenLibm v0.8.7 子树
替换不兼容的 x87 long-double 源码,由
zig-bootstrap/zig/src/libs/ohos.zig 显式选入。精确 revision 和兼容补丁
记录在 manifest 中。
git clone https://github.com/JuliaMath/openlibm.git /path/to/openlibm
git -C /path/to/openlibm switch --detach 9fbeafcd4f1b6ef6aa3946c1c8faead50f38a94d
zig-bootstrap/scripts/ohos/update-openlibm.sh --source /path/to/openlibm先审查 zig-bootstrap/out/ohos-openlibm-maintenance/diff/,再加
--apply。x86_64 QEMU 测试会实际执行 powl、expl、logl、sqrtl,
并要求出现 C_OHOS_F128_OK 标记。
准备 harmony-contrib/ohos-qemu 的三个镜像归档,以及 QEMU 和 HDC。镜像 revision 和 SHA-256 必须与 manifest 中的固定值一致。脚本校验归档后,依次启动完整 OpenHarmony standard-system 客体。
验证四个宿主编译器:
scripts/test-host-matrix.sh \
--packages /path/to/ohos-qemu/packages \
--hdc-endpoint 127.0.0.1:5556矩阵使用每个宿主编译器生成三个 OHOS 架构的程序,并在对应客体运行。
覆盖静态、static-PIE、动态程序、共享库/dlopen、malloc 扩展、文件、
mmap、线程、TLS、原子操作、网络/DNS、时间、locale、数学库,以及
zig cc、zig c++、zig ar 和 zig ranlib。
macOS ARM64 编译器在本机原生执行。Linux 编译器在容器内执行;ARM64
宿主上的静态 musl 编译器使用 ARM64 容器内的 qemu-x86_64,限制为两个
Zig job。Windows 编译器通过 x86_64 Linux 环境中的 WineHQ 11 执行;
ARM64 macOS 使用完整 x86_64 Ubuntu QEMU VM。宿主容器验证需要 Docker,
定义位于 zig-bootstrap/ohos/Dockerfile.host-test 和
Dockerfile.host-test-arm64。
可用 --targets x64-windows-gnu 单独验证宿主;--compile-only 只做编译
和 ELF 检查,--skip-compile 核对并复用已有产物重跑 QEMU,后两项不能
同时使用。VM 状态及 SSH key 默认保存在
zig-bootstrap/out/ohos-windows-x86-vm/,可用 --windows-vm-dir 和
--windows-vm-port 调整位置和转发的 SSH 端口。
验证三个 OHOS 原生编译器:
scripts/test-qemu.sh \
--zig zig-bootstrap/out/zig-aarch64-macos-none-baseline/zig \
--packages /path/to/ohos-qemu/packages \
--native-zig-root zig-bootstrap/out \
--native-only \
--arch all \
--hdc-endpoint 127.0.0.1:5556每个原生编译器执行 version、env 和客体内 Zig 编译、链接、运行检查,
要求出现 NATIVE_ZIG_OHOS_OK。--native-only 为这些检查单独 clean-boot。
HDC 直接传输编译器及 smoke 所需的精简库 tar,发布归档始终保留完整安装
前缀。原生套件还要求 OHOS_SIGNING_SMOKE_OK:使用隔离的测试签名器检查
最终 ELF 链接、共享库、zig cc、权限恢复、缓存命中和签名失败后的重试。
这些检查验证编译器集成,真实签名应使用系统或 SDK 签名工具验签。
去掉 --native-only 可在同次启动中加入交叉编译的运行库 smoke。
仅检查编译和 ELF 元数据时执行:
scripts/test-qemu.sh \
--zig zig-bootstrap/out/zig-aarch64-macos-none-baseline/zig \
--compile-only独立复现 Windows 编译验证:
zig-bootstrap/scripts/ohos/prepare-runtime-kit.sh \
--zig zig-bootstrap/out/zig-aarch64-macos-none-baseline/zig \
--output zig-bootstrap/out/ohos-runtime-kit
zig-bootstrap/scripts/ohos/test-windows-vm.sh \
--zig zig-bootstrap/out/zig-x86_64-windows-gnu-baseline/zig.exe \
--runtime-kit zig-bootstrap/out/ohos-runtime-kit \
--work-dir zig-bootstrap/out/windows-host-smokecontrol 编译器预建带校验和的 target runtime kit,包含 CRT、libc/libc++、
compiler-rt 和大量使用 std 的 Zig smoke 对象。Windows Zig 编译三架构
C/C++ 和 ARM64 Zig 探针,运行 ar/ranlib 并完成最终 ELF/DSO 链接。
kit 不含最终可执行文件,宿主矩阵会自动准备它。隔离的 Wine runner 设置
ZIG_WINE_FILE_LOCK_WORKAROUND=1,兼容 Wine 尚未完整实现的 NtLockFile。
默认 HDC endpoint 为 127.0.0.1:5555;DevEco Emulator 占用 5555 时,
可选择 127.0.0.1:5556。每架构默认允许两次 clean-boot,每次尝试前
从已校验归档恢复可写镜像。--qemu-attempts 1 关闭重试。
| 环境变量 | 默认值 | 范围或用途 |
|---|---|---|
QEMU_HDC_COMMAND_TIMEOUT |
180 秒 | 普通 HDC 命令,30–600 秒 |
QEMU_NATIVE_HDC_COMMAND_TIMEOUT |
600 秒 | 原生编译器检查,180–1800 秒 |
OHOS_TMPDIR |
zig-bootstrap/out/tmp |
宿主临时目录 |
构建结果位于 zig-bootstrap/out/ohos-matrix/build-results.tsv,宿主矩阵
结果位于 zig-bootstrap/out/ohos-host-matrix-test/host-results.tsv,独立
QEMU 日志位于 zig-bootstrap/out/ohos-qemu-test/。
0.17.0 本地验证完成了:
- 完整补丁在官方基线上干净重放,1,441 个适配文件一致。
- 从全新源码和空 Zig 缓存重建七个平台的编译器、库文件与文档;全部 编译器及每包 20,882 个库文件均与已通过运行验证的产物逐字节一致。
- 七个 xz 包、18 个发布附件的元数据、校验和及 gzip/xz 内容一致性检查。
- 73 项 Target 单元测试、隐藏 sret 回归和两个 OHOS x86_64 long double C ABI 客体测试。
- 四个宿主编译器的三架构产物,以及三个原生编译器的 OHOS QEMU 运行检查。
独立源码重建复用了从同一正式版源码构建的 LLVM 22.1.8 / Clang / LLD / zlib / zstd 依赖,未重复冷构建 LLVM;上文常规全新 checkout 命令会构建 依赖。Windows VM 验证使用预建 runtime kit,未覆盖 Windows 侧完整运行库 冷构建。部分 ARMv7 客体在全部必要成功标记出现后失去响应,未验证长期 稳定性。验证基线为固定 QEMU 镜像和 SDK 6.1.1.125 / API 24,未包含 实体设备测试。
本地记录保存在 zig-bootstrap/dist/0.17.0/ 和 dist/releases/0.17.0/,
包含 validation-report.txt / .json、archive-verification.json、
clean-source-verification.json 及 validation-logs/。这些记录属于生成
文件,不随仓库签入。提交时应排除 out/、dist/、QEMU 镜像、本地 SDK
和 VM key。
本仓库自有新增内容使用与 zig-napi 一致的 MIT。
LICENSE-ZIG 为官方 Zig 许可的原样副本,
zig-bootstrap/zig/LICENSE 和上游源码版权声明均保留原样。
重新生成 overlay 或分发产物时,应保留上游许可文件及各文件的版权声明。
各许可证的适用范围见第三方许可说明。