Add macOS Tart VM build documentation

.cirrus.yml

@@ -0,0 +1,70 @@
+task:
+  name: macOS PCP Build
+  macos_instance:
+    image: ghcr.io/cirruslabs/macos-tahoe-base:latest
+  # Cache Homebrew prefix + download cache
+  homebrew_cache:
+    folder: /opt/homebrew
+    # Also cache downloaded bottles to avoid re-downloading on cache miss/rebuild
+    # (you can list multiple folders)
+    # folders:
+    #   - /opt/homebrew
+    #   - ~/Library/Caches/Homebrew
+    fingerprint_script: |
+      brew --version
+      echo $HOMEBREW_NO_AUTO_UPDATE  # if you use it
+      brew list --versions | sort    # list installed formulae & versions
+    populate_script: |
+      # This runs only on cache miss — safe to install everything here
+      echo "Populating Homebrew cache..."
+      # Homebrew is already in base images, but we can ensure update if needed
+      brew update --quiet || true
+      brew install coreutils gnu-tar pkg-config python3 python-setuptools autoconf || true  # idempotent
+    # Optional: clean up non-deterministic files before cache upload
+    before_cache_script: |
+      brew cleanup --prune=all || true
+      rm -rf ~/Library/Caches/Homebrew/downloads  # optional, if too noisy
+  #brew_setup_script:
+    # Now this will be very fast if cache hit
+    #- echo "Setting up dependencies (cached!)"
+#    - brew install coreutils gnu-tar pkg-config python3 python-setuptools autoconf || true  # idempotent
+  pcp_build_script: |
+     [ "$PCP_SKIP_BUILD" == "true" ] && echo "SKIPPING BUILD" || ./Makepkgs --verbose
+  pcp_install_script: |
+     DMG_PATH=$(find pcp-**/build/mac -name "pcp-*.dmg" | head -1) # Find the generated DMG
+     echo "Found DMG: $DMG_PATH"
+     MOUNT_OUTPUT=$(hdiutil attach "$DMG_PATH" | tail -1) # Mount the DMG
+     VOLUME_PATH=$(echo "$MOUNT_OUTPUT" | awk '{print $3}')
+     echo "Mounted at: $VOLUME_PATH"
+     PKG_PATH=$(find "$VOLUME_PATH" -name "*.pkg" | head -1) # Find and install the PKG
+     echo "Found PKG: $PKG_PATH"
+     ls -alh $PKG_PATH
+     pkgutil --check-signature $PKG_PATH || true # this returns 1 when things are ok
+     sudo installer -pkg "$PKG_PATH" -target / -verbose # Install (sudo is passwordless in GitHub Actions)
+  check_pmcd_is_running_postinstall_script: |
+    echo "Waiting for pcp service to start (it can take a while after install)..."
+    TIMEOUT=180  # 3 minutes
+    ELAPSED=0
+    INTERVAL=5
+
+    while [ $ELAPSED -lt $TIMEOUT ]; do
+      if pcp 2>/dev/null; then
+        echo "pcp service is responding"
+        break
+      fi
+      sleep $INTERVAL
+      ELAPSED=$((ELAPSED + INTERVAL))
+    done
+
+    if [ $ELAPSED -ge $TIMEOUT ]; then
+      echo "ERROR: pcp service failed to start within $TIMEOUT seconds"
+      exit 1
+    fi
+  pause_script: |
+    if [ "$PCP_PAUSE_AFTER_INSTALL" == "true" ]; then
+      echo "VM IP: $(ipconfig getifaddr en0)"
+      sleep 3600  # Keeps VM alive for an hour
+    else
+      echo "No pause required, finishing"
+    fi
+

CONTRIBUTING.md

@@ -167,3 +167,10 @@ keep the differences minimal in order to ease future updates of vendored code.
 
 **All bugs and CVEs of a vendored library in turn become responsibilities of the
 PCP maintainers as well** (and fixes must be pushed upstream).
