[applevz] Basic vm functionality

[sharder996]

This PR implement the creation of virtual machines as well as some of the basic functions for manipulating the state of a virtual machine using the Apple Virtualization Framework. This includes:

• start()
• shutdown(ShutdownPolicy shutdown_policy)
• suspend() to memory for now

All Objective-C++ code, other helper functions needed to perform these actions, and unit tests for these functions are also included.

On top of being able to manually manage memory, Objective-C uses Automatic Reference Counting (ARC) where the system reference counting to automatically insert appropriate memory management method calls for you at compile-time. However, in order for objects to persist across the Objective-C/C++ boundary, we must use some types from the CoreFoundation library instead of the Foundation library, i.e., CFErrorRef over NSError, also known as Toll-Free Bridged Types. This allows us to control who owns the object and avoids having ARC and the Objective-C memory management system release memory before we are done with it. There are several macros that are used to tell the compiler about the ownership semantics of an object, but we mainly use:

• __bridge; for objects such as the VMHandle which were declared on the C++ side and where we don't want ownership to transfer when casting the std::shared_ptr<void> to virtualization framework virtual machine type; VZVirtualMachine.

• __bridge_retained: for objects that were created on the Objective-C side and for which we want to persist even after the block in which they were created finishes. We are responsible for manually freeing this type of object, so care must be taken in order when using this macro to prevent memory leaks. The use of this macro here is limited to returning errors from the Objective-C side to the C++ side through the use of the custom C++ type; CFError, which automatically calls CFRelease when destructed.

The other unique memory management mechanism that is used is the autoreleasepool block. This is used in special circumstances when a large number of temporary autoreleased object. The autoreleasepool sends an autorelease message to all objects in that block which are immediately released instead of at the end of the current event-loop iteration. This prevents temporary objects from unnecessarily accumulating and causing excessive overhead.

Additional reading:

• Toll-Free Bridged Types
• Core Foundation Memory Management
• About Memory Management

---

MULTI-2258
MULTI-2260
MULTI-2261
MULTI-2266
MULTI-2267
MULTI-2268

[codecov]

Codecov Report

❌ Patch coverage is 95.23810% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 87.65%. Comparing base (39060a7) to head (9be4d92).
⚠️ Report is 9 commits behind head on main.

Files with missing lines	Patch %	Lines
src/client/cli/cmd/launch.cpp	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4653      +/-   ##
==========================================
+ Coverage   87.64%   87.65%   +0.02%     
==========================================
  Files         254      254              
  Lines       14158    14170      +12     
==========================================
+ Hits        12408    12420      +12     
  Misses       1750     1750              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR implements basic virtual machine functionality for the AppleVZ backend using the Apple Virtualization Framework. It enables creation, starting, stopping, and suspending of VMs with proper state management and memory handling across the Objective-C++/C++ boundary.

Changes:

• Implemented core VM lifecycle operations (start, shutdown, suspend) and state management for AppleVZ
• Added Objective-C++ bridge code with proper memory management using CFError and toll-free bridged types
• Extended qemu-img utilities to support raw image format conversion and format detection for resize operations

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/platform/backends/applevz/applevz_virtual_machine.cpp	Core VM implementation with lifecycle management and state transitions
src/platform/backends/applevz/applevz_bridge.mm	Objective-C++ bridge providing VM operations interface to C++ code
src/platform/backends/applevz/cf_error.h	Custom CFError wrapper with RAII semantics for memory management
src/platform/backends/applevz/applevz_wrapper.cpp	C++ wrapper layer delegating to bridge functions
src/platform/backends/qemu/qemu_img_utils.cpp	Added raw conversion and image format detection capabilities
tests/unit/applevz/test_applevz_virtual_machine.cpp	Comprehensive unit tests for VM state transitions and operations
tests/unit/qemu/test_qemu_img_utils.cpp	Updated tests for resize with format detection and raw conversion
include/multipass/virtual_machine.h	Added fmt formatter for VM state enum

Comments suppressed due to low confidence (1)

src/platform/backends/applevz/applevz_bridge.mm:1

• The log message uses '>' instead of the expected '->' used in other log messages in this file. This should be '->>' for consistency with the logging pattern used elsewhere.

/*

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.