macOS Development with Tart VMs

June 13, 2026 ยท View on GitHub

Overview

Developing PCP on MacOS has some quirks. We provide Tart VM/CirrusLabs CLI configuration to allow an isolated macOS virtual machine for reproducible, clean-room builds that match the CI environment.

Why Tart VMs?

  • macOS cannot be containerized (no Podman support)
  • Lightweight, fast virtualization using native macOS frameworks
  • Eliminates environment differences between developers
  • Matches GitHub Actions CI as close as possible

Prerequisites

Preliminary setup for brew, required brew packages and Python build dependencies (uses uv), see the "macOS-specific pre-requisites" section of ../../INSTALL.md.

Install Tart and Cirrus CLI:

brew install cirruslabs/cli/tart cirruslabs/cli/cirrus

and assuming you're using zsh

rehash

Python Build Dependencies

Only if not done from directions ../../INSTALL.md.

brew install uv
./build/mac/setup-python-env.sh

Basic Usage

Build PCP in a fresh VM (for all cirrus commands, need to cd to the base of the git tree, so ./.cirrus.yml can be found).

cirrus run --dirty

Note: The --dirty flag is required to preserve executable permissions when copying the git tree to the VM.

Useful Options

Simpler Output

Use --output simple to see the complete build log (by default it is very concise):

cirrus run --dirty --output simple

Skip Build (Reuse Existing Package)

If a valid macOS PKG already exists from a previous successful build, skip the build phase (you'll save 5 minutes!):

cirrus run --dirty -e PCP_SKIP_BUILD=true

Useful for testing installation without waiting for a full rebuild.

Debug in VM via SSH

Pause the VM after installation to explore interactively:

cirrus run --dirty -e PCP_PAUSE_AFTER_INSTALL=true

The build log will show the VM IP address. Connect with:

ssh admin@<ip-address>  # Password: admin

The VM stays alive for up to 1 hour. Press CTRL-C to terminate when finished.

Where the package ends up

Like the other platform builds, a successful run will leave an installable package in the build tree below the root of the git tree, e.g. pcp-7.1.6/build/mac/pcp-7.1.6-2.dmg

This can be used with the macOS Installer to install PCP on the build machine.

Understanding .cirrus.yml

The .cirrus.yml file defines the build task:

  • Homebrew cache: Caches /opt/homebrew to speed up subsequent builds
  • Build script: Runs ./Makepkgs --verbose (skipped if PCP_SKIP_BUILD=true)
  • Install script: Mounts the generated DMG and installs the PKG
  • Verification: Waits for pmcd service to start, validates installation
  • Pause script: Optionally pauses VM if PCP_PAUSE_AFTER_INSTALL=true

See .cirrus.yml for implementation details.

Documentation