# theiphoneos1project/iphoneos1-sdk architecture

> Architecture diagram of the GitHub repository theiphoneos1project/iphoneos1-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theiphoneos1project/iphoneos1-sdk
- Repository: https://github.com/theiphoneos1project/iphoneos1-sdk

## Overview

#### Purpose and Entry Point
This repository generates a compatibility SDK for targeting iPhone OS 1. It assembles user-supplied Mac OS X 10.5 and iPhone OS 2 SDK material with repository-provided overrides, linker shims, and runtime startup support. The operational entry point is `generate.py`; it accepts source SDK paths plus `include`, `shim_sdk`, and `csu` inputs.

#### Generation Orchestrator
`generate.py` is the control-plane script: it receives SDK locations and an output path, then constructs the generated SDK from multiple source boundaries. The repository does not contain an application or device-side service; its main product is a filesystem SDK layout for downstream compilers/linkers.
- `generate.py`
- `README.md`

#### Header Reconstruction Layer
The checked-in `include/` tree supplies manually written or reverse-engineered compatibility headers and local API declarations that complement copied upstream headers. It spans public and private iPhone-era frameworks, making this the primary compile-time API surface.
- `include/UIKit/UIKit.h`
- `include/Message/Message.h`
- `include/Celestial/Celestial.h`

#### Platform and ABI Surface
Low-level C, ARM, Mach, and system declarations establish the target ABI expected by old iPhone OS binaries. This is a boundary between source compatibility and the ARM/device execution environment.
- `include/architecture/arm/`
- `include/mach/arm/`
- `include/arm/_types.h`

#### Link-Time Framework Shim SDK
`shim_sdk/` mirrors `/System/Library/Frameworks` and private-framework locations using `.tbd` linker-interface files rather than Apple binaries. The generated SDK uses these interfaces to resolve framework linkage while actual implementations remain on the target device.
- `shim_sdk/System/Library/Frameworks/UIKit.framework/UIKit.tbd`
- `shim_sdk/System/Library/Frameworks/Foundation.framework/Foundation.tbd`
- `shim_sdk/System/Library/PrivateFrameworks/vmutils.framework/vmutils.tbd`

#### Runtime Startup Support
The `csu/` directory provides ARM C runtime/startup artifacts required for produced binaries to start correctly on-device, including assembly entry glue and CRT objects. This is the execution-time boundary between linked app code and the platform dynamic loader/runtime.
- `csu/arm-start.s`
- `csu/arm-dyld-glue.s`
- `csu/crt.c`

#### Primary Flow and External Dependencies
1. A user provides legally obtained Mac OS X 10.5 and iPhone OS 2 SDK directories.
2. `generate.py` combines selected upstream headers with `include/` overrides/compatibility declarations.
3. It incorporates `shim_sdk/` framework interfaces for linker resolution and `csu/` runtime files for binary startup.
4. The resulting SDK is consumed by an ARM/iPhone OS toolchain; linked applications depend at runtime on frameworks supplied by an iPhone OS 1 device.

Material external dependencies are Python 3, the two user-provided SDKs, an ARM-capable compiler/linker toolchain, and device-resident Apple frameworks. The repository itself intentionally avoids distributing Apple SDK binaries.

