# theiphoneos1project/ld64-build architecture

> Architecture diagram of the GitHub repository theiphoneos1project/ld64-build, 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/ld64-build
- Repository: https://github.com/theiphoneos1project/ld64-build

## Overview

#### Purpose and Entry Point
This repository is a macOS build wrapper for producing a patched `ld64` linker binary, `ld64-objc1`, with fragile Objective-C runtime support. Its operational entry point is `build.sh`; the repository intentionally contains only orchestration and source patches, not vendored third-party code.

Paths: `build.sh`, `README.md`

#### Build Orchestration
`build.sh` is the primary control plane. It runs interactively by default and supports automation through `--non-interactive`. It fetches required upstream dependencies at build time, applies this repository’s patches, and compiles the resulting linker with the active Xcode toolchain.

The script’s environment is macOS 12+ with Xcode 14+ and C++20 support. Output architecture depends on Xcode generation: older toolchains can produce universal `x86_64`/`arm64` output, while Xcode 26+ produces `arm64`.

Paths: `build.sh`, `.github/workflows/build.yml`

#### Upstream Source Boundary
No third-party source is committed here. The build process crosses a deliberate boundary from repository-owned scripts/patches into externally fetched ld64 and related dependency sources. Reproducibility therefore depends on the fetch behavior encoded in `build.sh` and on availability/compatibility of upstream repositories and the installed Xcode SDK.

Paths: `build.sh`, `README.md`

#### Patch Layer
The `Patches/` directory defines the product’s differentiating behavior: adapting ld64 to support fragile Objective-C runtime handling. Patches target linker option processing, output-file generation, LTO integration, Mach-O relocatable-file processing, and Apple dynamic-loader private declarations.

Key patch surface:
- Linker option and mode behavior: `Patches/Options.cpp.patch`
- Output binary/linker behavior: `Patches/OutputFile.cpp.patch`
- LTO file handling: `Patches/lto_file.cpp.patch`
- Mach-O relocatable-object handling: `Patches/macho_relocatable_file.cpp.patch`
- dyld-private API compatibility: `Patches/dyld_priv.h.patch`
- Version metadata changes: `Patches/Version.inc`

#### Produced Artifact and Runtime Boundary
The build produces `ld64-objc1`, a linker executable rather than a standalone application. The binary is dynamically coupled to Xcode-provided libraries, specifically `libtapi.dylib` and `libswiftDemangle.dylib`. It will fail at launch unless those libraries are reachable through its runtime loader paths.

Deployment is therefore separate from compilation: users should install the executable beside a `lib/` directory containing copies of the required dylibs, or place it in an existing Xcode-compatible toolchain.

Paths: `README.md`, `build.sh`

#### CI and Validation Infrastructure
GitHub Actions provides the repository’s automated build environment. The workflow is the main infrastructure contract for verifying that the script, patch set, and supported macOS/Xcode environment remain compatible.

Paths: `.github/workflows/build.yml`, `build.sh`

#### Ownership and Licensing
Repository-owned orchestration and patches are MIT-licensed. Upstream ld64 and fetched dependencies remain under their own licenses, reinforcing the separation between this build layer and externally sourced compiler/linker code.

Paths: `LICENSE`, `Patches/`, `README.md`

