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//! ## Using the Builder API
10//!
11//! ```no_run
12//! use cargo_image_runner::builder;
13//!
14//! # fn main() -> cargo_image_runner::Result<()> {
15//! // Load configuration from Cargo.toml and run
16//! builder()
17//!     .from_cargo_metadata()?
18//!     .no_bootloader()
19//!     .directory_output()
20//!     .qemu()
21//!     .run()
22//! # }
23//! ```
24//!
25//! ## Configuration in Cargo.toml
26//!
27//! ```toml
28//! [package.metadata.image-runner.boot]
29//! type = "uefi"
30//!
31//! [package.metadata.image-runner.bootloader]
32//! kind = "none"
33//!
34//! [package.metadata.image-runner.image]
35//! format = "directory"
36//! ```
37//!
38//! ## With Limine Bootloader
39//!
40//! ```toml
41//! [package.metadata.image-runner.boot]
42//! type = "hybrid"  # Supports both BIOS and UEFI
43//!
44//! [package.metadata.image-runner.bootloader]
45//! kind = "limine"
46//! config-file = "limine.conf"
47//!
48//! [package.metadata.image-runner.bootloader.limine]
49//! version = "v8.4.0-binary"
50//!
51//! [package.metadata.image-runner.variables]
52//! TIMEOUT = "5"
53//! ```
54//!
55//! Then create `limine.conf`:
56//!
57//! ```text
58//! timeout: {{TIMEOUT}}
59//!
60//! /My Kernel
61//!     protocol: limine
62//!     kernel_path: boot():/boot/{{EXECUTABLE_NAME}}
63//! ```
64//!
65//! # Architecture
66//!
67//! The library is built around three core traits:
68//!
69//! - [`Bootloader`](bootloader::Bootloader): Prepares bootloader files and configuration
70//! - [`ImageBuilder`](image::ImageBuilder): Builds bootable images in various formats
71//! - [`Runner`](runner::Runner): Executes images (e.g., in QEMU)
72//!
73//! These traits allow easy extensibility for custom bootloaders, image formats, and runners.
74//!
75//! # Custom Bootloader Example
76//!
77//! ```no_run
78//! use cargo_image_runner::bootloader::{Bootloader, BootloaderFiles, ConfigFile};
79//! use cargo_image_runner::config::BootType;
80//! use cargo_image_runner::core::{Context, Result};
81//!
82//! struct MyBootloader;
83//!
84//! impl Bootloader for MyBootloader {
85//!     fn prepare(&self, ctx: &Context) -> Result<BootloaderFiles> {
86//!         Ok(BootloaderFiles::new())
87//!     }
88//!
89//!     fn config_files(&self, ctx: &Context) -> Result<Vec<ConfigFile>> {
90//!         Ok(Vec::new())
91//!     }
92//!
93//!     fn boot_type(&self) -> BootType {
94//!         BootType::Uefi
95//!     }
96//!
97//!     fn name(&self) -> &str {
98//!         "MyBootloader"
99//!     }
100//! }
101//! ```
102//!
103//! # Features
104//!
105//! - `default` - Enables `uefi`, `bios`, `limine`, `iso`, and `qemu`
106//! - `uefi` - UEFI boot support (includes OVMF firmware)
107//! - `bios` - BIOS boot support
108//! - `limine` - Limine bootloader (requires git)
109//! - `grub` - GRUB bootloader
110//! - `iso` - ISO image format (not yet implemented)
111//! - `fat` - FAT filesystem image format (not yet implemented)
112//! - `qemu` - QEMU runner
113//! - `progress` - Progress reporting (optional, not yet implemented)
114
115pub mod bootloader;
116pub mod config;
117pub mod core;
118pub mod firmware;
119pub mod image;
120pub mod runner;
121pub mod util;
122
123// Re-export commonly used types
124pub use crate::core::{Error, ImageRunner, ImageRunnerBuilder, Result};
125pub use config::{BootType, BootloaderKind, Config, ImageFormat};
126
127/// Create a new image runner builder.
128///
129/// This is the main entry point for the fluent API.
130///
131/// # Example
132///
133/// ```no_run
134/// use cargo_image_runner::builder;
135///
136/// # fn main() -> cargo_image_runner::Result<()> {
137/// builder()
138///     .from_cargo_metadata()?
139///     .no_bootloader()
140///     .directory_output()
141///     .qemu()
142///     .run()
143/// # }
144/// ```
145pub fn builder() -> ImageRunnerBuilder {
146    ImageRunnerBuilder::new()
147}
cargo_image_runner/lib.rs

cargo_image_runner/
lib.rs
