arcbox_vz/
lib.rs

1//! Safe Rust bindings for Apple's Virtualization.framework.
2//!
3//! This crate provides ergonomic, async-first bindings to Apple's Virtualization.framework,
4//! allowing you to create and manage virtual machines on macOS. All framework
5//! interaction happens in the bundled ArcBoxVZShim Swift static library
6//! (`shim/`), reached through the hand-written C ABI in `shim_ffi.rs` — see
7//! that file's header for the boundary conventions.
8//!
9//! # Features
10//!
11//! - **Safe API**: Minimize unsafe code exposure with safe Rust abstractions
12//! - **Async-first**: Native async/await support for all asynchronous operations
13//!
14//! # Example
15//!
16//! ```rust,no_run
17//! use arcbox_vz::{
18//!     VirtualMachineConfiguration, LinuxBootLoader, GenericPlatform,
19//!     SocketDeviceConfiguration, VZError,
20//! };
21//!
22//! #[tokio::main]
23//! async fn main() -> Result<(), VZError> {
24//!     let mut config = VirtualMachineConfiguration::new()?;
25//!     config
26//!         .set_cpu_count(2)
27//!         .set_memory_size(512 * 1024 * 1024);
28//!
29//!     let boot_loader = LinuxBootLoader::new("/path/to/kernel")?;
30//!     config.set_boot_loader(boot_loader);
31//!
32//!     let vm = config.build()?;
33//!     vm.start().await?;
34//!
35//!     Ok(())
36//! }
37//! ```
38//!
39//! # Platform Support
40//!
41//! This crate only supports macOS 11.0 (Big Sur) and later. Attempting to compile
42//! on other platforms will result in a compilation error.
43//!
44//! # Entitlements
45//!
46//! Your application must have the `com.apple.security.virtualization` entitlement
47//! to use this framework. See Apple's documentation for details.
48
49#![cfg(target_os = "macos")]
50#![warn(missing_docs)]
51
52pub mod error;
53mod shim_ffi;
54
55pub mod configuration;
56pub mod device;
57pub mod restore;
58pub mod socket;
59pub mod vm;
60
61// Re-exports for convenience
62pub use error::VZError;
63
64pub use configuration::{
65    GenericPlatform, LinuxBootLoader, MacAuxiliaryStorage, MacHardwareModel, MacMachineIdentifier,
66    MacOSBootLoader, MacPlatform, Platform, VirtualMachineConfiguration,
67};
68
69pub use device::{
70    DirectoryShare, EntropyDeviceConfiguration, LinuxRosettaDirectoryShare,
71    MacGraphicsDeviceConfiguration, MemoryBalloonDevice, MemoryBalloonDeviceConfiguration,
72    NetworkDeviceConfiguration, RosettaAvailability, SerialPortConfiguration, SharedDirectory,
73    SingleDirectoryShare, SocketDeviceConfiguration, StorageDeviceConfiguration,
74    VirtioFileSystemDeviceConfiguration, desired_network_mtu,
75};
76
77pub use socket::{VirtioSocketConnection, VirtioSocketDevice};
78
79pub use restore::{MacOSConfigurationRequirements, MacOSInstaller, MacOSRestoreImage};
80
81pub use vm::{VirtualMachine, VirtualMachineState};
82
83/// Check if virtualization is supported on this system.
84///
85/// Returns `true` if the Virtualization.framework is available and the
86/// hardware supports virtualization.
87#[must_use]
88pub fn is_supported() -> bool {
89    // SAFETY: shim reads a class property; no preconditions.
90    unsafe { shim_ffi::abx_vz_supported() }
91}
92
93/// Get the minimum allowed CPU count for a virtual machine.
94#[must_use]
95pub fn min_cpu_count() -> u64 {
96    // SAFETY: shim reads a class property; no preconditions.
97    unsafe { shim_ffi::abx_vz_min_cpu_count() }
98}
99
100/// Get the maximum allowed CPU count for a virtual machine.
101#[must_use]
102pub fn max_cpu_count() -> u64 {
103    // SAFETY: shim reads a class property; no preconditions.
104    unsafe { shim_ffi::abx_vz_max_cpu_count() }
105}
106
107/// Get the minimum allowed memory size for a virtual machine (in bytes).
108#[must_use]
109pub fn min_memory_size() -> u64 {
110    // SAFETY: shim reads a class property; no preconditions.
111    unsafe { shim_ffi::abx_vz_min_memory_size() }
112}
113
114/// Get the maximum allowed memory size for a virtual machine (in bytes).
115#[must_use]
116pub fn max_memory_size() -> u64 {
117    // SAFETY: shim reads a class property; no preconditions.
118    unsafe { shim_ffi::abx_vz_max_memory_size() }
119}
arcbox_vz/lib.rs

arcbox_vz/
lib.rs
