omea_kernel/lib.rs
1//! Pre-built runtime assets for [omea], packaged as a Rust crate so
2//! embedders can `cargo add omea-kernel` instead of fetching binaries
3//! out of band — with **no network at build time** (the bytes are
4//! `include_bytes!`'d into the binary).
5//!
6//! ## A facade over per-arch sub-crates
7//!
8//! omea runs a **guest** Linux kernel matching the **host** arch (KVM
9//! guest). Shipping every arch's kernel in one crate would bust the crates.io
10//! ~10 MiB cap and make every consumer download kernels they can't use.
11//!
12//! So this crate is a thin facade. The actual bytes live in per-arch
13//! sub-crates, declared as `[target.'cfg(target_arch = ...)']` dependencies:
14//!
15//! - [`omea-kernel-x86-64`] — x86_64 `bzImage` + busybox + agent
16//!
17//! Cargo only resolves/downloads the dependency whose `cfg(target_arch)`
18//! matches the **compilation target**, so building for x86_64 fetches *only*
19//! other arch's multi-MiB kernel. This module re-exports the matching
20//! sub-crate's public API (`KERNEL_BYTES`, `extract_kernel_to`, …) so callers
21//! write arch-agnostic code:
22//!
23//! ```no_run
24//! // Same call on any host; you get that host's guest kernel.
25//! omea_kernel::extract_kernel_to(
26//! std::path::Path::new("/tmp/omea/kernel"),
27//! ).unwrap();
28//! ```
29//!
30//! ## Arch-specific surface
31//!
32//! Most of the API is common to both sub-crates: `KERNEL_BYTES` / `KERNEL_LEN`,
33//! `OMEA_AGENT_BYTES` / `_LEN`, and the `extract_kernel_to{,_with_parents}`
34//! / `extract_omea_agent_to{,_with_parents}` helpers.
35//!
36//! Some items exist only on one arch because the backends differ:
37//! `smpark.ko` module for multi-vCPU snapshot capture.
38//! - **x86_64 only:** `BUSYBOX_BYTES` (+ `extract_busybox_to*` / `BUSYBOX_LEN`).
39//! The KVM backend builds the container rootfs (overlayfs + `switch_root`)
40//! directly in the agent initramfs, using a bundled busybox.
41//!
42//! Code that needs an arch-specific item should gate it with
43//! `#[cfg(target_arch = "…")]` to stay portable.
44//!
45//! [omea]: https://crates.io/crates/omea
46//! [`omea-kernel-x86-64`]: https://crates.io/crates/omea-kernel-x86-64
47
48#[cfg(target_arch = "x86_64")]
49pub use omea_kernel_x86_64::*;
50
51// The facade only supports the arches omea itself runs on. Fail loudly
52// rather than silently exporting an empty API on an unsupported target.
53#[cfg(not(target_arch = "x86_64"))]
54compile_error!(
55 "omea-kernel supports only x86_64 (KVM) hosts; \
56 no guest kernel is bundled for this target_arch"
57);