containerization-framework 0.2.1

Rust bindings for Apple's Containerization framework: Linux containers in lightweight VMs, in-process and without a daemon.
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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

//! Rust bindings for Apple's [Containerization] framework: Linux containers,
//! each in its own lightweight VM, in-process and with no daemon.
//!
//! # Requirements
//!
//! macOS 26 on Apple silicon, with Xcode 26 to build. The Swift package is
//! compiled by this crate's build script, which resolves Containerization and
//! its dependencies from the network on a first build.
//!
//! **A binary using this crate must be codesigned with the
//! `com.apple.security.virtualization` entitlement**, or every [`Session::boot`]
//! fails saying so. A plain `cargo build` drops the signature, so re-sign after
//! each one; `containerization.entitlements` in this crate is the file to pass
//! to `codesign --entitlements`.
//!
//! Elsewhere this crate compiles, and every call that needs a VM fails on
//! first use with [`Error::Unavailable`], so a cross-platform workspace still
//! builds.
//!
//! # Shape
//!
//! [`Builder`] turns a [`BuildPlan`] into an image in the [`Store`].
//! [`Session`] boots a [`BootSpec`]'s container from one and runs processes
//! in it. A container belongs to the process that booted it and dies with it;
//! reaching one from elsewhere is the caller's to arrange.
//!
//! Configuration types in [`model`] mirror Containerization's, with the same
//! names and defaults.
//!
//! [Containerization]: https://github.com/apple/containerization

// `exec` passes a process's descriptors as scalars beside its configuration,
// and swift-bridge refuses an `allow` inside its module.
#![cfg_attr(target_os = "macos", allow(clippy::too_many_arguments))]

pub mod error;
pub mod model;
pub mod stdio;
mod store;

mod builder;
mod session;

#[cfg(target_os = "macos")]
mod bridge;

#[cfg(not(target_os = "macos"))]
mod unsupported;

pub use crate::builder::Builder;
pub use crate::error::Error;
pub use crate::model::{BootSpec, BuildPlan, BuildStep, CachePolicy, Shell};
pub use crate::session::Session;
pub use crate::stdio::{Stdio, UNATTACHED, is_tty, lend};
pub use crate::store::{
  INITFS_REFERENCE, INITFS_VERSION, KERNEL_IN_ARCHIVE, KERNEL_URL, KERNEL_VERSION, Store, StoreError,
};

/// The bridge's failure code; can't collide with a guest exit code (0...255).
const FAILED: i32 = -1;

#[cfg(target_os = "macos")]
use crate::bridge::ffi;

#[cfg(not(target_os = "macos"))]
use crate::unsupported as ffi;

/// Turns the bridge's `-1` into a failure of `action`, with the message Swift
/// left behind.
#[cfg(target_os = "macos")]
fn checked(code: i32, action: impl Into<String>) -> Result<i32, Error> {
  if code == FAILED {
    return Err(Error::failed(action, ffi::czbridge_last_error()));
  }

  Ok(code)
}

/// Elsewhere the bridge only ever fails, and nothing was attempted.
#[cfg(not(target_os = "macos"))]
fn checked(code: i32, action: impl Into<String>) -> Result<i32, Error> {
  if code == FAILED {
    return Err(Error::unavailable(action, "Containerization.framework is macOS only"));
  }

  Ok(code)
}