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

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) 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), the main entry point conforms to ParsableCommand and uses property wrappers like @Option to define CLI flags:

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) to disassemble firmware images, locate specific instructions, and reassemble modified binaries:

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), 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:

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) 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) 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 and 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. 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) script installs Python dependencies listed in [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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}