Main entry points: [`build.sh`](https://github.com/theiphoneos1project/ld64-build/blob/main/build.sh) (Build orchestrator), [`README.md`](https://github.com/theiphoneos1project/ld64-build/blob/main/README.md) (Build and deployment guidance), [`LICENSE`](https://github.com/theiphoneos1project/ld64-build/blob/main/LICENSE) (MIT license), [`.github/workflows/build.yml`](https://github.com/theiphoneos1project/ld64-build/blob/main/.github/workflows/build.yml) (GitHub Actions build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository-owned build layer"]
  node_build["Build orchestrator<br/>shell script<br/>[build.sh]"]
  node_readme["Build and deployment guidance<br/>documentation<br/>[README.md]"]
  node_workflow["GitHub Actions build<br/>CI workflow<br/>[build.yml]"]
  node_patches["Fragile ObjC patch set<br/>patch directory"]
  node_options_patch["Linker options and modes<br/>ld64 patch<br/>[Options.cpp.patch]"]
  node_output_patch["Output-file behavior<br/>ld64 patch"]
  node_lto_patch["LTO handling<br/>ld64 patch<br/>[lto_file.cpp.patch]"]
  node_macho_patch["Mach-O relocatable handling<br/>ld64 patch"]
  node_dyld_patch["dyld private compatibility<br/>header patch<br/>[dyld_priv.h.patch]"]
  node_version["Version metadata<br/>version file<br/>[Version.inc]"]
  node_license["MIT license"]
end

subgraph group_upstream["Fetched upstream sources"]
  node_upstream_sources[("ld64 and dependencies<br/>external source")]
  node_xcode{{"macOS Xcode toolchain<br/>build environment"}}
  node_patched_ld64["Patched ld64 source tree<br/>build workspace"]
end

subgraph group_runtime["Deployment runtime"]
  node_artifact["ld64-objc1<br/>linker executable"]
  node_xcode_libs[("Xcode runtime dylibs<br/>dynamic libraries")]
  node_deployment["Installed toolchain layout<br/>deployment target"]
end

node_user(("Developer or CI<br/>build invoker"))

node_user -->|"runs"| node_build
node_workflow -->|"automates"| node_build
node_readme -.->|"documents"| node_build
node_build -->|"fetches"| node_upstream_sources
node_build -->|"applies"| node_patches
node_patches -.->|"contains"| node_options_patch
node_patches -.->|"contains"| node_output_patch
node_patches -.->|"contains"| node_lto_patch
node_patches -.->|"contains"| node_macho_patch
node_patches -.->|"contains"| node_dyld_patch
node_patches -.->|"contains"| node_version
node_upstream_sources -->|"provides base sources"| node_patched_ld64
node_patches -->|"modifies"| node_patched_ld64
node_xcode -->|"provides compiler and SDK"| node_build
node_build -->|"builds"| node_artifact
node_patched_ld64 -->|"compiled as"| node_artifact
node_xcode_libs -->|"required at launch"| node_artifact
node_artifact -->|"installed with"| node_deployment
node_readme -.->|"documents"| node_deployment
node_license -.->|"licenses"| node_build
node_license -.->|"licenses"| node_patches

click node_build "https://github.com/theiphoneos1project/ld64-build/blob/main/build.sh"
click node_readme "https://github.com/theiphoneos1project/ld64-build/blob/main/README.md"
click node_workflow "https://github.com/theiphoneos1project/ld64-build/blob/main/.github/workflows/build.yml"
click node_options_patch "https://github.com/theiphoneos1project/ld64-build/blob/main/Patches/Options.cpp.patch"
click node_output_patch "https://github.com/theiphoneos1project/ld64-build/blob/main/Patches/OutputFile.cpp.patch"
click node_lto_patch "https://github.com/theiphoneos1project/ld64-build/blob/main/Patches/lto_file.cpp.patch"
click node_macho_patch "https://github.com/theiphoneos1project/ld64-build/blob/main/Patches/macho_relocatable_file.cpp.patch"
click node_dyld_patch "https://github.com/theiphoneos1project/ld64-build/blob/main/Patches/dyld_priv.h.patch"
click node_version "https://github.com/theiphoneos1project/ld64-build/blob/main/Patches/Version.inc"
click node_license "https://github.com/theiphoneos1project/ld64-build/blob/main/LICENSE"

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_build,node_readme,node_workflow,node_patches,node_options_patch,node_output_patch,node_lto_patch,node_macho_patch,node_dyld_patch,node_version,node_license toneBlue
class node_upstream_sources,node_xcode,node_patched_ld64 toneAmber
class node_artifact,node_xcode_libs,node_deployment toneMint
class node_user toneNeutral
```

## Components

### Repository-owned build layer

MIT-licensed orchestration and ld64 patch set.

- [Build orchestrator](https://github.com/theiphoneos1project/ld64-build/blob/main/build.sh): shell script · Interactive by default; supports --non-interactive automation. · `build.sh`
- [Build and deployment guidance](https://github.com/theiphoneos1project/ld64-build/blob/main/README.md): documentation · `README.md`
- [GitHub Actions build](https://github.com/theiphoneos1project/ld64-build/blob/main/.github/workflows/build.yml): CI workflow · Validates script, patches, and supported macOS/Xcode compatibility. · `.github/workflows/build.yml`
- **Fragile ObjC patch set**: patch directory · Repository-specific ld64 behavior changes.
- [Linker options and modes](https://github.com/theiphoneos1project/ld64-build/blob/main/Patches/Options.cpp.patch): ld64 patch · `Patches/Options.cpp.patch`
- [Output-file behavior](https://github.com/theiphoneos1project/ld64-build/blob/main/Patches/OutputFile.cpp.patch): ld64 patch · `Patches/OutputFile.cpp.patch`
- [LTO handling](https://github.com/theiphoneos1project/ld64-build/blob/main/Patches/lto_file.cpp.patch): ld64 patch · `Patches/lto_file.cpp.patch`
- [Mach-O relocatable handling](https://github.com/theiphoneos1project/ld64-build/blob/main/Patches/macho_relocatable_file.cpp.patch): ld64 patch · `Patches/macho_relocatable_file.cpp.patch`
- [dyld private compatibility](https://github.com/theiphoneos1project/ld64-build/blob/main/Patches/dyld_priv.h.patch): header patch · `Patches/dyld_priv.h.patch`
- [Version metadata](https://github.com/theiphoneos1project/ld64-build/blob/main/Patches/Version.inc): version file · `Patches/Version.inc`
- [MIT license](https://github.com/theiphoneos1project/ld64-build/blob/main/LICENSE): license · Applies to repository-owned orchestration and patches. · `LICENSE`

### Fetched upstream sources

Third-party sources are acquired at build time.

- **ld64 and dependencies**: external source · Fetched rather than vendored; retain their own licenses.
- **macOS Xcode toolchain**: build environment · Requires macOS 12+, Xcode 14+, and C++20 support.
- **Patched ld64 source tree**: build workspace · Transient upstream source after patch application.

### Deployment runtime

The linker requires Xcode-provided dynamic libraries.

- **ld64-objc1**: linker executable · Universal x86_64/arm64 on older Xcode or arm64 on Xcode 26+.
- **Xcode runtime dylibs**: dynamic libraries · libtapi.dylib and libswiftDemangle.dylib must be reachable at launch.
- **Installed toolchain layout**: deployment target · Place the executable beside lib/ copies or in a compatible Xcode toolchain.

### Other components

- **Developer or CI**: build invoker

## Connections

- Developer or CI → Build orchestrator: runs
- GitHub Actions build → Build orchestrator: automates
- Build and deployment guidance → Build orchestrator: documents
- Build orchestrator → ld64 and dependencies: fetches
- Build orchestrator → Fragile ObjC patch set: applies
- Fragile ObjC patch set → Linker options and modes: contains
- Fragile ObjC patch set → Output-file behavior: contains
- Fragile ObjC patch set → LTO handling: contains
- Fragile ObjC patch set → Mach-O relocatable handling: contains
- Fragile ObjC patch set → dyld private compatibility: contains
- Fragile ObjC patch set → Version metadata: contains
- ld64 and dependencies → Patched ld64 source tree: provides base sources
- Fragile ObjC patch set → Patched ld64 source tree: modifies
- macOS Xcode toolchain → Build orchestrator: provides compiler and SDK
- Build orchestrator → ld64-objc1: builds
- Patched ld64 source tree → ld64-objc1: compiled as
- Xcode runtime dylibs → ld64-objc1: required at launch
- ld64-objc1 → Installed toolchain layout: installed with
- Build and deployment guidance → Installed toolchain layout: documents
- MIT license → Build orchestrator: licenses
- MIT license → Fragile ObjC patch set: licenses