Why vphone-cli Requires `make build` Instead of Raw `swift build`

Every vphone‑cli binary must be built with make build because the tool requires private Apple entitlements and code signing that Swift Package Manager does not perform, causing unsigned binaries to fail at runtime when launching the iOS VM.

The Lakr233/vphone-cli repository leverages low-level virtualization APIs that are inaccessible to standard Swift binaries. While most Swift projects compile with a simple swift build, this codebase explicitly prohibits that workflow to ensure every executable carries the cryptographic signatures and private entitlements required by the Virtualization.framework.

The Private Entitlement Requirement

The vphone‑cli tool utilizes PV=3 virtualization, an internal Apple privilege level that grants direct access to hardware-assisted virtualization features. To obtain these privileges, the binary must be signed with specific entitlements defined in sources/vphone.entitlements that are not applied by default SwiftPM builds.

According to AGENTS.md in the repository root:

"Always use make build — never swift build alone, as the unsigned binary will fail at runtime."

These entitlements act as a kernel-level gatekeeper. Without them, macOS explicitly denies the virtualization requests necessary to boot the iOS environment.

Build Process Comparison

Running swift build produces an unsigned executable in .build/debug/vphone-cli. This binary lacks the embedded entitlements and cryptographic signature that the Virtualization.framework validates before granting PV=3 access, resulting in immediate runtime termination.

The make build target orchestrates a three-phase pipeline:

1. Compilation – Invokes SwiftPM to generate the raw executable from Package.swift
2. Entitlement binding – Applies the private entitlements from sources/vphone.entitlements to the binary
3. Code signing – Cryptographically signs the executable with a developer certificate, embedding the entitlements into the signature

This ensures the resulting binary satisfies all security requirements imposed by the kernel extension and virtualization subsystem.

Runtime Consequences of Unsigned Binaries

Attempting to execute an unsigned binary triggers explicit errors from the operating system. The Virtualization.framework checks for the presence of required entitlements before allocating VM resources, and unsigned builds fail this validation.

# Incorrect approach – produces an unsigned binary

$ swift build
$ .build/debug/vphone-cli
Error: The binary is not signed with the required entitlements.

# Correct approach – compiles and signs in one step

$ make build

# Output: signed binary ready for virtualization

$ ./vphone-cli

# VM launches with full PV=3 privileges

The Makefile handles the specific codesign flags and certificate selection required to satisfy Apple's security policy, preventing the "unsigned binary" errors that occur when manually invoking swift build.

Summary

• PV=3 virtualization requires private entitlements stored in sources/vphone.entitlements
• swift build generates unsigned binaries that macOS rejects for virtualization tasks
• make build performs compilation, entitlement application, and cryptographic signing as an atomic operation
• Skipping the Makefile bypasses mandatory security checks, causing runtime failures when launching iOS VMs

Frequently Asked Questions

What are private entitlements in vphone-cli?

Private entitlements are specialized permissions defined in sources/vphone.entitlements that authorize the binary to access Apple's Virtualization.framework with PV=3 privileges. These entitlements are restricted by Apple and require proper code signing to be recognized by the macOS kernel during VM initialization.

Can I manually sign the binary after running swift build?

While manual signing using the codesign utility is technically possible, the Makefile encodes specific flags, certificate identities, and entitlement mappings that ensure compatibility with the Virtualization.framework. Bypassing make build risks using incorrect signing parameters that the kernel will reject.

Where is the signing logic defined?

The build and signing orchestration resides in the Makefile at the repository root. This file defines the build target that chains Swift compilation with the entitlement injection and signing steps required to produce a runnable binary.

Does this affect release builds only?

No. Both debug and release configurations require proper entitlements and signatures. The make build target handles the necessary signing regardless of optimization level, ensuring that every binary—whether for development or production—can successfully initialize the virtualization environment.

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