+
+## Platform-Specific Development
+
+### macOS with Tart VMs
+
+macOS developers can build in isolated VMs for clean, reproducible builds that match the CI environment. See [MACOS_DEVELOPMENT.md](MACOS_DEVELOPMENT.md) for details.
+

INSTALL.md

@@ -204,11 +204,14 @@ optional" or "QA optional".
 The pcp package uses autoconf/configure and expects a GNU build
 environment (your platform must at least have gmake).
 
+#### macOS-specific pre-requisites 
 ```
-# MacOS - use Homebrew and ensure the following packages are installed 
+# use Homebrew and ensure the following packages are installed 
 brew install gnu-tar pkg-config python3 python-setuptools autoconf
 ```
 
+To build from source using isolated VMs, see [MACOS_DEVELOPMENT.md](MACOS_DEVELOPMENT.md).
+
 ---
 
 ### 2. Building PCP binaries

MACOS_DEVELOPMENT.md

@@ -0,0 +1,85 @@
+# macOS Development with Tart VMs
+
+## 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
+
+Install Tart and Cirrus CLI:
+
+```bash
+brew install cirruslabs/cli/tart cirruslabs/cli/cirrus
+```
+
+## Basic Usage
+
+Build PCP in a fresh VM:
+
+```bash
+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):
+
+```bash
+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!):
+
+```bash
+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:
+
+```bash
+cirrus run --dirty -e PCP_PAUSE_AFTER_INSTALL=true
+```
+
+The build log will show the VM IP address. Connect with:
+
+```bash
+ssh admin@<ip-address>  # Password: admin
+```
+
+The VM stays alive for up to 1 hour. Press `CTRL-C` to terminate when finished.
+
+## 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](.cirrus.yml) for implementation details.
+
+## Documentation
+
+- [Tart Virtualization](https://tart.run/) - Official documentation
+- [Tart on GitHub](https://github.com/cirruslabs/tart) - Source and issues
+- [Tart Quick Start](https://tart.run/quick-start/) - Getting started
+- [Cirrus CLI Integration](https://tart.run/integrations/cirrus-cli/) - How Cirrus CLI works with Tart

build/mac/build-installer

@@ -49,8 +49,8 @@ _do()
 
 _run()
 {
-    echo $*
-    eval $*
+    echo "$@"
+    "$@"
 }
 
 echo "Verifying IDB file is valid"
@@ -96,8 +96,22 @@ pkgroot=`mktemp -d /tmp/macos-pkg.XXXXXXXXX`
 cp -RP installer-files/* $pkgroot/
 cp -RP installer-resources/* $pkgroot/
 
+# WORKAROUND: Write package to /tmp first to avoid virtiofs XAR corruption
+# then copy to final location in build directory
+# without this, the pkgbuild produces a corrupted archive inside a Tart VM
+pkgout="/tmp/pcp-pkg.$$"
+
 # pkgbuild must be run by the user logged into the localhost desktop.
-_run $PKGBUILD --identifier io.pcp.performancecopilot --version $PACKAGE_VERSION --nopayload --scripts $pkgroot $HERE/$PKG
+_run "$PKGBUILD" --identifier io.pcp.performancecopilot --version "$PACKAGE_VERSION" --nopayload --scripts "$pkgroot" "$pkgout"
+
+if [ ! -s "$pkgout" ]
+then
+    echo "$prog: Package generation failed"
+    exit 1
+fi
+
+# Copy package from /tmp to build directory
+cp "$pkgout" "$HERE/$PKG"
 
 if [ ! -s $HERE/$PKG ]
 then
@@ -111,6 +125,9 @@ _do rm -rf $DMG $TEMPDMG $PACKAGE
 _do mkdir $PACKAGE
 _do mv $PKG $PACKAGE
 
+# Clean up temporary files
+rm -rf "$pkgroot" "$pkgout"
+
 _do $HDIUTIL makehybrid -quiet -o $PACKAGE.tmp $PACKAGE \
 	-hfs-openfolder dmg.tmp/$DMG -hfs
 _do $HDIUTIL convert -quiet $TEMPDMG -format UDRO -o $DMG