# Build Targets in the vphone-cli Makefile: Complete Developer Reference

> Explore vphone-cli Makefile build targets for VM management, firmware patching, testing, and CFW installation. Master your virtual iPhone workflow with this developer reference.

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

---

**The vphone-cli Makefile defines over 30 `.PHONY` targets across nine functional categories—including setup, compilation, VM management, firmware patching, boot operations, testing, and CFW installation—that orchestrate the entire virtual iPhone workflow from environment initialization to custom firmware deployment.**

The `Makefile` at the root of the [Lakr233/vphone-cli](https://github.com/Lakr233/vphone-cli) repository serves as the single entry point for the virtual iPhone toolchain. This declarative build system implements every high-level operation through specific rules, enabling developers to compile Swift host binaries, manage virtual machine lifecycles, patch IPSW firmware, and deploy custom iOS variants using standard `make` commands.

## Setup and Environment Targets

The environment initialization targets prepare the host machine and install external dependencies required by the rest of the pipeline.

- **`help`**: Prints usage information for all public targets.
- **`setup_machine`**: Performs first-time environment preparation, including creating the `VM_DIR` directory structure and downloading base IPSW files. Accepts boolean flags to enable specific build modes: `JB=1` (jailbreak), `DEV=1` (development), `EXP=1` (experimental), or `LESS=1` (security-preserving minimal mode).
- **`setup_tools`**: Installs all required external tools and dependencies needed for compilation and patching.

```bash

# Initialize environment with jailbreak support enabled

make setup_machine JB=1

# Install external dependencies

make setup_tools

```

## Build and Compilation Targets

These targets compile the Swift-based host tools and the guest daemon using the Swift Package Manager manifest at [`Package.swift`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift) and the auxiliary Makefile at `scripts/vphoned/Makefile`.

- **`build`**: Compiles the main `vphone-cli` Swift binary.
- **`patcher_build`**: Compiles the standalone patcher binary (`$(PATCHER_BINARY)`) used for firmware modification.
- **`bundle`**: Produces a signed macOS application bundle by adding entitlements, icons, and helper tools to the compiled binary.
- **`vphoned`**: Cross-compiles the guest daemon (`vphoned`) that runs inside the virtual machine.

```bash

# Fast debug build of the host binary

make build

# Compile the firmware patcher

make patcher_build

# Create signed .app bundle

make bundle

# Build the guest daemon

make vphoned

```

## Firmware Patching Pipeline

The firmware pipeline downloads official IPSWs and applies custom patches to create bootable custom firmware (CFW) variants.

- **`fw_prepare`**: Downloads and merges IPSW files from Apple’s servers into the local cache.
- **`fw_patch`**: Applies the standard patch set to the prepared firmware.
- **`fw_patch_less`**: Applies a minimal patch set that preserves more security boundaries; **requires `sudo`** because it modifies protected system paths.
- **`fw_patch_dev`**: Applies patches for development workflows.
- **`fw_patch_jb`**: Applies jailbreak-specific kernel patches.
- **`fw_patch_exp`**: Applies experimental patches not yet stabilized.

Each variant invokes the patcher binary with a specific `--variant` flag (e.g., `--variant less`, `--variant jb`).

```bash

# Download and prepare IPSWs

make fw_prepare

# Apply standard patches

make fw_patch

# Apply minimal patches (requires elevated privileges)

sudo make fw_patch_less

```

## VM Lifecycle Management Targets

These targets manage the virtual machine directory (`VM_DIR`) and its `config.plist` configuration file.

- **`vm_new`**: Creates a fresh VM with default resource allocations.
- **`vm_backup`**: Creates a timestamped backup of the current VM state.
- **`vm_restore`**: Restores the VM from a specified backup.
- **`vm_switch`**: Performs a quick switch between two VM snapshots without full restoration.
- **`vm_list`**: Displays existing backups and their metadata.

```bash

# Create a new virtual machine

make vm_new

# Backup current state before patching

make vm_backup

# List available backups

make vm_list

```

## Boot and Runtime Targets

Boot targets launch the virtualized environment with varying levels of instrumentation and security bypasses.

- **`boot`**: Starts the VM using the bundled binary and launches the `vphoned` guest daemon for full functionality.
- **`boot_less`**: Boots the VM without the `vphoned` daemon for a minimal environment.
- **`boot_dfu`**: Boots the VM into DFU (Device Firmware Update) mode for low-level restoration.
- **`boot_host_preflight`**: Executes pre-flight checks on the host system before booting.
- **`boot_binary_check`**: Verifies the integrity of the boot binary and its entitlements.
- **`amfidont_allow_vphone`**: Applies a temporary AMFI (Apple Mobile File Integrity) bypass to allow the unsigned vphone binary to execute.

```bash

# Normal boot with full daemon support

make boot

# Minimal boot without guest daemon

make boot_less

# Boot into DFU mode

make boot_dfu

```

## Testing and Validation Targets

These targets execute automated validation suites suitable for continuous integration pipelines.

- **`test_jb_patches`**: Runs the full jailbreak kernel-patch suite to verify patch application correctness.
- **`test_fw_patches`**: Executes end-to-end firmware-patch pipeline testing, verifying that IPSW modification produces valid boot chains.

```bash

# Verify kernel patches

make test_jb_patches

# Full pipeline integration test

make test_fw_patches

```

## Restore Targets

Restore targets handle device restoration and SHSH blob management for downgrades.

- **`restore_get_shsh`**: Retrieves and caches SHSH blobs required for signed restores.
- **`restore`**: Performs an online restore using Apple’s signing servers.
- **`restore_offline`**: Performs an offline restore using locally cached SHSH blobs.

## CFW Installation Targets

These shell-script-backed targets install prepared custom firmware onto a **powered-off** VM.

- **`cfw_install`**: Installs the base custom firmware without extensions.
- **`cfw_install_dev`**: Installs base CFW plus development tool extensions.
- **`cfw_install_jb`**: Installs base CFW plus jailbreak extensions.
- **`cfw_install_exp`**: Installs base CFW plus experimental patches.
- **`cfw_install_host`**: Installs CFW using a host-mount method; **requires `sudo`** because it mounts the VM disk image directly.

```bash

# Install jailbreak-enabled CFW

make cfw_install_jb

# Install via host mount (requires sudo)

sudo make cfw_install_host

```

## Cleanup Targets

- **`clean`**: Removes build artifacts, temporary tooling directories, and optionally wipes the `VM_DIR` or IPSW cache depending on environment variables provided.

## Summary

- The **Lakr233/vphone-cli** `Makefile` implements a complete toolchain workflow through **`.PHONY`** targets defined in the root `Makefile`.
- **Setup targets** (`setup_machine`, `setup_tools`) initialize the environment with optional flags (`JB=1`, `LESS=1`) that configure subsequent build behavior.
- **Build targets** (`build`, `patcher_build`, `bundle`, `vphoned`) compile host tools, the patcher utility, and the guest daemon using Swift Package Manager and auxiliary Makefiles.
- **Firmware targets** (`fw_prepare`, `fw_patch*`) download IPSWs and apply variant-specific patches via the `$(PATCHER_BINARY)` with `--variant` flags.
- **VM targets** (`vm_new`, `vm_backup`, `boot`, `boot_less`) manage the `VM_DIR` lifecycle and control whether the `vphoned` daemon runs.
- **Installation targets** (`cfw_install*`) deploy custom firmware to powered-off VMs, with `cfw_install_host` requiring `sudo` for disk mounting.
- **Test targets** (`test_jb_patches`, `test_fw_patches`) provide automated validation of kernel and firmware modifications.

## Frequently Asked Questions

### What is the difference between `build` and `patcher_build`?

The `build` target compiles the main `vphone-cli` Swift binary defined in [`Package.swift`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift), while `patcher_build` specifically compiles the standalone firmware patcher binary (`$(PATCHER_BINARY)`) used to modify IPSW files. You typically run `build` for day-to-day development and `patcher_build` when preparing to modify firmware.

### Why does `fw_patch_less` require sudo privileges?

The `fw_patch_less` target applies a minimal patch set that preserves security boundaries but requires direct modification of protected system paths and raw disk operations. The Makefile includes a UID check to ensure `sudo` is used, preventing permission errors during the patching process.

### When should I use `boot_less` instead of the standard `boot` target?

Use `boot_less` when you need a minimal VM environment without the `vphoned` guest daemon, typically for debugging low-level startup issues or when running processes that conflict with the daemon’s virtualization hooks. The standard `boot` target should be used for normal operation when full guest-host communication is required.

### How do the CFW installation targets differ from each other?

The base `cfw_install` target installs standard custom firmware, while `cfw_install_dev`, `cfw_install_jb`, and `cfw_install_exp` layer additional development tools, jailbreak patches, or experimental features on top of the base image. The `cfw_install_host` variant operates differently by mounting the VM disk on the host filesystem using `sudo`, rather than using guest-side installation methods.