msb_krun/lib.rs
1//! msb_krun - Native Rust API for libkrun microVMs.
2//!
3//! This crate provides a builder-pattern API for creating and entering microVMs
4//! using libkrun's VMM infrastructure.
5//!
6//! # Lifecycle
7//!
8//! [`Vm::enter()`] never returns on success. When the guest shuts down, the
9//! VMM calls `_exit()`, killing the entire process. `enter()` only returns
10//! `Err` if something fails before the VMM takes over.
11//!
12//! # Example
13//!
14//! ```rust,no_run
15//! use msb_krun::{VmBuilder, Result};
16//!
17//! fn main() -> Result<()> {
18//! VmBuilder::new()
19//! .machine(|m| m.vcpus(4).memory_mib(2048))
20//! .fs(|fs| fs.root("/path/to/rootfs"))
21//! .exec(|e| e.path("/bin/myapp").args(["--flag"]).env("HOME", "/root"))
22//! .build()?
23//! .enter()?;
24//!
25//! unreachable!()
26//! }
27//! ```
28
29//--------------------------------------------------------------------------------------------------
30// Modules
31//--------------------------------------------------------------------------------------------------
32
33pub mod api;
34pub mod backends;
35
36//--------------------------------------------------------------------------------------------------
37// Re-Exports
38//--------------------------------------------------------------------------------------------------
39
40pub use api::builder::VmBuilder;
41#[cfg(feature = "blk")]
42pub use api::builders::CacheMode;
43#[cfg(feature = "blk")]
44pub use api::builders::DiskBuilder;
45#[cfg(feature = "blk")]
46pub use api::builders::DiskImageFormat;
47pub use api::builders::FsBuilder;
48#[cfg(feature = "net")]
49pub use api::builders::NetBuilder;
50#[cfg(feature = "blk")]
51pub use api::builders::SyncMode;
52pub use api::builders::{ConsoleBuilder, ExecBuilder, KernelBuilder, MachineBuilder};
53pub use api::error::{BuildError, ConfigError, Error, Result, RuntimeError};
54pub use api::exit_handle::ExitHandle;
55pub use api::metrics::{
56 BlockDeviceMetrics, BlockMetrics, CpuMetrics, FilesystemMetrics, MemoryMetrics, MetricsHandle,
57 VmMetrics,
58};
59pub use api::vm::Vm;
60#[cfg(not(feature = "tee"))]
61pub use api::vm::{VmControl, VmCpuState, VmMemoryState};
62
63#[cfg(not(target_os = "windows"))]
64pub use backends::console::ConsolePortBackend;
65
66#[cfg(not(any(feature = "tee", feature = "aws-nitro")))]
67pub use backends::fs::DynFileSystem;
68
69#[cfg(feature = "net")]
70pub use backends::net::NetBackend;