# macOS profile `macos-27.3-26C5035r` builds a kernel for macOS 27.3 user space. It is an [arm64e profile](/porting/arm64e), so the device must pass the arm64e requirements. One device repository serves the iPadOS and macOS profiles: the macOS values sit in `[os_overrides."macos-27.3-26C5035r"]` of `board.toml`, and an iPadOS build never reads them. This page follows [Port a device](/porting/steps) and names what differs for macOS. Every step not named here is the same as for iPadOS. ## What the profile supplies {#profile} `profiles/os/macos-27.3-26C5035r/profile.toml` in UniXNU: | Table | Content | | --- | --- | | `[os]` | XNU `12377.121.6` with `target = "macosx"`. The kernel is compiled with `XNU_TARGET_OS_OSX` on the machine configuration, memory layout and link address of the iPadOS kernel | | `[ipsw]` | `UniversalMac_27.3_26C5035r_Restore.ipsw`, product `Mac17,11`. `fetch` lists the kernelcache, the device tree and the static, system and application trust caches | | `[kernel.prelink]` | The `kernelcache_sha256` pin, the `roots` of the macOS startup closure and `early_security_init`. A root with a leading `!` is left out of the closure. The collection keeps its symbol tables and its linked addresses, so there is no `slide` | | `[adt]` | The Mac17,11 identity, the `/chosen` boot volume UUIDs and the `asmb` boot policy | | `[userdata]` | Three windows: `OS`, `SystemOS` (`Cryptex1,SystemOS`) and `App` (`Cryptex1,AppOS`) | | `[root]`, `[payload.adt]` | Volume UUIDs and image digests of the three windows, and the root volume UUID | `configs/macos.config` and `patches/xnu/series` beside it hold the kernel configuration and the patch series: the Darwin 26 system calls and kernel interfaces, the macOS machine options, the Data firmlinks, the VM and Hardware volumes on Data, and the application cryptex mount. Signed-text fixups retain their original bytes for verification. Code-signing checks use a bounded snapshot; APFS compressed-block checks use a private copy while resident executable pages keep the configured instructions. ## 1. Check the host and inputs {#inputs} A macOS build runs on a Mac with Xcode. In addition to the [common requirements](/guide/requirements): | Input | Source | | --- | --- | | macOS SDK | Xcode. The boot shim and the device recipes that use macOS family headers compile with `xcrun --sdk macosx` | | IPSW | `[ipsw] url` of the profile, or `--ipsw` | | Kernelcache | Extracted from the IPSW and checked against `kernelcache_sha256` | | Trust caches | `[payload.runtime] trust_components` names the IPSW members that go into the owner trust bundle | | Data seed | Made once as root from the system volume, see [step 4](#data-seed) | | Root access | `sudo` for the Data seed; noninteractive `sudo` for read-only Metal-library enumeration | ## 2. Add the macOS values to the device repository {#device} Add a defconfig for the profile, map it in `[package.defconfig]`, and put every value that differs under the override. The [sheng board file](https://github.com/UniXNU/UniXNU-sheng/blob/00ba90984e831e4c6ce30ec3d8a56e6434e9f1af/board.toml) is a complete example. ```toml [package.defconfig] "macos-27.3-26C5035r" = "_macos_defconfig" [os_overrides."macos-27.3-26C5035r"] remove = ["payload.install", "payload.skip_setup_tool", "payload.runtime.appsync"] [os_overrides."macos-27.3-26C5035r".kernel] defconfig = "_macos_defconfig" config_fragments = ["arch:configs/common.config", "os:configs/macos.config"] archives = [""] [os_overrides."macos-27.3-26C5035r".components] include = [""] [os_overrides."macos-27.3-26C5035r".payload] size_mib = 200 kernel_args = [""] [os_overrides."macos-27.3-26C5035r".payload.adt] chip_id = "6050" [os_overrides."macos-27.3-26C5035r".payload.runtime] target = "macos27" build = "26C5035r" data_seed_tool = "scripts/make-macos-data-seed.py" data_gib = 210 skip_setup = false boot_shims = true ``` | Key | macOS value | | --- | --- | | `[package.defconfig]` | The defconfig that `--os` and the packaging script select for the profile | | `kernel.config_fragments` | `os:configs/macos.config` | | `kernel.patch_series` | No override when the board list uses the `os:` prefix: `os:patches/xnu/series` resolves to the macOS series | | `kernel.archives`, `components.include`, `payload.kernel_args` | Complete lists. Arrays replace the board arrays | | `kernel.prelink.roots` | Not set. The profile list applies. A board list for another profile belongs in that profile's override, because a board value replaces the profile list | | `payload.size_mib` | Room for the kernel collection, the Data seed and the addon | | `payload.adt.chip_id` | `6050`, the chip of Mac17,11 | | `payload.runtime.target`, `build` | `macos27` and `26C5035r` | | `payload.runtime.data_seed_tool` | The seed script that runs as root | | `payload.runtime.data_gib` | Size of the Data volume. The persistent Data store must not overlap the root image in `userdata` | | `payload.runtime.skip_setup` | `true` adds `--skip-setup` to the seed command | | `payload.runtime.boot_shims` | Adds the owner `apfs_boot_util` to the addon, for `apfs-boot-shim=1` | | `payload.runtime.gpu_addon` | `true` builds the Metal plugin for macOS. With `gpu-addon=1` the kernel writes it to `/Library/GPUBundles` on Data | | `remove` | Board keys that apply to iPadOS only, such as the install entry, `payload.skip_setup_tool` and `payload.runtime.appsync` | On sheng the macOS defconfig differs from the iPadOS 27 one only in the Data volume UUID, which the build writes from the seed. The Mac17,11 identity comes from the profile. Kernel arguments that the macOS patch series adds: | Argument | Effect | | --- | --- | | `vc-text=1` | Draws the kernel console as text on the boot framebuffer and mirrors it to the serial console | | `exec-log=1` | Prints every image activation and every exit with its wait status and reason. Diagnostic, off by default | | `apfs-boot-shim=1` | Shows the addon's `apfs_boot_util` over the system's for launchd's mount boot tasks. Needs `boot_shims = true` | | `timebase-hz=24000000` | Gives user space a 24 MHz timebase when the hardware counter runs at another rate | | `gpu-addon=1` | Writes the Metal plugin to `/Library/GPUBundles` | ## 3. Select the profile {#select} `--os` applies to one command. Pass it to every command of a macOS build, or set `board.os_profile` on a board that builds macOS only. `macos-27` resolves to `macos-27.3-26C5035r`, and the output directory is `out//macos-27.3-26C5035r//`. ```sh ./unixnu defconfig _macos_defconfig -D ../UniXNU- --os macos-27 ./unixnu fetch --os macos-27 ./unixnu ipsw info --os macos-27 ./unixnu status --json --os macos-27 ``` `ipsw info` shows `27.3 (26C5035r)`. `status` shows the macOS profile root, the merged override and the patch order. ## 4. Make the Data seed {#data-seed} Build the kernel and the payload in one command, so the kernel build binds the seed's volume UUID: ```sh ./unixnu build kernel payload --os macos-27 ``` Without a seed the command stops before compiling and prints the seed creation command, including the OS image, output path and `data_gib`. ### Create an account and skip Setup {#account} Run from the UniXNU checkout with the paths and size printed by the build. Prompt for a short login name, display name and hidden password: ```sh sudo python3 scripts/make-macos-data-seed.py \ "" "/runtime/data.dbr" --gib "" \ --skip-setup --interactive-user --auto-login ``` The script creates a local administrator and its home, preserves template owners, and skips both initial and first-login Setup. The output seed must be new. The prompts use `admin` and `Admin` as defaults. `sudo` authenticates the build host account; the interactive password is assigned to the new macOS administrator. For automation, replace `--interactive-user` with `--user NAME:PASSWORD` and `--real-name NAME`, or read credentials from a private JSON file: ```sh sudo -v sudo -n python3 scripts/make-macos-data-seed.py \ "" "/runtime/data.dbr" --gib "" \ --skip-setup --user-stdin --auto-login < account.json ``` `account.json` contains `name`, `password` and an optional `real_name` string. `--real-name` overrides the JSON display name. Supplied credentials do not open an account input prompt. Build and pack using that seed: ```sh ./unixnu build kernel payload --os macos-27 \ --data-ramdisk "/runtime/data.dbr" ./unixnu bootimg --os macos-27 \ --data-ramdisk "/runtime/data.dbr" ``` After flashing fresh userdata on sheng, select **Initialize macOS Data and boot** and confirm **Initialize Data and boot**. This erases macOS Data and initializes its persistent store from the seed. Use **Boot** on subsequent starts to retain Data. The account and Setup settings come from the seed; `--skip-setup` is a seed creation option. The sheng macOS desktop profile builds its BootShim, board firmware and DarwinBoot from the selected sources. Its 256 MiB logical payload uses chunk compression and fits the 193 MiB boot-image limit. The menu selects **Boot** after one second. `autoreset=7200` and `uefi-watchdog=1` provide the firmware return timer; `diag-export=7140` retains the boot log before the deadline. Shader Cache is installed in Applications and shows compilation progress. Seed creation options: | Argument | Effect | | --- | --- | | `--skip-setup` | Marks Setup Assistant done | | `--user NAME:PASSWORD` | Adds a local administrator and its home | | `--real-name NAME` | Sets the displayed administrator name; the short account name and `/Users/NAME` remain unchanged | | `--user-stdin` | Reads `name`, `password` and optional `real_name` from a JSON object on standard input | | `--interactive-user` | Prompts for the account name, display name and password | | `--auto-login` | Logs the selected account in at boot. For unattended tests | | `--keyboard-type PRODUCT-VENDOR-COUNTRY=TYPE` | Records a keyboard layout type, so Keyboard Setup Assistant does not ask | | `--volume-uuid UUID` | Gives the Data volume a fixed UUID, so a new seed replaces an older one without a kernel build | Keep `runtime/data.dbr` for every later build of the installation. A payload build with a seed whose UUID differs from the compiled configuration stops and asks for a kernel build. The kernel mounts the seed at `/System/Volumes/Data` and sets the firmlinks of `/usr/share/firmlinks`. ## 5. Build the images {#build} ```sh ./unixnu build kernel payload --os macos-27 ./unixnu build package --os macos-27 ./unixnu build firmware --os macos-27 ./unixnu build userdata --os macos-27 --dry-run ./unixnu build userdata --os macos-27 ./unixnu bootimg --os macos-27 ``` The packaging script runs the same steps except userdata: ```sh scripts/package.sh --os macos-27 --uefi ../uefi- ``` For sheng, prepare the [LLVM 22 tools](/porting/uefi-firmware), then save the installation inputs in the UniXNU checkout's `unixnu.local.toml`: ```toml [build] device = "../UniXNU-sheng" uefi = "../uefi-sheng" clang_bin = ".cache/edk2-llvm22" data_ramdisk = "/path/to/installed-data.dbr" unique_chip_id = "" ``` Then run `../UniXNU-sheng/scripts/package.sh --os macos-27` from UniXNU. Add the [exported kernel tool paths](/guide/build-kernel#local-builds-with-exported-inputs) on a host using exported build inputs. `package.manifest.json` records the source revisions, complete boot arguments and runtime input identities. The sheng macOS workflow uses Xcode 26.6, Python 3.14 and LLVM/LLD 22. Configure repository secrets `UNIXNU_UNIQUE_CHIP_ID` and `UNIXNU_LAB_PASSWORD` for the device identity and the initial administrator account. `root_storage=true` builds the three verified root windows and userdata; `false` retains the profile's signed policies for a boot-image update. A saved Android sparse userdata image can supply the three root images locally: ```sh python3 ../UniXNU-sheng/scripts/restore-macos-images.py /path/to/userdata.sparse ``` The script checks each recovered image against the selected OS profile and stores it as `out/ipsw//.raw.dmg`. The build uses these verified images. Reserve their combined size plus build space before extraction. | Step | macOS difference | | --- | --- | | Kernel | `XNU_TARGET_OS_OSX`, the macOS series and the prelink against the macOS kernel collection | | Payload | The Mac17,11 ADT, the owner trust bundle and the addon built for `macos27` | | Userdata | Three windows. Check the dry-run capacity against `data_gib` | | Package, firmware, boot image | None | A board that links owner root policies (`CONFIG_XNU_SOURCE_STORAGE=y`) needs a signed policy for each window. `scripts/make-root-policies.py --tree TREE --output POLICIES --window NAME=IMAGE:VOLUME_UUID` writes `POLICIES/NAME/manifest.header.bin`, `trusted-key.bin` and `verification.json`, and the hash table `TREE/build/verified-root-NAME/hashes.bin`. `IMAGE` holds the window's bytes; its SHA-256 equals `[root] _image_sha256` of the profile. The storage archive recipe reads the policy directory named by its `--policy-dir` argument. With `CONFIG_XNU_SOURCE_STORAGE_TABLES="userdata"`, add each hash table to the userdata image as `--object NAME.vroot=FILE`. ## 6. Adapt the drivers {#drivers} Follow [driver adaptation](/porting/drivers) in the same order. The macOS kernel collection has its own class layouts, and macOS user space expects some services that iPadOS does not. The sheng port shows each case: | Area | macOS adaptation | | --- | --- | | Private class bindings | A fixture per build for each bound class family, `scripts/-26C5035r.json`. `scripts/gen-board-abi.py` writes them from the symbols of the collection, and the display recipe selects them by build | | Crypto | `SoftwareAES` joins `components.include` and `kernel.archives`, compiled against the 26C5035r class layout. A board probe registers it, because AppleImage4 waits for an `IOAESAccelerator` service | | Network | `en0` is an `IOEthernetController` of the original IONetworkingFamily, started with `ethernet=1`. It carries the Wi-Fi module's frames. The TimeSync clock takes its identifier from the address of an Ethernet or 802.11 interface, and WindowServer waits for that clock. The supplicant is built for macOS and its job is a plist in `/Library/LaunchDaemons` | | Input | The HID device starts with `offline-hid-home=1`. WindowServer pairs the touch screen with the display through the service's `displayUUID`, the UUID the framebuffer publishes as `IOMFBUUID` | | Keyboard cover | A keyboard and a pointer: relative motion, scroll steps and two buttons, without the Keyboard Power usage | | GPU | The plugin is built as a macOS bundle with its executable in `Contents/MacOS` | | Audio | The audio server plug-in is a macOS driver bundle in `/Library/Audio/Plug-Ins/HAL` | | Bluetooth | The daemon opens the serial device `/dev/cu.BLTH`. The board's daemon, BlueTool and capability library sit in the addon's `sbin` and `lib`, shown over `/usr/sbin` and `/usr/lib` | | Firmware images in the kernel | Placed in `__DATA,__firmware` | ## 7. Boot and check {#bring-up} Flash the userdata image and boot as in [Boot the image](/guide/boot). The [bring-up order](/porting/bring-up) applies with these macOS checkpoints: | Stage | Check | | --- | --- | | Storage and root | The partition scheme publishes `OS`, `SystemOS` and `App`. The root is the read-only system volume with SystemOS mounted over it | | Data | Data mounts at `/System/Volumes/Data`. `/System/Volumes/VM` and `/System/Volumes/Hardware` resolve into it | | Cryptexes | The OS cryptex view and the App cryptex appear below `/System/Volumes/Preboot/Cryptexes` | | Userland | launchd finishes its boot tasks and WindowServer presents the login window or Setup Assistant | `vc-text=1` keeps the kernel log on the panel. `exec-log=1` names a boot task that fails. ## 8. Record the results {#record} `device.os_profile` in `porting.toml` equals `board.os_profile`, the default profile of the board. A board that serves several profiles keeps one record: write the macOS configuration, findings and evidence into the same areas and name the profile and build in each entry. See [porting records](/porting/records).