# Key Dependencies of vphone-cli: Swift Packages, Frameworks, and Python Libraries

> Discover vphone-cli's key dependencies: Swift packages, Apple frameworks, and Python libraries. Learn how they enable virtual iPhone booting and firmware manipulation on macOS.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: internals
- Published: 2026-09-05

---

**`vphone-cli` relies on five core Swift packages, six Apple system frameworks, and three Python libraries to enable virtual iPhone booting and firmware manipulation on macOS.**

`vphone-cli` is a Swift-based macOS command-line tool that creates a virtualized iPhone environment using Apple's Virtualization framework. Understanding the key dependencies of vphone-cli is essential for developers contributing to the project or troubleshooting build issues. The codebase integrates third-party Swift packages for low-level firmware operations, links against private and public Apple frameworks for VM orchestration, and leverages Python scripts for auxiliary patching tasks.

## Swift Package Dependencies

The project declares five critical Swift package dependencies in [[`Package.swift`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift)](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift) that handle everything from CLI parsing to binary manipulation.

### swift-argument-parser

**swift-argument-parser** provides the modern declarative interface for command-line argument parsing. In [[`sources/vphone-cli/VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneCLI.swift)](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneCLI.swift), the main entry point conforms to `ParsableCommand` and uses property wrappers like `@Option` to define CLI flags:

```swift
import ArgumentParser

@main
struct VPhoneCLI: ParsableCommand {
    @Option(name: .shortAndLong, help: "Path to the IPSW file")
    var ipsw: String
    
    func run() throws {
        let orchestrator = VPhoneCreateOrchestrator(ipswPath: ipsw)
        try orchestrator.start()
    }
}

```

### Dynamic

**Dynamic** enables runtime access to private Apple APIs without requiring Objective-C bridging headers. This package is crucial for invoking undocumented Virtualization framework features that standard Swift cannot access directly.

### libcapstone-spm and libimg4-spm

**libcapstone-spm** wraps the Capstone disassembly engine, while **libimg4-spm** provides Swift bindings for `img4tool`. These work together in [[`sources/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift)](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift) to disassemble firmware images, locate specific instructions, and reassemble modified binaries:

```swift
import Capstone
import Img4tool

func applyPatch(to image: IM4P) throws -> IM4P {
    let disasm = try Capstone.disassemble(image.data)
    let patched = try Keystone.assemble("nop")
    return try image.replacingBytes(at: targetOffset, with: patched)
}

```

### MachOKit

**MachOKit** supplies Mach-O binary parsing and code signing utilities required for IPA extraction and re-signing. The library validates executable architectures and handles entitlement injection before packages are installed in the virtual machine.

## Apple System Frameworks

The executable target links against several Apple frameworks to provide hardware abstraction and host integration.

### Virtualization Framework

**Virtualization** is the core framework that creates and manages the virtual iPhone VM. In [[`sources/VPhoneCore/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/VPhoneCore/VPhoneVirtualMachine.swift)](https://github.com/Lakr233/vphone-cli/blob/main/sources/VPhoneCore/VPhoneVirtualMachine.swift), the code configures `VZVirtualMachine` instances with specific hardware models, storage attachments, and network interfaces to emulate iPhone-class devices.

### UI and Media Frameworks

- **AppKit**: Provides the macOS windowing system for the GUI boot mode, handling native window management and event loops.
- **SwiftUI**: Implements modern file-browser interfaces and configuration panels using declarative syntax.
- **AVFoundation**: Enables screen recording and audio capture from the virtual device, streaming host audio into the guest environment.
- **CoreLocation**: Supplies host location data that gets forwarded to the guest VM via the location provider bridge.

The location forwarding implementation in the source uses `CLLocationManager` to bridge host GPS data:

```swift
import CoreLocation
import VPhoneControl

class LocationProvider: NSObject, CLLocationManagerDelegate {
    private let manager = CLLocationManager()
    private let control = VPhoneControl.shared
    
    func start() {
        manager.delegate = self
        manager.requestWhenInUseAuthorization()
        manager.startUpdatingLocation()
    }
    
    func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
        guard let loc = locations.last else { return }
        control.send(.location(lat: loc.coordinate.latitude,
                               lon: loc.coordinate.longitude))
    }
}

```

## Internal Project Targets

Beyond external packages, `vphone-cli` organizes functionality into two major internal Swift Package Manager targets:

- **FirmwarePatcher**: Encapsulates all firmware-level patching logic, aggregating Capstone, Img4tool, and MachOKit functionality into reusable patching pipelines.
- **VPhoneCore**: Acts as the core VM abstraction layer, driving Virtualization.framework configuration and runtime orchestration between the CLI interface and the underlying hypervisor.

## Python Dependencies for Auxiliary Scripts

The [[`requirements.txt`](https://github.com/Lakr233/vphone-cli/blob/main/requirements.txt)](https://github.com/Lakr233/vphone-cli/blob/main/requirements.txt) file lists Python packages used by helper scripts such as [[`scripts/setup_machine.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_machine.sh)](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_machine.sh) and firmware preparation utilities:

- **capstone**: Python bindings for the Capstone disassembly engine, enabling script-based firmware analysis without compiling Swift code.
- **keystone-engine**: Assembler library used to generate replacement machine instructions for the Python-based patcher workflow.
- **pyimg4**: Handles IMG4 format parsing and manipulation in Python scripts like [`fw_prepare.sh`](https://github.com/Lakr233/vphone-cli/blob/main/fw_prepare.sh) and [`fw_manifest.py`](https://github.com/Lakr233/vphone-cli/blob/main/fw_manifest.py).

These dependencies ensure the toolchain runs correctly on both Linux and macOS host machines during firmware preparation phases.

## Summary

The key dependencies of vphone-cli work together to provide a complete virtual iPhone environment:

- **swift-argument-parser** handles CLI interface definitions with type-safe argument validation.
- **Dynamic** enables access to private Apple APIs required for advanced Virtualization framework features.
- **Capstone, Img4tool, and MachOKit** provide the binary manipulation capabilities necessary for firmware patching and IPA resigning.
- **Apple's Virtualization framework** powers the actual VM execution, while **AppKit**, **SwiftUI**, and **AVFoundation** handle user interface and media routing.
- **Python libraries** (`capstone`, `keystone-engine`, `pyimg4`) support auxiliary scripts that prepare firmware images before boot.

## Frequently Asked Questions

### What is the minimum macOS version required for vphone-cli dependencies?

**vphone-cli** requires macOS 12.0 or later to support the Virtualization framework features used in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift). The Swift package dependencies generally require Swift 5.5 or newer, and the Python scripts require Python 3.8+ to support the `pyimg4` library functionality.

### Why does vphone-cli need both Swift and Python Capstone libraries?

The project uses **libcapstone-spm** for the main Swift-based firmware patcher that runs within the application, while the **Python `capstone` package** supports auxiliary scripts in the `scripts/` directory that run during build or setup phases. This dual-language approach allows firmware analysis tools to run on Linux build servers while the main application targets macOS virtualization.

### How does the Dynamic package differ from standard Swift interop?

**Dynamic** specifically targets private Objective-C runtime functions that lack public headers, allowing `vphone-cli` to invoke undocumented Virtualization framework methods without linking against restricted Apple APIs at compile time. Standard Swift interop requires public headers and compile-time linking, whereas Dynamic resolves symbols at runtime to avoid App Store review issues and maintain compatibility across macOS versions.

### Where are the Python dependencies installed during setup?

The [[`scripts/setup_machine.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_machine.sh)](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_machine.sh) script installs Python dependencies listed in [[`requirements.txt`](https://github.com/Lakr233/vphone-cli/blob/main/requirements.txt)](https://github.com/Lakr233/vphone-cli/blob/main/requirements.txt) into the system Python environment or a virtual environment, ensuring `capstone`, `keystone-engine`, and `pyimg4` are available for the firmware preparation toolchain before the Swift executable builds.