How to Use the Key Make Targets for vphone-cli: Complete Build and VM Management Guide

The vphone-cli Makefile defines 25+ automated targets that handle the full virtual iPhone lifecycle, from host setup and binary compilation to firmware patching, VM booting, and iOS restoration.

This article breaks down every essential make target for vphone-cli based on the actual source code in Lakr233/vphone-cli. Whether you're building the CLI for the first time or managing multiple VM snapshots, these targets eliminate manual steps and ensure reproducible workflows.

---

Setup and Tooling Targets

setup_machine: One-Step Full Environment Setup

The setup_machine target (lines 48–68 in Makefile) performs complete host preparation and first-boot of a virtual iPhone. It accepts optional flags for JB/DEV/EXP/LESS modes and handles sudo password injection automatically.

make setup_machine

setup_tools: Install Host Dependencies

The setup_tools target (lines 70–73) invokes scripts/setup_tools.sh to install:

• Homebrew packages
• trustcache and insert_dylib tools
• Python virtual environment
• pymobiledevice3

make setup_tools

Run this once per development machine before any build or VM operations.

---

Build Targets for vphone-cli Components

build: Compile the Signed CLI Binary

The build target (lines 5–27) compiles the release configuration and embeds the current Git short hash into VPhoneBuildInfo.swift for version tracking.

make build

Source: sources/vphone-cli/Package.swift drives the underlying swift build commands.

bundle: Create macOS App Package

The bundle target (lines 27–37) packages the binary into a signed .app bundle with proper entitlements and resource copying.

vphoned: Cross-Compile the Guest Daemon

The vphoned target (lines 38–51) cross-compiles the iOS arm64 daemon, signs it with ldid, and places it in the VM directory. This daemon enables advanced VM features during boot.

---

VM Lifecycle Management Targets

vm_new: Initialize a Fresh Virtual Machine

Creates $(VM_DIR) with a config.plist specifying 8 CPU cores, 8 GB RAM, and 64 GB disk by default (lines 56–62). Source: scripts/vm_create.sh.

make vm_new

VM Snapshot Targets

Target	Purpose	Line Range
vm_backup	Create named backup	63–68
vm_restore	Restore from named backup	69–72
vm_switch	Swap between backups atomically	73–75
vm_list	Display all stored backups	76–78

Usage example:

make vm_backup NAME=pre-jb-test
make vm_restore NAME=pre-jb-test
make vm_switch NAME=stable-release

---

Firmware and Boot Targets

fw_prepare: Download and Extract IPSWs

Downloads required iOS firmware files and merges cloudOS components into the VM directory (lines 45–51).

Firmware Patch Variants

The fw_patch* family runs the Swift-based patching pipeline through scripts/patchers/cfw.py:

• fw_patch — Standard variant
• fw_patch_less — Minimal compatibility mode
• fw_patch_dev — Developer features enabled
• fw_patch_jb — Jailbreak patches included
• fw_patch_exp — Experimental features

make fw_patch_jb  # Apply jailbreak patches

Boot Targets

Target	Behavior	Lines
boot	Full-featured boot with vphoned	28–33
boot_less	Patch-less mode (no daemon)	34–38
boot_dfu	Direct DFU mode entry	39–42

Use boot_less when the vphoned daemon is omitted or incompatible with your target iOS version.

---

Testing and Validation Targets

Automated Test Suites

• test_jb_patches (lines 82–90): Validate jailbreak kernel patches
• test_fw_patches (lines 91–100): Full firmware-patch pipeline verification

make test_fw_patches  # Run before committing changes

---

iOS Restore Targets

restore_get_shsh: Fetch Signing Tickets

Uses pymobiledevice3 to retrieve SHSH blobs from Apple's servers (lines 104–112).

Restore Operations

Target	Method	Lines
restore	Online restore with live SHSH	113–118
restore_offline	Cached SHSH, no server contact	119–124

Offline restore requires a previously saved blob from restore_get_shsh.

---

Custom Firmware (CFW) Installation Targets

Install host-mount CFW for specific variants:

Target	Description	Lines
cfw_install	Standard CFW	126–130
cfw_install_dev	Developer variant	131
cfw_install_jb	Jailbreak variant	132
cfw_install_exp	Experimental variant	133
cfw_install_host	Underlying sudo driver	134–138

Example workflow:

make fw_patch_jb
make cfw_install_jb
make boot

---

Complete vphone-cli Workflow Example

# 1. Install all host tools (run once)

make setup_tools

# 2. Build and bundle the CLI

make build && make bundle

# 3. Create VM and prepare firmware

make vm_new
make fw_prepare

# 4. Patch and install jailbreak CFW

make fw_patch_jb
make cfw_install_jb

# 5. Boot with full features

make boot

# 6. Create backup before experiments

make vm_backup NAME=jb-working

# 7. Test patches and restore if needed

make test_jb_patches
make vm_restore NAME=jb-working

---

Summary

• vphone-cli make targets consolidate 25+ operations into single commands, from setup_machine (full environment) to granular controls like boot_dfu or cfw_install_exp.
• The Makefile (main build script), scripts/setup_tools.sh (dependency installer), and scripts/patchers/cfw.py (firmware patcher) form the core automation layer.
• VM snapshots (vm_backup, vm_restore, vm_switch) enable safe experimentation with jailbreak and experimental patches.
• All firmware patching and CFW installation support five distinct variants: default, less, dev, jb, and exp.
• Testing targets (test_jb_patches, test_fw_patches) validate changes before deployment to physical or virtual devices.

---

Frequently Asked Questions

What is the difference between boot and boot_less in vphone-cli?

boot launches the VM with the full vphoned daemon, enabling advanced features like host-guest communication and dynamic patching. boot_less (lines 34–38) starts in patch-less compatibility mode using --variant less, which bypasses the daemon entirely—useful when vphoned is incompatible with your target iOS version or when debugging baseline behavior.

How do I create and restore VM backups using make targets?

Run make vm_backup NAME=your-label to snapshot the current VM state to $(VM_DIR)/backups/your-label. Restore with make vm_restore NAME=your-label or atomically switch between backups using make vm_switch NAME=another-label. List all backups with make vm_list. These operations are implemented in Makefile lines 63–78.

Which make target should I run first on a new machine?

Always start with make setup_tools followed by make build. The setup_tools target installs all host dependencies including Python tooling, code signing utilities, and submodules. Once built, make setup_machine can perform complete automated setup including first VM creation and boot if you prefer a single command.

What do the firmware patch variants (jb, dev, exp, less) actually change?

Each fw_patch_* target passes a different --variant flag to scripts/patchers/cfw.py: jb applies jailbreak kernel patches; dev enables developer debugging features; exp activates experimental modifications; less minimizes patches for maximum compatibility. The matching cfw_install_* and boot_* targets must use the same variant for consistent behavior.

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