如何编译、签名并运行你的第一个iOS/macOS程序？darwin-vm自定义程序完全教程

darwin-vm 是一个在 Qemu 中运行 iOS/macOS（Darwin 系统）的开源项目。它能在几秒内把虚拟 iPhone 17/16/15/14/13/12 或 M5–M1 的 Mac 直接启动到 root 命令行，让你以 root 身份在虚拟机里编译、签名并运行自己的程序，无需越狱、无需打内核补丁。本教程面向新手，手把手带你完成环境准备，直到你的第一个 iOS/macOS 程序在 darwin-vm 中跑起来。

📖 一、认识 darwin-vm：几秒进入 Darwin 系统的 root 命令行

darwin-vm 的定位是一个轻量、可调试的 Darwin 系统实验台，可以类比"在 Qemu 里用-kernel+-initrd引导 Linux + busybox"，只不过对象换成了 iOS/macOS。

它能做到：

• ⚡ 数秒内从内核启动到 root shell，全程自动完成
• 🛠️ 以 root 身份编译、签名并运行自定义命令行程序
• 🔍 可调试/打补丁内核、SPTM、TXM、dyld、launchd 与用户态程序
• 🧠 支持模拟 A19–A14（iOS）与 M5–M1（macOS）芯片，含 SPTM/MIE 新特性
• 🌐 在 Qemu 能跑的平台上即可运行，不要求 ARM 主机

⚠️ 它不是完整 iPhone/Mac 模拟器：没有屏幕、Wi-Fi、蓝牙、图形界面和 springboard，目标是让你进入 root shell 玩转命令行与 Darwin 底层。

已测试的设备支持一览：

macOS 侧支持 M5 MacBook Air、M4 Mac Mini、M3 MacBook Air、M2/M1 Mac Mini（✅ 均可启动）。

🛠️ 二、编译 iOS/macOS 程序前的环境要求

在 darwin-vm 中编译、签名、运行程序，需要准备：

1. 一台 Mac：下载系统文件、codesign签名、挂载 ramdisk 都必须依赖 macOS 工具链；
2. Xcode：提供xcrun（交叉编译）与codesign（签名）；
3. 一台能编译运行 Qemu 的机器：可以是上面那台 Mac，也可以是另一台机器；
4. 可选：指定要使用的 IPSW（iOS/macOS 恢复镜像）URL，不指定则使用项目内置的默认版本。

安装依赖并克隆仓库：

brew install jq ipsw git clone https://gitcode.com/gh_mirrors/da/darwin-vm cd darwin-vm

🚀 三、一键安装系统文件：下载、打补丁并自动签名

get_files.sh 是整套流程的核心脚本，它会从 IPSW 中自动下载并解包：内核缓存（bootkc）、SPTM、TXM、设备树（dtree）和系统 ramdisk（ramdisk.dmg），然后完成三件关键的事——

1. 注入 launchdaemons/com.jprx.bash.plist 让系统启动后直接拉起 bash root shell；
2. 把预编译的 sysroot/ios_sysroot.tar.gz（bash、coreutils 等工具）解进 ramdisk 并自动签名所有二进制；
3. 用 build_tc.py构建信任缓存（trustcache），让系统允许这些二进制运行。

执行：

./get_files.sh ./fix_perms.sh firmware/ramdisk.dmg

第二条命令 fix_perms.sh 会把 ramdisk 内文件的所有者修正为root:wheel——这是 Darwin 启动的硬性要求（见后面"常见问题"）。

（可选，推荐）用 silence_logs.py 屏蔽几条刷屏的内核日志：

./silence_logs.py firmware/bootkc

⚙️ 四、编译启动虚拟机的 qemu-sptm

darwin-vm 基于 qemu-sptm/——一个为 Apple Silicon + SPTM/TXM 定制了darwin机型的 Qemu 分支（以子模块形式提供），需要先编译它：

git submodule update --init cd qemu-sptm mkdir build cd build ../configure --target-list=aarch64-softmmu --disable-pvg make -j cd ../..

编译完成后，Qemu 可执行文件位于qemu-sptm/build/qemu-system-aarch64。

💡 注意--disable-pvg必须带上：在 macOS 27.0 上，paravirtualized graphics（PVG）已无法编译。

▶️ 五、第一次运行 darwin-vm 虚拟机

