hackios-xnu-userland README

The project's README from github.com/oosexgang/hackios-xnu-userland. As one markdown file: README.md.

HackiOS — userland

The user-space half of HackiOS: Apple's open-source XNU kernel on Android phone hardware (POCO X5 Pro 5G) and in QEMU, running the unmodified iOS 16.5 user space. The kernel, loader, UEFI and the common/ scripts are in hackios-xnu-kernel — start there.

No Apple files are in this repository. ios165/fetch.sh downloads the iOS 16.5 IPSW from Apple's CDN to your machine and extracts what is needed there. HackiOS is an independent research project by OOSEX GANG and is not affiliated with, authorised or endorsed by Apple Inc.

Getting it

The two repositories are built as one tree. Clone the kernel repository and let it bring this one in:

git clone https://github.com/oosexgang/hackios-xnu-kernel.git hackios
cd hackios
common/setup.sh        # checks this repository out into the same directory (git dir .userland.git)
common/ugit status     # git for this repository inside that tree

What is here

Path What
userland/build.sh builds the APFS images: root.apfs (our init, libraries, launchd jobs, firmware) and system.apfs (the selected part of iOS 16.5 and its cryptexes); every option is documented at the top
userland/src/ init.c (process 1), injected libraries (inject.c backboardd, inject_sb.c SpringBoard, inject_media.c mediaserverd, inject_tweaks.c), the CoreAudio output device (audio_plugin.c), the OpenGL ES bridge to Mesa (eagl.c), Metal driver work, tests
userland/libmini/ a tiny libc for the static programs
userland/rc.*, com.redwood.*.plist job lists and launchd jobs for test scenarios (RC_JOBS=rc.jobs.tour, rc.jobs.ssh, ...)
userland/mkjobs.py, jobinfo.py the stock iOS launchd jobs: which are loaded, who provides a Mach service
userland/var/ our default preferences for /private/var
ios165/ fetch.sh / fetch-from-ipsw.py (take iOS out of the IPSW), select-system.py (what goes into the image)
tools/apfs/ APFS on the computer: mkapfs.py (image writer), reader, checks, write tests
tools/mk-mesa.sh, tools/mesa/ Mesa 25.0.7 with our patches: freedreno on Darwin, the AIR (Metal IR) frontend
tools/air/, tools/metal/, tools/metallib.py Metal shader (AIR) checks and analysis; notes in docs/air.md
tools/mk-jb.sh, jb-preinstall.py Procursus bootstrap + Sileo for the package manager prefix
tools/font_trim.py trims two oversized iOS fonts so the image fits
prebuilt/userland/ our programs and libraries, built — used when there is no cross toolchain

Building the images

ios165/fetch.sh               # once
REST=1 userland/build.sh      # -> userland/root.apfs, userland/system.apfs
GL=1 REST=1 userland/build.sh # with OpenGL ES (Mesa) for the window server; on the phone with gpu=1

Without the cross toolchain (theos + iPhoneOS16.5.sdk, see the kernel repository) the build takes our programs from prebuilt/userland; with it, it compiles userland/src.

A job list (RC_JOBS=file) is run by our init, not by a shell: iOS 16.5's root has no shell, lines are split on blanks, there is no quoting and no variable assignment; only >> FILE and a trailing & are understood.

Licenses

Our code in this repository is released under the MIT License. Mesa (MIT) is not in the repository: tools/mk-mesa.sh fetches release 25.0.7, tools/mesa/*.patch are our changes to it. apfsprogs (GPL-2.0) is not in the repository either: tools/apfs/check-image.sh fetches and builds only apfsck.

OOSEX GANG — t.me/oosexgangdevs

hackios-xnu-userland (oosexgang/hackios-xnu-userland)

hardware-hacking
Searching Database…

383 ·GitHub
Hackios-xnu-userland
What is this?HackiOS-userland is the user-space half of HackiOS, a project that runs Apple's open-source XNU kernel with an unmodified iOS 16.5 user space on Android phone hardware (a POCO X5 Pro 5G) and in QEMU.
Is this a standalone repo, or does it depend on another one?It is built as one tree together with the hackios-xnu-kernel repository, which provides the kernel, loader, UEFI and shared scripts; you clone the kernel repo and it pulls this userland repo in.
How do I build the iOS userland images?Run userland/build.sh, which produces root.apfs (init, libraries, launchd jobs, firmware) and system.apfs (the selected part of iOS 16.5 and its cryptexes); every build option is documented at the top of the script.
Do I need Apple's IPSW or a cross-compiler to build this?You need ios165/fetch.sh to pull the iOS 16.5 IPSW straight from Apple's CDN since no Apple files ship in the repo; a theos + iPhoneOS16.5.sdk cross toolchain lets you compile userland/src yourself, otherwise the build falls back to prebuilt binaries in prebuilt/userland.
Does the stock iOS job-list format support real shell scripting?No — job lists like rc.jobs.tour are run by their own init, not a shell: iOS 16.5's root has no shell, lines just split on blanks with no quoting or variable assignment, only redirection (>>) and a trailing & are understood.
Does this run on real Android hardware or only in an emulator?Both — the project targets a real Android phone (POCO X5 Pro 5G) as well as QEMU, with the GPU bridge (Mesa/freedreno) built to work on the real device's hardware.
Does this need a particular GPU or graphics driver setup?Yes — the project patches Mesa 25.0.7 to add a freedreno driver on Darwin plus an AIR (Metal IR) frontend, used as the OpenGL ES/Metal bridge on the target hardware.
What does init.c actually do?It is process 1 for the custom userland, started by the build's root image to bring up the injected libraries and launchd job lists that recreate the iOS boot sequence.
Why was the POCO X5 Pro 5G chosen as the target device?The README does not explain the choice explicitly, but it is listed as the specific Android phone hardware the project's kernel and GPU bridge were made to run on.
What package manager can I use once iOS userspace is running?tools/mk-jb.sh and jb-preinstall.py set up a Procursus bootstrap with Sileo, giving the userland a familiar jailbreak-style package manager prefix.
How does the OpenGL/Metal graphics bridge work?eagl.c implements an OpenGL ES bridge to Mesa, while the patched Mesa adds a freedreno backend and an AIR (Metal IR) frontend so iOS Metal shaders can run against the Android GPU; AIR/Metal shader checks live under tools/air and tools/metal.
What are similar projects?ios-sweet, ios-topaz, hackios-xnu-kernel, Snapintosh, UniXNU, gpu-unlock-ada, PCILeechGen, OpenCorePkg
Which topics is it in?ios-jailbreak, hardware-hacking, qemu, driver, opengl, operating-system, metal, kernel, low-level, gplv2, firmware, systems-programming
Creator
oosexgang
Size
0 MB
Stars
383
Updated
CommitOct 25
Age
4d
Commits · 90 Days