os_foundry_suite/
lib.rs

1#![doc = include_str!("../docs/CRATE_OVERVIEW.md")]
2
3//!
4//! # os_foundry_suite
5//!
6//! This crate is a *suite* facade that unifies multiple OS-building crates into a single,
7//! coherent, well-documented entry point.
8//!
9//! It is designed to:
10//!
11//! - Provide a stable, user-friendly *orchestration* API (blueprints, builders, targets).
12//! - Re-export the underlying crates behind feature flags.
13//! - Offer conventions and integration helpers so downstream projects can compose kernel,
14//!   services, ABI contracts, state machines, observability, and images with less friction.
15//!
16//! ## Feature flags
17//!
18//! The underlying crates are optional dependencies. Enable only what you need:
19//!
20//! - `kernel-foundry` => `os_kernel_foundry`
21//! - `dev-toolkit` => `os_dev_toolkit`
22//! - `metal-primitives` => `os_metal_primitives`
23//! - `service-fabric` => `os_service_fabric`
24//! - `linker-sculptor` => `os_linker_sculptor`
25//! - `slab-vault` => `os_slab_vault`
26//! - `abi-sentinel` => `os_abi_sentinel`
27//! - `state-maestro` => `os_state_maestro`
28//! - `observatory` => `os_observatory`
29//! - `image-lens` => `os_image_lens`
30//!
31//! Additional features:
32//!
33//! - `serde` enables serialization support for select suite-level types.
34//!
35//! ## Quick start
36//!
37//! ```
38//! use os_foundry_suite::prelude::*;
39//!
40//! let blueprint = OsBlueprint::minimal_dev();
41//! blueprint.validate().unwrap();
42//!
43//! let plan = OsBuilder::new(blueprint)
44//!     .target(Target::x86_64_bare_metal())
45//!     .validate_and_plan()
46//!     .unwrap();
47//!
48//! assert_eq!(plan.target.arch, Arch::X86_64);
49//! ```
50//!
51//! ## Scope
52//!
53//! This crate intentionally focuses on *composition and orchestration*. It does not attempt
54//! to hide all complexity involved in OS development; instead it provides a consistent
55//! structure and strongly-typed configuration to reduce accidental complexity.
56
57pub mod artifacts;
58pub mod builder;
59pub mod config;
60pub mod error;
61pub mod execution;
62pub mod export;
63pub mod image;
64pub mod integration;
65pub mod pipeline;
66pub mod prelude;
67pub mod profiles;
68pub mod report;
69pub mod services;
70pub mod targets;
71
72pub use artifacts::{ArtifactCatalog, BuildMetadata, WorkspaceLayout};
73pub use builder::{BuildPlan, OsBuilder};
74pub use config::{
75    AbiPolicy, ImageConfig, ImageKind, KernelConfig, MemoryConfig, ObservabilityConfig,
76    OsBlueprint, ServiceSet, ValidationReport,
77};
78pub use error::{Error, Result};
79pub use execution::{
80    CommandSpec, ExecutionPlan, ExecutionPlanner, QemuRunSpec, ToolchainChannel, ToolchainSpec,
81    plan_execution,
82};
83pub use export::{
84    CommandExport, ExecutionPlanExport, ImagePlanExport, ServiceGraphExport, SuiteReportExport,
85};
86pub use image::{
87    BootArtifact, ImageLayoutIntent, ImagePlan, PartitionScheme, PartitionSpec, plan_image,
88};
89pub use integration::validate_blueprint_integrations;
90pub use pipeline::derive_artifacts;
91pub use profiles::Profiles;
92pub use report::SuiteReport;
93pub use services::{ServiceGraph, ServiceId, ServiceNode};
94pub use targets::{Arch, Target};
95
96/// Re-exports of the underlying crates, gated behind feature flags.
97///
98/// The naming is intentionally short and stable, so downstream code can write:
99/// `os_foundry_suite::crates::kernel::...`.
100pub mod crates {
101    /// Re-export of `os_kernel_foundry`.
102    #[cfg(feature = "kernel-foundry")]
103    pub use os_kernel_foundry as kernel;
104
105    /// Re-export of `os_dev_toolkit`.
106    #[cfg(feature = "dev-toolkit")]
107    pub use os_dev_toolkit as dev;
108
109    /// Re-export of `os_metal_primitives`.
110    #[cfg(feature = "metal-primitives")]
111    pub use os_metal_primitives as metal;
112
113    /// Re-export of `os_service_fabric`.
114    #[cfg(feature = "service-fabric")]
115    pub use os_service_fabric as services;
116
117    /// Re-export of `os_linker_sculptor`.
118    #[cfg(feature = "linker-sculptor")]
119    pub use os_linker_sculptor as linker;
120
121    /// Re-export of `os_slab_vault`.
122    #[cfg(feature = "slab-vault")]
123    pub use os_slab_vault as slab;
124
125    /// Re-export of `os_abi_sentinel`.
126    #[cfg(feature = "abi-sentinel")]
127    pub use os_abi_sentinel as abi;
128
129    /// Re-export of `os_state_maestro`.
130    #[cfg(feature = "state-maestro")]
131    pub use os_state_maestro as state;
132
133    /// Re-export of `os_observatory`.
134    #[cfg(feature = "observatory")]
135    pub use os_observatory as observatory;
136
137    /// Re-export of `os_image_lens`.
138    #[cfg(feature = "image-lens")]
139    pub use os_image_lens as image;
140}
os_foundry_suite/lib.rs

os_foundry_suite/
lib.rs