Main entry points: [`generate.py`](https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/generate.py) (SDK generator), [`shim_sdk/System/Library/Frameworks/UIKit.framework/UIKit.tbd`](https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/shim_sdk/System/Library/Frameworks/UIKit.framework/UIKit.tbd) (Framework shim SDK), [`csu/arm-start.s`](https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/csu/arm-start.s) (ARM startup support), [`include/UIKit/UIKit.h`](https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/include/UIKit/UIKit.h) (Compatibility headers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["External inputs"]
  node_mac_sdk[("Mac OS X 10.5 SDK<br/>upstream SDK")]
  node_iphone_sdk[("iPhone OS 2 SDK<br/>upstream SDK")]
end

subgraph group_sources["Repository sources"]
  node_generator{{"SDK generator<br/>Python orchestrator<br/>[generate.py]"}}
  node_compat_headers["Compatibility headers<br/>header layer<br/>[UIKit.h]"]
  node_message_headers["Message declarations<br/>framework headers<br/>[Message.h]"]
  node_celestial_headers["Celestial declarations<br/>private headers<br/>[Celestial.h]"]
  node_abi_headers["ARM and Mach ABI headers<br/>ABI surface"]
  node_arm_types["ARM type declarations<br/>ABI headers<br/>[_types.h]"]
  node_shim_sdk["Framework shim SDK<br/>linker interfaces<br/>[UIKit.tbd]"]
  node_private_shims["Private framework shims<br/>linker interfaces<br/>[vmutils.tbd]"]
  node_startup["ARM startup support<br/>CRT and assembly<br/>[arm-start.s]"]
end

subgraph group_output["Generated SDK use"]
  node_generated_sdk[("iPhone OS 1 compatibility SDK<br/>filesystem SDK")]
  node_toolchain{{"ARM compiler and linker<br/>downstream toolchain"}}
  node_device_frameworks[("iPhone OS 1 device frameworks<br/>runtime platform")]
end

node_mac_sdk -->|"source headers"| node_generator
node_iphone_sdk -->|"source headers"| node_generator
node_compat_headers -->|"overrides"| node_generator
node_message_headers -->|"API declarations"| node_generator
node_celestial_headers -->|"API declarations"| node_generator
node_abi_headers -->|"target ABI"| node_generator
node_arm_types -->|"ARM types"| node_generator
node_shim_sdk -->|"framework interfaces"| node_generator
node_private_shims -->|"private interfaces"| node_generator
node_startup -->|"CRT artifacts"| node_generator
node_generator -->|"assembles"| node_generated_sdk
node_generated_sdk -->|"compile and link target"| node_toolchain
node_toolchain -.->|"linked apps use at runtime"| node_device_frameworks
node_shim_sdk -.->|"interfaces correspond to"| node_device_frameworks
node_startup -->|"binary entry support"| node_toolchain

click node_generator "https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/generate.py"
click node_compat_headers "https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/include/UIKit/UIKit.h"
click node_message_headers "https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/include/Message/Message.h"
click node_celestial_headers "https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/include/Celestial/Celestial.h"
click node_arm_types "https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/include/arm/_types.h"
click node_shim_sdk "https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/shim_sdk/System/Library/Frameworks/UIKit.framework/UIKit.tbd"
click node_private_shims "https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/shim_sdk/System/Library/PrivateFrameworks/vmutils.framework/vmutils.tbd"
click node_startup "https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/csu/arm-start.s"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mac_sdk,node_iphone_sdk toneBlue
class node_generator,node_compat_headers,node_message_headers,node_celestial_headers,node_abi_headers,node_arm_types,node_shim_sdk,node_private_shims,node_startup toneAmber
class node_generated_sdk,node_toolchain,node_device_frameworks toneMint
```

## Components

### External inputs

- **Mac OS X 10.5 SDK**: upstream SDK · User-supplied source material.
- **iPhone OS 2 SDK**: upstream SDK · User-supplied source material.

### Repository sources

- [SDK generator](https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/generate.py): Python orchestrator · Combines upstream material and repository compatibility layers. · `generate.py`
- [Compatibility headers](https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/include/UIKit/UIKit.h): header layer · Local public and private API declarations. · `include/UIKit/UIKit.h`
- [Message declarations](https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/include/Message/Message.h): framework headers · `include/Message/Message.h`
- [Celestial declarations](https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/include/Celestial/Celestial.h): private headers · `include/Celestial/Celestial.h`
- **ARM and Mach ABI headers**: ABI surface · C, ARM, Mach, and system target declarations.
- [ARM type declarations](https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/include/arm/_types.h): ABI headers · `include/arm/_types.h`
- [Framework shim SDK](https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/shim_sdk/System/Library/Frameworks/UIKit.framework/UIKit.tbd): linker interfaces · TBD interfaces replace distributed Apple framework binaries. · `shim_sdk/System/Library/Frameworks/UIKit.framework/UIKit.tbd`
- [Private framework shims](https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/shim_sdk/System/Library/PrivateFrameworks/vmutils.framework/vmutils.tbd): linker interfaces · `shim_sdk/System/Library/PrivateFrameworks/vmutils.framework/vmutils.tbd`
- [ARM startup support](https://github.com/theiphoneos1project/iphoneos1-sdk/blob/main/csu/arm-start.s): CRT and assembly · Entry glue and runtime startup objects. · `csu/arm-start.s`

### Generated SDK use

- **iPhone OS 1 compatibility SDK**: filesystem SDK · Generated compiler and linker target layout.
- **ARM compiler and linker**: downstream toolchain
- **iPhone OS 1 device frameworks**: runtime platform · Actual framework implementations remain on the device.

## Connections

- Mac OS X 10.5 SDK → SDK generator: source headers
- iPhone OS 2 SDK → SDK generator: source headers
- Compatibility headers → SDK generator: overrides
- Message declarations → SDK generator: API declarations
- Celestial declarations → SDK generator: API declarations
- ARM and Mach ABI headers → SDK generator: target ABI
- ARM type declarations → SDK generator: ARM types
- Framework shim SDK → SDK generator: framework interfaces
- Private framework shims → SDK generator: private interfaces
- ARM startup support → SDK generator: CRT artifacts
- SDK generator → iPhone OS 1 compatibility SDK: assembles
- iPhone OS 1 compatibility SDK → ARM compiler and linker: compile and link target
- ARM compiler and linker → iPhone OS 1 device frameworks: linked apps use at runtime
- Framework shim SDK → iPhone OS 1 device frameworks: interfaces correspond to
- ARM startup support → ARM compiler and linker: binary entry support