一切就绪后，用 run.sh 启动虚拟机——它会自动加载firmware/目录下的内核、设备树、SPTM/TXM 与 ramdisk，并传入rd=md0 serial=3 -v ...等启动参数：

./run.sh

几秒后你就能看到内核日志滚过，最终停在bash-3.2#的root shell提示符上：

bash-3.2# whoami root bash-3.2# uname -v Darwin Kernel Version 27.0.0: ... RELEASE_ARM64_T8142

在终端按Ctrl+A再按x即可退出 Qemu。

💻 六、编译你的第一个程序：用 xcrun 交叉编译

假设你想运行下面这段最简单的 C 程序（保存为hello.c）：

#include <stdio.h> int main() { printf("hello, xnu!\n"); }

用 Xcode 自带的xcrun交叉编译，SDK 按目标系统选择：iOS 虚拟机用iphoneos，macOS 虚拟机用macosx：

xcrun -sdk iphoneos clang hello.c -o hello

一条命令即可生成 arm64 的目标可执行文件。

✍️ 七、签名程序：codesign 免证书 ad-hoc 签名

Darwin 系统强制校验代码签名（arm64e 指令集自带指针认证），未签名或未被信任的二进制根本无法执行。darwin-vm 里用codesign做ad-hoc 签名即可，-s -表示"无证书自签"，不需要任何 Apple 开发者账号：

codesign -s - hello

📦 八、把程序装进虚拟文件系统

虚拟机用的是firmware/ramdisk.dmg这个磁盘镜像，把程序拷贝进去即可。挂载它、复制、卸载：

mkdir mnt hdiutil attach -owners on -mountpoint mnt firmware/ramdisk.dmg sudo cp hello mnt/bin/hello hdiutil detach mnt rmdir mnt

⚠️ 拷入的文件必须属于root:wheel，否则 XNU/launchd 会直接拒绝加载。

🔐 九、构建 trustcache：把你的程序加入信任名单

最后一步是签名信任。Darwin 只运行"信任缓存（trustcache）"中列出 CDHash（代码签名哈希）的二进制。先取出hello的 CDHash 追加到哈希清单，再重建 trustcache 文件：

codesign -d -vvv hello 2>&1 | grep -i cdhash= | cut -d= -f2- >> firmware/all_hashes ./build_tc.py firmware/all_hashes firmware/ramdisk.tc

build_tc.py 会把哈希清单打包成 Darwin 内核认可的 TrustCache 二进制结构（对应内核头文件中的TrustCacheModule1_t，见 build_tc.py 中的结构定义），供 run.sh 通过-tc firmware/ramdisk.tc参数加载。

✅ 十、重启验证：运行你的第一个 iOS/macOS 程序

重新启动虚拟机并执行hello：

bash-3.2# hello hello, xnu!

看到输出即代表你已完整走通 darwin-vm 自定义程序的编译 → 签名 → 注入 → 信任 → 运行全流程 🎉

🐛 十一、常见问题快速排查

1. 系统启动了但没有 shell，日志报Path had bad ownership/permissions

说明 ramdisk 权限没修好。重新执行并重启 VM：

./fix_perms.sh firmware/ramdisk.dmg

2. 编译 qemu-sptm 报error: 'PGTask_t' is unavailable: obsoleted in macOS 27.0

你用了 macOS 27.0+ 却没有禁用 PVG。重新configure时加上--disable-pvg再make。

3. 为什么没有图形界面？

这是设计定位而非缺陷——darwin-vm 目标是裸机级命令行与内核调试环境。想远程登录可启用 SSH/TCP 隧道，见 TCP_TUNNELING_SSH.md。

🧭 十二、下一步进阶方向

• 📡SSH 进虚拟机：通过 UART 隧道在 VM 内跑 SSH 服务器，参见 TCP_TUNNELING_SSH.md
• 🔬调试内核：在 run.sh 的args中加-s暴露 GDB 服务端口，用lldb设置断点、检查内存
• 🧩修改整个文件系统：挂载 ramdisk 后，把 launchd 守护进程放进System/Library/LaunchDaemons、把工具装进bin（记得更新 trustcache）
• 🧵运行开发版内核：用kmutil组合 KDK 内核与系统 kext，构建可调试的 kernelcache

📁 附：darwin-vm 关键文件速查

掌握"编译 + 签名 + trustcache"这条主线后，darwin-vm 就是一台随叫随到的 Darwin 沙盒：改文件系统、调试内核、跑自研工具，都只需几分钟循环。