arcbox-vz 0.4.18

//! Safe Rust bindings for Apple's Virtualization.framework.
//!
//! This crate provides ergonomic, async-first bindings to Apple's Virtualization.framework,
//! allowing you to create and manage virtual machines on macOS.
//!
//! # Features
//!
//! - **Safe API**: Minimize unsafe code exposure with safe Rust abstractions
//! - **Async-first**: Native async/await support for all asynchronous operations
//! - **Complete Coverage**: Support all Virtualization.framework features (macOS 11+)
//!
//! # Example
//!
//! ```rust,no_run
//! use arcbox_vz::{
//!     VirtualMachineConfiguration, LinuxBootLoader, GenericPlatform,
//!     SocketDeviceConfiguration, VZError,
//! };
//!
//! #[tokio::main]
//! async fn main() -> Result<(), VZError> {
//!     let mut config = VirtualMachineConfiguration::new()?;
//!     config
//!         .set_cpu_count(2)
//!         .set_memory_size(512 * 1024 * 1024);
//!
//!     let boot_loader = LinuxBootLoader::new("/path/to/kernel")?;
//!     config.set_boot_loader(boot_loader);
//!
//!     let vm = config.build()?;
//!     vm.start().await?;
//!
//!     Ok(())
//! }
//! ```
//!
//! # Platform Support
//!
//! This crate only supports macOS 11.0 (Big Sur) and later. Attempting to compile
//! on other platforms will result in a compilation error.
//!
//! # Entitlements
//!
//! Your application must have the `com.apple.security.virtualization` entitlement
//! to use this framework. See Apple's documentation for details.

#![cfg(target_os = "macos")]
#![warn(missing_docs)]
// FFI bindings require extensive pointer casts - these are intentional and safe.
#![allow(clippy::ptr_as_ptr)]
#![allow(clippy::ptr_cast_constness)]
#![allow(clippy::ref_as_ptr)]
#![allow(clippy::borrow_as_ptr)]
#![allow(clippy::unnecessary_cast)]
#![allow(clippy::type_complexity)]
#![allow(clippy::collapsible_if)]
#![allow(clippy::map_unwrap_or)]
// VM operations run on the main thread with ObjC FFI pointers (*const c_void,
// *mut AnyObject) that are inherently not Send. This is by design.
#![allow(clippy::future_not_send)]

pub mod error;
pub mod ffi;

pub mod configuration;
pub(crate) mod delegate;
pub mod device;
pub mod restore;
pub mod socket;
pub mod vm;

// Re-exports for convenience
pub use error::VZError;

pub use configuration::{
    GenericPlatform, LinuxBootLoader, MacAuxiliaryStorage, MacHardwareModel, MacMachineIdentifier,
    MacOSBootLoader, MacPlatform, Platform, VirtualMachineConfiguration,
};

pub use device::{
    DirectoryShare, EntropyDeviceConfiguration, LinuxRosettaDirectoryShare,
    MacGraphicsDeviceConfiguration, MemoryBalloonDevice, MemoryBalloonDeviceConfiguration,
    MultipleDirectoryShare, NetworkDeviceConfiguration, RosettaAvailability,
    SerialPortConfiguration, SharedDirectory, SingleDirectoryShare, SocketDeviceConfiguration,
    StorageDeviceConfiguration, VirtioFileSystemDeviceConfiguration,
};

pub use socket::{VirtioSocketConnection, VirtioSocketDevice, VirtioSocketListener};

pub use restore::{MacOSConfigurationRequirements, MacOSInstaller, MacOSRestoreImage};

pub use vm::{VirtualMachine, VirtualMachineState};

/// Check if virtualization is supported on this system.
///
/// Returns `true` if the Virtualization.framework is available and the
/// hardware supports virtualization.
#[must_use]
pub fn is_supported() -> bool {
    ffi::is_supported()
}

/// Get the minimum allowed CPU count for a virtual machine.
#[must_use]
pub fn min_cpu_count() -> u64 {
    ffi::min_cpu_count()
}

/// Get the maximum allowed CPU count for a virtual machine.
#[must_use]
pub fn max_cpu_count() -> u64 {
    ffi::max_cpu_count()
}

/// Get the minimum allowed memory size for a virtual machine (in bytes).
#[must_use]
pub fn min_memory_size() -> u64 {
    ffi::min_memory_size()
}

/// Get the maximum allowed memory size for a virtual machine (in bytes).
#[must_use]
pub fn max_memory_size() -> u64 {
    ffi::max_memory_size()
}