cargo_image_runner/
lib.rs

1//! cargo-image-runner: A generic, highly customizable embedded/kernel development runner for Rust.
2//!
3//! This library provides a flexible framework for building and running bootable images with
4//! support for multiple bootloaders (Limine, GRUB, none), image formats (ISO, FAT, directory),
5//! and boot types (BIOS, UEFI, hybrid).
6//!
7//! # Quick Start
8//!
9//! ## Standalone Usage (no `cargo_metadata` or `clap` required)
10//!
11//! ```no_run
12//! use cargo_image_runner::{builder, Config};
13//!
14//! # fn main() -> cargo_image_runner::Result<()> {
15//! let config = Config::from_toml_str(r#"
16//!     [boot]
17//!     type = "uefi"
18//!     [bootloader]
19//!     kind = "none"
20//!     [image]
21//!     format = "directory"
22//! "#)?;
23//!
24//! builder()
25//!     .with_config(config)
26//!     .workspace_root(".")
27//!     .executable("target/x86_64-unknown-none/debug/my-kernel")
28//!     .run()
29//! # }
30//! ```
31//!
32//! ## Using Cargo.toml Metadata (requires `cargo-metadata` feature)
33//!
34//! ```no_run
35//! # #[cfg(feature = "cargo-metadata")]
36//! # fn main() -> cargo_image_runner::Result<()> {
37//! use cargo_image_runner::builder;
38//!
39//! // Load configuration from Cargo.toml and run
40//! builder()
41//!     .from_cargo_metadata()?
42//!     .no_bootloader()
43//!     .directory_output()
44//!     .qemu()
45//!     .run()
46//! # }
47//! # #[cfg(not(feature = "cargo-metadata"))]
48//! # fn main() {}
49//! ```
50//!
51//! ## Configuration in Cargo.toml
52//!
53//! ```toml
54//! [package.metadata.image-runner.boot]
55//! type = "uefi"
56//!
57//! [package.metadata.image-runner.bootloader]
58//! kind = "none"
59//!
60//! [package.metadata.image-runner.image]
61//! format = "directory"
62//! ```
63//!
64//! ## With Limine Bootloader
65//!
66//! ```toml
67//! [package.metadata.image-runner.boot]
68//! type = "hybrid"  # Supports both BIOS and UEFI
69//!
70//! [package.metadata.image-runner.bootloader]
71//! kind = "limine"
72//! config-file = "limine.conf"
73//!
74//! [package.metadata.image-runner.bootloader.limine]
75//! version = "v8.4.0-binary"
76//!
77//! [package.metadata.image-runner.variables]
78//! TIMEOUT = "5"
79//! ```
80//!
81//! Then create `limine.conf`:
82//!
83//! ```text
84//! timeout: {{TIMEOUT}}
85//!
86//! /My Kernel
87//!     protocol: limine
88//!     kernel_path: boot():/boot/{{EXECUTABLE_NAME}}
89//! ```
90//!
91//! # Architecture
92//!
93//! The library is built around three core traits:
94//!
95//! - [`Bootloader`](bootloader::Bootloader): Prepares bootloader files and configuration
96//! - [`ImageBuilder`](image::ImageBuilder): Builds bootable images in various formats
97//! - [`Runner`](runner::Runner): Executes images (e.g., in QEMU)
98//!
99//! These traits allow easy extensibility for custom bootloaders, image formats, and runners.
100//!
101//! # Custom Bootloader Example
102//!
103//! ```no_run
104//! use cargo_image_runner::bootloader::{Bootloader, BootloaderFiles, ConfigFile};
105//! use cargo_image_runner::config::BootType;
106//! use cargo_image_runner::core::{Context, Result};
107//!
108//! struct MyBootloader;
109//!
110//! impl Bootloader for MyBootloader {
111//!     fn prepare(&self, ctx: &Context) -> Result<BootloaderFiles> {
112//!         Ok(BootloaderFiles::new())
113//!     }
114//!
115//!     fn config_files(&self, ctx: &Context) -> Result<Vec<ConfigFile>> {
116//!         Ok(Vec::new())
117//!     }
118//!
119//!     fn boot_type(&self) -> BootType {
120//!         BootType::Uefi
121//!     }
122//!
123//!     fn name(&self) -> &str {
124//!         "MyBootloader"
125//!     }
126//! }
127//! ```
128//!
129//! # Features
130//!
131//! - `default` - Enables `cli`, `cargo-metadata`, `uefi`, `bios`, `limine`, `iso`, and `qemu`
132//! - `cli` - CLI binary and argument parsing (implies `cargo-metadata`)
133//! - `cargo-metadata` - Load config from `Cargo.toml` via `cargo_metadata`
134//! - `uefi` - UEFI boot support (includes OVMF firmware)
135//! - `bios` - BIOS boot support
136//! - `limine` - Limine bootloader (requires git)
137//! - `grub` - GRUB bootloader
138//! - `iso` - ISO image format
139//! - `fat` - FAT filesystem image format
140//! - `qemu` - QEMU runner
141//! - `progress` - Progress reporting (optional)
142//!
143//! For standalone library use without `clap` or `cargo_metadata`:
144//!
145//! ```toml
146//! [dependencies]
147//! cargo-image-runner = { version = "0.4", default-features = false, features = ["uefi", "qemu"] }
148//! ```
149
150pub mod bootloader;
151pub mod config;
152pub mod core;
153pub mod firmware;
154pub mod image;
155pub mod runner;
156pub mod util;
157
158// Re-export commonly used types
159pub use crate::core::{Error, ImageRunner, ImageRunnerBuilder, Result};
160pub use config::{BootType, BootloaderKind, Config, ImageFormat};
161
162/// Create a new image runner builder.
163///
164/// This is the main entry point for the fluent API.
165///
166/// # Example
167///
168/// ```no_run
169/// use cargo_image_runner::{builder, Config};
170///
171/// # fn main() -> cargo_image_runner::Result<()> {
172/// let config = Config::from_toml_str(r#"
173///     [boot]
174///     type = "uefi"
175///     [bootloader]
176///     kind = "none"
177///     [image]
178///     format = "directory"
179/// "#)?;
180///
181/// builder()
182///     .with_config(config)
183///     .workspace_root(".")
184///     .executable("target/x86_64-unknown-none/debug/my-kernel")
185///     .run()
186/// # }
187/// ```
188pub fn builder() -> ImageRunnerBuilder {
189    ImageRunnerBuilder::new()
190}
cargo_image_runner/lib.rs

cargo_image_runner/
lib.rs
