roxy_loader_utils/
build_image.rs

1//! Helpers for producing bootable disk images for `roxy-loader`.
2//!
3//! The functions in this module are intended for host-side build tools that
4//! need to prepare a disk image containing the loader and a kernel binary.
5
6use std::{
7    fs::File,
8    io::{self, Seek, SeekFrom},
9    path::{Path, PathBuf},
10};
11
12use anyhow::Result;
13use cargo_artifact_dependency::ArtifactDependencyBuilder;
14use fatfs::{FileSystem, FormatVolumeOptions, FsOptions};
15
16use crate::utils::{cargo_target_dir, static_workspace_root};
17
18const ROXY_LOADER_ARTIFACT_VERSION: &str = "0.1.5";
19
20/// Builds a bootable disk image for a kernel artifact.
21pub fn build_image(kernel_binary: PathBuf) -> Result<PathBuf> {
22    let image_path = default_image_path()?;
23    build_image_from_paths(&image_path, &roxyloader_artifact()?, &kernel_binary)?;
24    Ok(image_path)
25}
26
27/// Builds a bootable disk image from explicit paths.
28///
29/// Use this when you want full control over the image path, loader path, or
30/// kernel path.
31///
32/// # Examples
33///
34/// ```
35/// use roxy_loader_utils::build_image::build_image_from_paths;
36///
37/// let temp = std::env::temp_dir().join(format!(
38///     "roxy-loader-doc-{}",
39///     std::process::id()
40/// ));
41/// std::fs::create_dir_all(&temp)?;
42///
43/// let image = temp.join("image.img");
44/// let loader = temp.join("loader.efi");
45/// let kernel = temp.join("kernel.bin");
46///
47/// std::fs::write(&loader, b"loader")?;
48/// std::fs::write(&kernel, b"kernel")?;
49///
50/// build_image_from_paths(&image, &loader, &kernel)?;
51///
52/// assert!(image.exists());
53///
54/// std::fs::remove_dir_all(&temp)?;
55/// # Ok::<(), Box<dyn std::error::Error>>(())
56/// ```
57pub fn build_image_from_paths(
58    image_path: &Path,
59    roxyloader_artifact: &Path,
60    kernel_binary: &Path,
61) -> Result<()> {
62    const IMAGE_SIZE: u64 = 64 * 1024 * 1024;
63
64    let mut image = open_image(image_path)?;
65
66    // truncate
67    image.set_len(IMAGE_SIZE)?;
68
69    fatfs::format_volume(&mut image, FormatVolumeOptions::new())?;
70
71    image.seek(SeekFrom::Start(0))?;
72
73    let fs = FileSystem::new(image, FsOptions::new())?;
74
75    let root_dir = fs.root_dir();
76    root_dir.create_dir("EFI")?;
77    let efi_dir = root_dir.open_dir("EFI")?;
78    efi_dir.create_dir("BOOT")?;
79    let boot_dir = efi_dir.open_dir("BOOT")?;
80
81    // Copies roxyloader artifact
82    let mut src = File::open(roxyloader_artifact)?;
83    let mut dst = boot_dir.create_file("BOOTX64.EFI")?;
84    io::copy(&mut src, &mut dst)?;
85
86    // Installs kernel binary
87    let mut dst = fs.root_dir().create_file("KERNEL")?;
88    let mut src = File::open(kernel_binary)?;
89    io::copy(&mut src, &mut dst)?;
90
91    Ok(())
92}
93
94/// Returns the default output path used by [`build_image`].
95pub fn default_image_path() -> Result<PathBuf> {
96    const IMAGE_NAME: &str = "image.img";
97    Ok(cargo_target_dir()?.join(IMAGE_NAME))
98}
99
100fn open_image(path: &Path) -> Result<File> {
101    Ok(File::options()
102        .read(true)
103        .write(true)
104        .create(true)
105        .truncate(true)
106        .open(path)?)
107}
108
109fn roxyloader_artifact() -> Result<PathBuf> {
110    Ok(ArtifactDependencyBuilder::default()
111        .crate_name("roxy-loader")
112        // Use staticly evaluated workspace root to prevent it from getting the
113        // crate user's workspace root
114        .path(static_workspace_root())
115        .version(ROXY_LOADER_ARTIFACT_VERSION)
116        .target("x86_64-unknown-uefi")
117        .build()?
118        .resolve()?)
119}
120
121#[cfg(test)]
122mod tests {
123    use workspace_root::get_workspace_root;
124
125    use super::*;
126    use std::{
127        io::Read,
128        sync::atomic::{AtomicU64, Ordering},
129        time::{SystemTime, UNIX_EPOCH},
130    };
131
132    fn test_temp_dir() -> Result<std::path::PathBuf> {
133        static COUNTER: AtomicU64 = AtomicU64::new(0);
134
135        let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
136        let dir = std::env::temp_dir().join(format!(
137            "roxy-loader-test-{}-{}",
138            std::process::id(),
139            SystemTime::now().duration_since(UNIX_EPOCH)?.as_nanos() + unique as u128
140        ));
141
142        std::fs::create_dir_all(&dir)?;
143        Ok(dir)
144    }
145
146    #[test]
147    fn roxyloader_artifact_version_matches_package_version() -> Result<()> {
148        let metadata = cargo_metadata::MetadataCommand::new()
149            .manifest_path(get_workspace_root().join("Cargo.toml"))
150            .exec()?;
151        let package = metadata
152            .packages
153            .iter()
154            .find(|package| package.name == "roxy-loader")
155            .expect("workspace should contain the roxy-loader package");
156
157        assert_eq!(
158            ROXY_LOADER_ARTIFACT_VERSION,
159            package.version.to_string(),
160            "update ROXY_LOADER_ARTIFACT_VERSION when bumping roxy-loader"
161        );
162
163        Ok(())
164    }
165
166    #[test]
167    fn roxyloader_artifact_resolves_to_valid_file() -> Result<()> {
168        let artifact_path = roxyloader_artifact()?;
169        let metadata = std::fs::metadata(&artifact_path)?;
170
171        assert!(
172            metadata.is_file(),
173            "roxy-loader artifact path should be a file: {}",
174            artifact_path.display()
175        );
176        assert!(
177            metadata.len() > 0,
178            "roxy-loader artifact should not be empty: {}",
179            artifact_path.display()
180        );
181
182        Ok(())
183    }
184
185    #[test]
186    fn build_image_contains_loader_and_kernel_payloads() -> Result<()> {
187        let dir = test_temp_dir()?;
188        let image_path = dir.join("image.img");
189        let loader_path = dir.join("loader.efi");
190        let kernel_path = dir.join("kernel.bin");
191
192        std::fs::write(&loader_path, b"loader-bytes")?;
193        std::fs::write(&kernel_path, b"kernel-bytes")?;
194
195        build_image_from_paths(&image_path, &loader_path, &kernel_path)?;
196
197        let image = File::options().read(true).write(true).open(&image_path)?;
198        let fs = FileSystem::new(image, FsOptions::new())?;
199
200        let root = fs.root_dir();
201        let efi_dir = root.open_dir("EFI")?;
202        let boot_dir = efi_dir.open_dir("BOOT")?;
203
204        let mut loader_file = boot_dir.open_file("BOOTX64.EFI")?;
205        let mut loader_bytes = Vec::new();
206        loader_file.read_to_end(&mut loader_bytes)?;
207        assert_eq!(loader_bytes, b"loader-bytes");
208
209        let mut kernel_file = root.open_file("KERNEL")?;
210        let mut kernel_bytes = Vec::new();
211        kernel_file.read_to_end(&mut kernel_bytes)?;
212        assert_eq!(kernel_bytes, b"kernel-bytes");
213
214        std::fs::remove_dir_all(&dir)?;
215        Ok(())
216    }
217
218    #[test]
219    fn build_image_truncates_existing_image_contents() -> Result<()> {
220        let dir = test_temp_dir()?;
221        let image_path = dir.join("image.img");
222        let loader_path = dir.join("loader.efi");
223        let kernel_path = dir.join("kernel.bin");
224
225        std::fs::write(&loader_path, b"a")?;
226        std::fs::write(&kernel_path, b"b")?;
227        std::fs::write(&image_path, b"stale-bytes")?;
228
229        build_image_from_paths(&image_path, &loader_path, &kernel_path)?;
230
231        let metadata = std::fs::metadata(&image_path)?;
232        assert_eq!(metadata.len(), 64 * 1024 * 1024);
233
234        std::fs::remove_dir_all(&dir)?;
235        Ok(())
236    }
237}
roxy_loader_utils/build_image.rs

roxy_loader_utils/
build_image.rs
