arcbox-vz 0.4.21

Safe Rust bindings for Apple's Virtualization.framework
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

# arcbox-vz

Safe Rust bindings for Apple's Virtualization.framework, implemented on a
bundled Swift shim.

## Overview

This crate provides ergonomic, async-first bindings to Apple's
Virtualization.framework for creating and managing virtual machines on macOS.
All framework interaction lives in **ArcBoxVZShim**, a SwiftPM static library
under `shim/` that `build.rs` compiles and links into the crate. Rust and
Swift meet at a hand-written C ABI: `shim/Sources/ArcBoxVZShim/Exports.swift`
(`@_cdecl` exports) and `src/shim_ffi.rs` (extern declarations) mirror each
other in a normative symbol order — review them side by side. The shim is
statically linked from this same build, so symbol drift is caught at link
time by the `link_coverage` test rather than a runtime version handshake.

## Requirements

- macOS 13+ (the shim's deployment target)
- Xcode Command Line Tools (`xcode-select --install`) — `build.rs` invokes
  `swift build`
- The `com.apple.security.virtualization` entitlement on any binary that
  creates VMs (configuration objects and capability queries work unsigned)

## Usage

```rust
use arcbox_vz::{LinuxBootLoader, VirtualMachineConfiguration, VZError};

#[tokio::main]
async fn main() -> Result<(), VZError> {
    if !arcbox_vz::is_supported() {
        return Err(VZError::OperationFailed("virtualization unsupported".into()));
    }

    let mut config = VirtualMachineConfiguration::new()?;
    config
        .set_cpu_count(2)
        .set_memory_size(512 * 1024 * 1024);
    config.set_boot_loader(LinuxBootLoader::new("/path/to/kernel")?);

    let vm = config.build()?;
    vm.start().await?;

    vm.request_stop()?;
    Ok(())
}
```

## VM Lifecycle

| Method | Description |
|--------|-------------|
| `start()` | Async start; resolves on the framework's completion |
| `stop()` | Force stop (destructive); resolves on completion |
| `pause()` / `resume()` | Pause / resume; resolve on completion |
| `request_stop()` | Send a graceful shutdown request to the guest |
| `state()` | Query the current `VirtualMachineState` |

## License

MIT OR Apache-2.0