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;
47#[cfg(feature = "net")]
48pub use api::builders::NetBuilder;
49#[cfg(feature = "blk")]
50pub use api::builders::SyncMode;
51pub use api::builders::{ConsoleBuilder, ExecBuilder, FsBuilder, KernelBuilder, MachineBuilder};
52pub use api::error::{BuildError, ConfigError, Error, Result, RuntimeError};
53pub use api::exit_handle::ExitHandle;
54pub use api::metrics::{
55 BlockDeviceMetrics, BlockMetrics, CpuMetrics, MemoryMetrics, MetricsHandle, VmMetrics,
56};
57pub use api::vm::Vm;
58
59pub use backends::console::ConsolePortBackend;
60
61#[cfg(not(any(feature = "tee", feature = "aws-nitro")))]
62pub use backends::fs::DynFileSystem;
63
64#[cfg(feature = "net")]
65pub use backends::net::NetBackend;