tatara-vm 0.2.203

Typed VM definitions — Darwin-hosted Linux guests for tatara-os, authored in tatara-lisp, emitted as vfkit/qemu config
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
64
65
66
67
68
69

//! Engine selection — map a `(defvm …)` [`Hypervisor`] to an in-process
//! [`maquina_engine::MaquinaEngine`].
//!
//! Only the Rust-native backends are real engines (zero shell-out): `Libkrun`
//! (`tateru`) and `Kasou` (VZ). `Vfkit` / `VfkitDarwin` / `Qemu` are CLI
//! emitters (the `vfkit` module) with no in-process engine — selecting them
//! here is an error by design (see `theory/MAQUINA.md` § zero-shell-out).
//!
//! The real engines live behind tatara-vm's `engines` feature (macOS), which
//! forwards to `maquina-engine`'s `tateru-backend` + `kasou-backend`. Without
//! that feature (the default build, or any non-macOS target), `engine_for`
//! reports the engine as unavailable so the host-agnostic build of tatara-vm
//! stays dependency-light.

// Gated with the dependency it names. `maquina-engine` is `optional = true`,
// so an unconditional `use` here made the DEFAULT build fail with E0432
// `unresolved import maquina_engine` — the exact opposite of this module's
// stated purpose, which is to keep the featureless build dependency-light.
#[cfg(all(target_os = "macos", feature = "engines"))]
use maquina_engine::MaquinaEngine;

use crate::config::Hypervisor;

/// Why an engine could not be selected for a hypervisor.
#[derive(Debug, thiserror::Error)]
pub enum EngineSelectError {
    /// The hypervisor is a CLI emitter, not an in-process engine.
    #[error(
        "hypervisor {0:?} has no in-process MaquinaEngine (it is a CLI emitter); \
         select Libkrun or Kasou"
    )]
    NoEngine(Hypervisor),
    /// No engine compiled in (engines are macOS-only, behind `--features engines`).
    #[error("no máquina engine available: build tatara-vm with --features engines on macOS")]
    Unavailable,
}

/// Select the in-process [`MaquinaEngine`] for a hypervisor.
///
/// # Errors
/// [`EngineSelectError::NoEngine`] for shell-out hypervisors
/// (`Vfkit`/`VfkitDarwin`/`Qemu`).
#[cfg(all(target_os = "macos", feature = "engines"))]
pub fn engine_for(h: &Hypervisor) -> Result<Box<dyn MaquinaEngine>, EngineSelectError> {
    match h {
        Hypervisor::Libkrun => Ok(Box::new(maquina_engine::tateru_backend::TateruEngine::new())),
        Hypervisor::Kasou => Ok(Box::new(maquina_engine::kasou_backend::KasouEngine::new())),
        other => Err(EngineSelectError::NoEngine(*other)),
    }
}

/// Fallback when no engine backend is compiled in (default build / non-macOS).
///
/// The success type is [`std::convert::Infallible`] rather than
/// `Box<dyn MaquinaEngine>`, and that is the honest signature: without the
/// `engines` feature the `maquina-engine` crate is not linked at all, so there
/// is no engine type to name — and no engine can ever be produced. An
/// uninhabited `Ok` says exactly that at the type level instead of promising a
/// value this build can never construct.
///
/// The previous signature named `MaquinaEngine` unconditionally, which is what
/// forced the ungated `use` above and broke the default build.
///
/// # Errors
/// Always [`EngineSelectError::Unavailable`].
#[cfg(not(all(target_os = "macos", feature = "engines")))]
pub fn engine_for(_h: &Hypervisor) -> Result<std::convert::Infallible, EngineSelectError> {
    Err(EngineSelectError::Unavailable)
}