在Linux上从零编译iOS内核:HackiOS的XNU构建工具链完整教程(theos + clang + iig stub)
在Linux上从零编译iOS内核:HackiOS的XNU构建工具链完整教程(theos + clang + iig stub)
HackiOS(hackios-xnu-kernel)把苹果开源的 XNU 内核(xnu-8796.121.2,即 iOS 16.5 的内核)跑在 Android 手机硬件和 QEMU 上,并运行未经修改的 iOS 16.5 用户空间。本教程带你从零在 Linux 上编译出这个 iOS 内核:全程使用 stock clang + theos 工具链 + 自制 iig 桩代码,不需要 macOS、不需要 Xcode,约 45 秒完成一次完整链接。
🧩 先搞懂:为什么 iOS 内核能在 Linux 上编译
XNU 本身是 APSL 2.0 开源的,理论上"缺什么补什么"就能编。HackiOS 的构建工具链恰好只解决三个缺口:
| 缺口 | Linux 上的替代方案 | 所在位置 |
|---|---|---|
| 苹果私有链接器 ld64 / nm / otool | theos 的 Linux 交叉工具链(toolchain/linux/iphone/bin) |
~/theos(外部安装) |
| iPhone SDK 头文件 | theos 的 iPhoneOS16.5.sdk + 自制 SDK overlay |
xnu-deps/setup.sh |
闭源的 iig(DriverKit 接口生成器) |
iig 桩代码:由链接器未定义符号表自动生成 | xnu-deps/gen-iig-stubs.py |
另外两个"胶水"脚本控制一切:
- xnu-env.sh:导出
THEOS、XNU_SRC、XNU_SDK_PATH等全部路径变量,所有构建脚本都 source 它; - xnu-build.sh:真正调起
make,固定ARCH_CONFIGS=ARM64、MACHINE_CONFIGS=BCM2837(以 BCM2837 配置为基座)、KERNEL_CONFIGS=DEVELOPMENT。
📦 步骤一:安装构建依赖(clang + lld + theos)
系统包(Arch):
sudo pacman -S --needed base-devel git curl clang lld python perl xz
Debian/Ubuntu 对应 build-essential git curl clang lld python3 perl xz-utils,另需 flex bison m4 autoconf automake。
theos:按官方文档装到 ~/theos(或设置 $THEOS 指向它)。它提供两样东西,缺一不可:
toolchain/linux/iphone/bin:ld64 链接器、nm、otool、strip 等 Mach-O 工具;sdks/iPhoneOS16.5.sdk:内核编译所对标的 SDK。
⚠️ 仓库路径不能含空格——XNU 的 makefile 承受不住,这是官方明确点名的坑(见 xnu/README.md)。
🌱 步骤二:拉取 XNU 源码并打补丁(xnu/apply.sh)
xnu/apply.sh # ~6 s
这一步只做三件事(见 xnu/apply.sh):
- 浅克隆 Apple 官方 XNU 仓库的
xnu-8796.121.2标签(不带历史,只取一个 commit); - 检出到
xnu-src/xnu-8796.121.2,建redwood分支; - 应用 xnu/redwood.patch(改动苹果文件)+ 拷入 xnu/files/(新增的驱动、文件系统、minicrypto 等)。
完成后是一个"改动未提交"的普通 git 树——这正是后续 xnu/export.sh 导出回补丁的约定格式。
🔧 步骤三:准备构建依赖(xnu-deps/setup.sh)
xnu-deps/setup.sh # ~30 s(两阶段自动串联)
xnu-deps/setup.sh 分两个阶段,所有产物都落在 xnu-deps/ 下(不入库):
Stage 1 —— 源码与宿主工具
- 抓取 Apple 开源组件在 iOS 16.5 对应版本:
libdispatch、libpthread、AvailabilityVersions; - 构建
mig(Apple 原版编不过 glibc,用的是能编的移植版)、tcsh(XNU 的doconf是 csh 脚本)、unifdef; - 从 macOS 13.3 SDK 中只解压 Kernel.framework 的 DriverKit 头文件——这正是闭源
iig本应生成头文件的替代来源; - 组装 SDK:软链接 theos 的
iPhoneOS16.5.sdk,再叠加usr/local(公开 SDK 缺失的私有头文件,如 firehose)。
Stage 2 —— 两个静态库(需要内核树先存在)
libfirehose_kernel.a:libdispatch 的 firehose 日志缓冲,直接对内核导出的头文件编译;libpthread_kext.a:pthread 内核扩展。
改了内核头文件后,用 xnu-deps/setup.sh --rebuild-libs 重编这两个库。
🚀 步骤四:一条命令编出内核(xnu-build.sh -j8 -k)
tools/mk-ath11k.sh # 可选:手机 Wi-Fi 驱动 ath11k(首次)
./xnu-build.sh -j8 -k
约 45 秒(12 线程实测),产物是:
xnu-src/xnu-8796.121.2/BUILD/obj/DEVELOPMENT_ARM64_BCM2837/mach.development.bcm2837
编译时的"假报错"要心里有数:
-k参数必须带。构建会"失败"退出(make 返回 2),但报错全部发生在内核链接完成之后:check_all_exports导出检查和 3 个 symbolsets 校验,共 217 条exported name not in import list——全是 iig 桩引入的 DriverKit RPC 名字。看产物文件的时间戳,别看 make 的退出码。- 编译用的
xnu-deps/host/bin/xnu-clang只是调/usr/bin/clang的薄封装,官方在 clang 22.1 上验证过。
iig 桩:整个工具链最妙的部分
苹果的 iig(DriverKit 接口生成器)闭源,正常会为 <Class>.iig.cpp 生成用户态驱动 RPC 编组代码,没有它内核链接不过。HackiOS 的做法(xnu-deps/gen-iig-stubs.py):
- 读链接器输出的未定义符号表 xnu-deps/iig-impl/undefined-all.txt;
- 自动生成 xnu-deps/iig-impl/OSObject.iig.cpp:对纯 DriverKit 接口类定义元类,其余生成方法一律返回
kIOReturnUnsupported。
代价只是"用户态 DriverKit 驱动不可用",而 HackiOS 根本不用它——显示、表面、密钥存储都有自制替代(MiniIOMobileFramebuffer 等)。若未定义符号集变化,重新生成即可:
xnu-deps/gen-iig-stubs.py xnu-deps/iig-impl/undefined-all.txt xnu-deps/iig-impl qemu/kernel.syms
rm -rf BUILD # 必须清构建缓存
✅ 验证产物 & 让它跑起来
- 官方验证过:在只有一个空仓库的目录里按上述命令执行,得到的内核大小和符号集与可用内核完全一致,占盘约 600 MB(不含 theos)。
- 重编之后想更新仓库里的预编译内核:
tools/update-prebuilt.sh(预编译版在 prebuilt/mach.development.bcm2837)。 - 日常使用其实不用手动指路径:
./xl run(真机)和 qemu/run-ios.sh(QEMU)会自动优先取新编译的内核,取不到才回落到prebuilt/。
📋 排错速查表
| 症状 | 原因 / 解决 |
|---|---|
make 返回 2、满屏 exported name not in import list |
正常,产物已生成,看文件时间戳 |
找不到 ld / cctools 报错 |
theos 没装到 ~/theos,或设 THEOS 指向正确位置 |
| 路径含空格导致 makefile 崩溃 | 换目录,路径去掉空格 |
stage 2 提示缺内核树 |
先跑 xnu/apply.sh 再重新执行 setup |
| 改了内核头文件后库不一致 | xnu-deps/setup.sh --rebuild-libs |
| iig 桩不匹配新符号 | 重新跑 gen-iig-stubs.py 并 rm -rf BUILD |
更多细节(补丁结构、export.sh 的"回滚陷阱"、内核新增文件清单)见 xnu/README.md;想移植到别的设备,从 common/new-device.sh 和 docs/PORTING.md 入手。

