sprout: version 0.0.9

.github/workflows/ci-actions.yaml

@@ -9,6 +9,10 @@ on:
 permissions:
   contents: read # Needed to checkout the repository.
 
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}"
+  cancel-in-progress: true
+
 jobs:
   zizmor:
     name: zizmor
@@ -24,12 +28,12 @@ jobs:
         egress-policy: audit
 
     - name: checkout
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         persist-credentials: false
 
     - name: setup uv
-      uses: astral-sh/setup-uv@3259c6206f993105e3a61b142c2d97bf4b9ef83d # v7
+      uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
 
     - name: zizmor
       run: uvx zizmor --pedantic --format sarif . > results.sarif
@@ -37,7 +41,7 @@ jobs:
         GH_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
 
     - name: upload
-      uses: github/codeql-action/upload-sarif@16140ae1a102900babc80a33c44059580f687047 # v4
+      uses: github/codeql-action/upload-sarif@4e94bd11f71e507f7f87df81788dff88d1dacbfb # v4.31.0
       with:
         sarif_file: results.sarif
         category: zizmor

.github/workflows/ci-code.yaml

@@ -11,6 +11,10 @@ on:
 permissions:
   contents: read # Needed to checkout the repository.
 
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}"
+  cancel-in-progress: true
+
 jobs:
   rustfmt:
     name: rustfmt
@@ -22,7 +26,7 @@ jobs:
         egress-policy: audit
 
     - name: checkout
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         persist-credentials: false
 
@@ -52,7 +56,7 @@ jobs:
         egress-policy: audit
 
     - name: checkout
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         persist-credentials: false
 
@@ -81,7 +85,7 @@ jobs:
         egress-policy: audit
 
     - name: checkout
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         persist-credentials: false
 

.github/workflows/codeql.yaml

@@ -11,6 +11,10 @@ on:
 permissions:
   contents: read # Needed to checkout the repository.
 
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}"
+  cancel-in-progress: true
+
 jobs:
   analyze:
     name: analyze (${{ matrix.language }})
@@ -36,18 +40,18 @@ jobs:
         egress-policy: audit
 
     - name: checkout
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         persist-credentials: false
 
     - name: initialize codeql
-      uses: github/codeql-action/init@16140ae1a102900babc80a33c44059580f687047 #v4
+      uses: github/codeql-action/init@4e94bd11f71e507f7f87df81788dff88d1dacbfb # v4.31.0
       with:
         languages: ${{ matrix.language }}
         build-mode: ${{ matrix.build-mode }}
         config-file: ./.github/codeql/codeql-config.yaml
 
     - name: perform codeql analysis
-      uses: github/codeql-action/analyze@16140ae1a102900babc80a33c44059580f687047 #v4
+      uses: github/codeql-action/analyze@4e94bd11f71e507f7f87df81788dff88d1dacbfb # v4.31.0
       with:
         category: "/language:${{matrix.language}}"

.github/workflows/publish.yaml

@@ -1,13 +1,6 @@
 name: publish
 
 on:
-  workflow_dispatch:
-    inputs:
-      release-tag:
-        description: 'Release Tag'
-        required: true
-        type: string
-
   push:
     branches:
     - main
@@ -25,11 +18,15 @@ on:
 permissions:
   contents: read # Needed to checkout the repository.
 
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}"
+  cancel-in-progress: true
+
 jobs:
   artifacts:
     name: artifacts
     permissions:
-      contents: write # Needed to upload release assets and artifacts.
+      contents: write # Needed to upload artifacts.
     runs-on: ubuntu-latest
     steps:
     - name: harden runner
@@ -38,7 +35,7 @@ jobs:
         egress-policy: audit
 
     - name: checkout
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         persist-credentials: false
 
@@ -50,35 +47,13 @@ jobs:
       run: ./hack/assemble.sh
 
     - name: 'upload sprout-x86_64.efi artifact'
-      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+      uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
       with:
         name: sprout-x86_64.efi
         path: target/assemble/sprout-x86_64.efi
 
     - name: 'upload sprout-aarch64.efi artifact'
-      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+      uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
       with:
         name: sprout-aarch64.efi
         path: target/assemble/sprout-aarch64.efi
-
-    - name: 'generate cultivator token'
-      uses: actions/create-github-app-token@67018539274d69449ef7c02e8e71183d1719ab42 # v2.1.4
-      id: generate-token
-      with:
-        app-id: "${{ secrets.EDERA_CULTIVATION_APP_ID }}"
-        private-key: "${{ secrets.EDERA_CULTIVATION_APP_PRIVATE_KEY }}"
-      if: ${{ github.event.inputs.release-tag != '' }}
-
-    - name: 'upload release artifacts'
-      run: ./hack/ci/upload-release-assets.sh
-      env:
-        GITHUB_TOKEN: "${{ steps.generate-token.outputs.token }}"
-        RELEASE_TAG: "${{ github.event.inputs.release-tag }}"
-      if: ${{ github.event.inputs.release-tag != '' }}
-
-    - name: 'mark release as published'
-      run: gh release edit "${RELEASE_TAG}" --draft=false --verify-tag
-      env:
-        GITHUB_TOKEN: "${{ steps.generate-token.outputs.token }}"
-        RELEASE_TAG: "${{ github.event.inputs.release-tag }}"
-      if: ${{ github.event.inputs.release-tag != '' }}

.github/workflows/release.yaml

@@ -0,0 +1,62 @@
+name: release
+
+on:
+  workflow_dispatch:
+    inputs:
+      release-tag:
+        description: 'Release Tag'
+        required: true
+        type: string
+
+permissions:
+  contents: read # Needed to checkout the repository.
+
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.inputs.release-tag }}"
+  cancel-in-progress: true
+
+jobs:
+  release:
+    name: release
+    permissions:
+      contents: write # Needed to upload release assets.
+    runs-on: ubuntu-latest
+    steps:
+    - name: harden runner
+      uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
+      with:
+        egress-policy: audit
+
+    - name: checkout
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      with:
+        persist-credentials: false
+
+    - name: 'install rust toolchain'
+      run: |
+        cargo version
+
+    - name: 'assemble artifacts'
+      run: ./hack/assemble.sh
+
+    - name: 'generate cultivator token'
+      uses: actions/create-github-app-token@bf559f85448f9380bcfa2899dbdc01eb5b37be3a # v3.0.0-beta.2
+      id: generate-token
+      with:
+        app-id: "${{ secrets.EDERA_CULTIVATION_APP_ID }}"
+        private-key: "${{ secrets.EDERA_CULTIVATION_APP_PRIVATE_KEY }}"
+      if: ${{ github.event.inputs.release-tag != '' }}
+
+    - name: 'upload release artifacts'
+      run: ./hack/ci/upload-release-assets.sh
+      env:
+        GITHUB_TOKEN: "${{ steps.generate-token.outputs.token }}"
+        RELEASE_TAG: "${{ github.event.inputs.release-tag }}"
+      if: ${{ github.event.inputs.release-tag != '' }}
+
+    - name: 'mark release as published'
+      run: gh release edit "${RELEASE_TAG}" --draft=false --verify-tag
+      env:
+        GITHUB_TOKEN: "${{ steps.generate-token.outputs.token }}"
+        RELEASE_TAG: "${{ github.event.inputs.release-tag }}"
+      if: ${{ github.event.inputs.release-tag != '' }}

Cargo.lock

@@ -61,7 +61,7 @@ dependencies = [
 
 [[package]]
 name = "edera-sprout"
-version = "0.0.7"
+version = "0.0.9"
 dependencies = [
  "anyhow",
  "image",

Cargo.toml

@@ -2,7 +2,7 @@
 name = "edera-sprout"
 description = "Modern UEFI bootloader"
 license = "Apache-2.0"
-version = "0.0.7"
+version = "0.0.9"
 homepage = "https://sprout.edera.dev"
 repository = "https://github.com/edera-dev/sprout"
 edition = "2024"

README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-![Sprout Logo](assets/logo.png)
+![Sprout Logo](assets/logo-small.png)
 
 # Sprout
 
@@ -18,6 +18,23 @@ existing UEFI bootloader or booted by the hardware directly.
 
 Sprout is licensed under Apache 2.0 and is open to modifications and contributions.
 
+## Background
+
+At [Edera] we make compute isolation technology for a wide variety of environments, often ones we do not fully control.
+Our technology utilizes a hypervisor to boot the host system to provide a new isolation mechanism that works
+with or without hardware virtualization support. To do this we need to inject our hypervisor at boot time.
+
+Unfortunately, GRUB, the most common bootloader on Linux systems today, utilizes a shell-script like
+configuration system. Both the code that runs to generate a GRUB config and the GRUB config
+itself is fully turing complete. This makes modifying boot configuration difficult and error-prone.
+
+Sprout was designed to take in a machine-readable, writable, and modifiable configuration that treats boot information
+like data plus configuration, and can be chained from both UEFI firmware and GRUB alike.
+
+Sprout aims to be flexible, secure, and modern. Written in Rust, it handles data safely and uses unsafe code as little
+as possible. It also critically must be easy to install into all common distributions, relying on simple principles to
+simplify installation and usage.
+
 ## Documentation
 
 - [Fedora Setup Guide]
@@ -40,6 +57,7 @@ have secure boot support. In fact, as of writing, it doesn't even have a boot me
 - [x] [Bootloader specification (BLS)](https://uapi-group.org/specifications/specs/boot_loader_specification/) support
 - [x] Chainload support
 - [x] Linux boot support via EFI stub
+- [x] Windows boot support via chainload
 - [x] Load Linux initrd from disk
 - [x] Boot first configured entry
 
@@ -48,7 +66,6 @@ have secure boot support. In fact, as of writing, it doesn't even have a boot me
 - [ ] Boot menu
 - [ ] Secure Boot support: work in progress
 - [ ] UKI support: partial
-- [ ] Windows boot support (untested via chainload)
 - [ ] multiboot2 support
 - [ ] Linux boot protocol (boot without EFI stub)
 
@@ -139,6 +156,7 @@ chainload.options = ["$options"]
 chainload.linux-initrd = "$boot\\$initrd"
 ```
 
+[Edera]: https://edera.dev
 [Fedora Setup Guide]: ./docs/fedora-setup.md
 [Generic Linux Setup Guide]: ./docs/generic-linux-setup.md
 [Windows Setup Guide]: ./docs/windows-setup.md

hack/common.sh

@@ -41,3 +41,8 @@ if [ -z "${QEMU_ACCEL}" ] && [ "${TARGET_ARCH}" = "${HOST_ARCH}" ] &&
 	grep -E '^flags.*:.+ vmx .*' /proc/cpuinfo >/dev/null; then
 	QEMU_ACCEL="kvm"
 fi
+
+if [ "$(uname)" = "Darwin" ] && [ "${TARGET_ARCH}" = "${HOST_ARCH}" ] &&
+	[ "$(sysctl -n kern.hv_support 2>&1 || true)" = "1" ]; then
+	QEMU_ACCEL="hvf"
+fi

hack/dev/boot.sh

@@ -19,7 +19,7 @@ elif [ "${TARGET_ARCH}" = "aarch64" ]; then
 fi
 
 if [ -n "${QEMU_ACCEL}" ]; then
-	set -- "${@}" "-accel" "kvm"
+	set -- "${@}" "-accel" "${QEMU_ACCEL}"
 fi
 
 if [ "${QEMU_GDB}" = "1" ]; then

src/drivers.rs

@@ -19,7 +19,7 @@ pub struct DriverDeclaration {
     pub path: String,
 }
 
-/// Loads the driver specified by the [driver] declaration.
+/// Loads the driver specified by the `driver` declaration.
 fn load_driver(context: Rc<SproutContext>, driver: &DriverDeclaration) -> Result<()> {
     // Acquire the handle and device path of the loaded image.
     let sprout_image = uefi::boot::image_handle();

src/entries.rs

@@ -1,5 +1,7 @@
+use crate::context::SproutContext;
 use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
+use std::rc::Rc;
 
 /// Declares a boot entry to display in the boot menu.
 ///
@@ -8,6 +10,7 @@ use std::collections::BTreeMap;
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct EntryDeclaration {
     /// The title of the entry which will be display in the boot menu.
+    /// This is the pre-stamped value.
     pub title: String,
     /// The actions to run when the entry is selected.
     #[serde(default)]
@@ -16,3 +19,64 @@ pub struct EntryDeclaration {
     #[serde(default)]
     pub values: BTreeMap<String, String>,
 }
+
+/// Represents an entry that is stamped and ready to be booted.
+#[derive(Clone)]
+pub struct BootableEntry {
+    name: String,
+    title: String,
+    context: Rc<SproutContext>,
+    declaration: EntryDeclaration,
+}
+
+impl BootableEntry {
+    /// Create a new bootable entry to represent the full context of an entry.
+    pub fn new(
+        name: String,
+        title: String,
+        context: Rc<SproutContext>,
+        declaration: EntryDeclaration,
+    ) -> Self {
+        Self {
+            name,
+            title,
+            context,
+            declaration,
+        }
+    }
+
+    /// Fetch the name of the entry. This is usually a machine-identifiable key.
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    /// Fetch the title of the entry. This is usually a human-readable key.
+    pub fn title(&self) -> &str {
+        &self.title
+    }
+
+    /// Fetch the full context of the entry.
+    pub fn context(&self) -> Rc<SproutContext> {
+        Rc::clone(&self.context)
+    }
+
+    /// Fetch the declaration of the entry.
+    pub fn declaration(&self) -> &EntryDeclaration {
+        &self.declaration
+    }
+
+    /// Swap out the context of the entry.
+    pub fn swap_context(&mut self, context: Rc<SproutContext>) {
+        self.context = context;
+    }
+
+    /// Restamp the title with the current context.
+    pub fn restamp_title(&mut self) {
+        self.title = self.context.stamp(&self.title);
+    }
+
+    /// Prepend the name of the entry with `prefix`.
+    pub fn prepend_name_prefix(&mut self, prefix: &str) {
+        self.name.insert_str(0, prefix);
+    }
+}

src/generators.rs

@@ -1,5 +1,5 @@
 use crate::context::SproutContext;
-use crate::entries::EntryDeclaration;
+use crate::entries::BootableEntry;
 use crate::generators::bls::BlsConfiguration;
 use crate::generators::matrix::MatrixConfiguration;
 use anyhow::Result;
@@ -40,7 +40,7 @@ pub struct GeneratorDeclaration {
 pub fn generate(
     context: Rc<SproutContext>,
     generator: &GeneratorDeclaration,
-) -> Result<Vec<(Rc<SproutContext>, EntryDeclaration)>> {
+) -> Result<Vec<BootableEntry>> {
     if let Some(matrix) = &generator.matrix {
         matrix::generate(context, matrix)
     } else if let Some(bls) = &generator.bls {

src/generators/bls.rs

@@ -1,5 +1,5 @@
 use crate::context::SproutContext;
-use crate::entries::EntryDeclaration;
+use crate::entries::{BootableEntry, EntryDeclaration};
 use crate::generators::bls::entry::BlsEntry;
 use crate::utils;
 use anyhow::{Context, Result};
@@ -42,10 +42,7 @@ fn quirk_initrd_remove_tuned(input: String) -> String {
 
 /// Generates entries from the BLS entries directory using the specified `bls` configuration and
 /// `context`. The BLS conversion is best-effort and will ignore any unsupported entries.
-pub fn generate(
-    context: Rc<SproutContext>,
-    bls: &BlsConfiguration,
-) -> Result<Vec<(Rc<SproutContext>, EntryDeclaration)>> {
+pub fn generate(context: Rc<SproutContext>, bls: &BlsConfiguration) -> Result<Vec<BootableEntry>> {
     let mut entries = Vec::new();
 
     // Stamp the path to the BLS entries directory.
@@ -116,7 +113,7 @@ pub fn generate(
         // Produce a new sprout context for the entry with the extracted values.
         let mut context = context.fork();
 
-        let title = entry.title().unwrap_or(name);
+        let title = entry.title().unwrap_or_else(|| name.clone());
         let chainload = entry.chainload_path().unwrap_or_default();
         let options = entry.options().unwrap_or_default();
 
@@ -129,7 +126,12 @@ pub fn generate(
         context.set("initrd", initrd);
 
         // Add the entry to the list with a frozen context.
-        entries.push((context.freeze(), bls.entry.clone()));
+        entries.push(BootableEntry::new(
+            name,
+            bls.entry.title.clone(),
+            context.freeze(),
+            bls.entry.clone(),
+        ));
     }
 
     Ok(entries)

src/generators/matrix.rs

@@ -1,5 +1,5 @@
 use crate::context::SproutContext;
-use crate::entries::EntryDeclaration;
+use crate::entries::{BootableEntry, EntryDeclaration};
 use anyhow::Result;
 use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
@@ -54,13 +54,13 @@ fn build_matrix(input: &BTreeMap<String, Vec<String>>) -> Vec<BTreeMap<String, S
 pub fn generate(
     context: Rc<SproutContext>,
     matrix: &MatrixConfiguration,
-) -> Result<Vec<(Rc<SproutContext>, EntryDeclaration)>> {
+) -> Result<Vec<BootableEntry>> {
     // Produce all the combinations of the input values.
     let combinations = build_matrix(&matrix.values);
     let mut entries = Vec::new();
 
     // For each combination, create a new context and entry.
-    for combination in combinations {
+    for (index, combination) in combinations.into_iter().enumerate() {
         let mut context = context.fork();
         // Insert the combination into the context.
         context.insert(&combination);
@@ -68,14 +68,18 @@ pub fn generate(
 
         // Stamp the entry title and actions from the template.
         let mut entry = matrix.entry.clone();
-        entry.title = context.stamp(&entry.title);
         entry.actions = entry
             .actions
             .into_iter()
             .map(|action| context.stamp(action))
             .collect();
         // Push the entry into the list with the new context.
-        entries.push((context, entry));
+        entries.push(BootableEntry::new(
+            index.to_string(),
+            entry.title.clone(),
+            context,
+            entry,
+        ));
     }
 
     Ok(entries)

src/main.rs

@@ -2,6 +2,9 @@
 #![feature(uefi_std)]
 
 use crate::context::{RootContext, SproutContext};
+use crate::entries::BootableEntry;
+use crate::options::SproutOptions;
+use crate::options::parser::OptionsRepresentable;
 use crate::phases::phase;
 use anyhow::{Context, Result};
 use log::info;
@@ -51,7 +54,7 @@ fn main() -> Result<()> {
     setup::init()?;
 
     // Parse the options to the sprout executable.
-    let options = options::parse().context("unable to parse options")?;
+    let options = SproutOptions::parse().context("unable to parse options")?;
 
     // Load the configuration of sprout.
     // At this point, the configuration has been validated and the specified
@@ -107,63 +110,75 @@ fn main() -> Result<()> {
     // Execute the late phase.
     phase(context.clone(), &config.phases.startup).context("unable to execute startup phase")?;
 
-    let mut staged_entries = Vec::new();
+    let mut entries = Vec::new();
 
     // Insert all the static entries from the configuration into the entry list.
-    for (_name, entry) in config.entries {
+    for (name, entry) in config.entries {
         // Associate the main context with the static entry.
-        staged_entries.push((context.clone(), entry));
+        entries.push(BootableEntry::new(
+            name,
+            entry.title.clone(),
+            context.clone(),
+            entry,
+        ));
     }
 
     // Run all the generators declared in the configuration.
-    for (_name, generator) in config.generators {
+    for (name, generator) in config.generators {
         let context = context.fork().freeze();
 
+        // We will prefix all entries with [name]-.
+        let prefix = format!("{}-", name);
+
         // Add all the entries generated by the generator to the entry list.
         // The generator specifies the context associated with the entry.
-        for entry in generators::generate(context.clone(), &generator)? {
-            staged_entries.push(entry);
+        for mut entry in generators::generate(context.clone(), &generator)? {
+            entry.prepend_name_prefix(&prefix);
+            entries.push(entry);
         }
     }
 
-    // Build a list of all the final boot entries.
-    let mut final_entries = Vec::new();
-    for (context, entry) in staged_entries {
-        let mut context = context.fork();
+    for entry in &mut entries {
+        let mut context = entry.context().fork();
         // Insert the values from the entry configuration into the
         // sprout context to use with the entry itself.
-        context.insert(&entry.values);
+        context.insert(&entry.declaration().values);
         let context = context.finalize().freeze();
-
-        // Insert the entry configuration into final boot entries with the extended context.
-        final_entries.push((context, entry));
+        // Provide the new context to the bootable entry.
+        entry.swap_context(context);
+        // Restamp the title with any values.
+        entry.restamp_title();
     }
 
     // TODO(azenla): Implement boot menu here.
     // For now, we just print all of the entries.
     info!("entries:");
-    for (index, (context, entry)) in final_entries.iter().enumerate() {
-        let title = context.stamp(&entry.title);
-        info!("  entry {}: {}", index + 1, title);
+    for (index, entry) in entries.iter().enumerate() {
+        let title = entry.context().stamp(&entry.declaration().title);
+        info!("  entry {} [{}]: {}", index, entry.name(), title);
     }
 
     // Execute the late phase.
     phase(context.clone(), &config.phases.late).context("unable to execute late phase")?;
 
     // Use the boot option if possible, otherwise pick the first entry.
-    let (context, entry) = if let Some(ref boot) = context.root().options().boot {
-        final_entries
+    let entry = if let Some(ref boot) = context.root().options().boot {
+        entries
             .iter()
-            .find(|(_context, entry)| &entry.title == boot)
+            .enumerate()
+            .find(|(index, entry)| {
+                entry.name() == boot || entry.title() == boot || &index.to_string() == boot
+            })
             .context(format!("unable to find entry: {boot}"))?
+            .1 // select the bootable entry.
     } else {
-        final_entries.first().context("no entries found")?
+        entries.first().context("no entries found")?
     };
 
     // Execute all the actions for the selected entry.
-    for action in &entry.actions {
-        let action = context.stamp(action);
-        actions::execute(context.clone(), &action)
+    for action in &entry.declaration().actions {
+        let action = entry.context().stamp(action);
+        actions::execute(entry.context().clone(), &action)
             .context(format!("unable to execute action '{}'", action))?;
     }
 

src/options.rs

@@ -1,6 +1,10 @@
+use crate::options::parser::{OptionDescription, OptionForm, OptionsRepresentable};
 use anyhow::{Context, Result, bail};
 use std::collections::BTreeMap;
 
+/// The Sprout options parser.
+pub mod parser;
+
 /// Default configuration file path.
 const DEFAULT_CONFIG_PATH: &str = "\\sprout.toml";
 
@@ -23,95 +27,58 @@ impl Default for SproutOptions {
     }
 }
 
-/// For minimalism, we don't want a full argument parser. Instead, we use
-/// a simple --xyz = xyz: None and --abc 123 = abc: Some("123") format.
-/// We also support --abc=123 = abc: Some("123") format.
-fn parse_raw() -> Result<BTreeMap<String, Option<String>>> {
-    // Collect all the arguments to Sprout.
-    // Skip the first argument which is the path to our executable.
-    let args = std::env::args().skip(1).collect::<Vec<_>>();
+/// The options parser mechanism for Sprout.
+impl OptionsRepresentable for SproutOptions {
+    /// Produce the [SproutOptions] structure.
+    type Output = Self;
 
-    // Represent options as key-value pairs.
-    let mut options = BTreeMap::new();
-
-    // Iterators makes this way easier.
-    let mut iterator = args.into_iter().peekable();
-
-    loop {
-        // Consume the next option, if any.
-        let Some(option) = iterator.next() else {
-            break;
-        };
-
-        // If the doesn't start with --, that is invalid.
-        if !option.starts_with("--") {
-            bail!("invalid option: {option}");
-        }
-
-        // Strip the -- prefix off.
-        let mut option = option["--".len()..].trim().to_string();
-
-        // An optional value.
-        let mut value = None;
-
-        // Check if the option is of the form --abc=123
-        if option.contains("=") {
-            let Some((part_key, part_value)) = option.split_once("=") else {
-                bail!("invalid option: {option}");
-            };
-
-            let part_key = part_key.to_string();
-            let part_value = part_value.to_string();
-            option = part_key;
-            value = Some(part_value);
-        }
-
-        if value.is_none() {
-            // Check for the next value.
-            let maybe_next = iterator.peek();
-
-            // If the next value isn't another option, set the value to the next value.
-            // Otherwise, it is an empty string.
-            value = if let Some(next) = maybe_next
-                && !next.starts_with("--")
-            {
-                iterator.next()
-            } else {
-                None
-            };
-        }
-
-        // Error on empty option names.
-        if option.is_empty() {
-            bail!("invalid empty option: {option}");
-        }
-
-        // Insert the option and the value into the map.
-        options.insert(option, value);
+    /// All the Sprout options that are defined.
+    fn options() -> &'static [(&'static str, OptionDescription<'static>)] {
+        &[
+            (
+                "config",
+                OptionDescription {
+                    description: "Path to Sprout configuration file",
+                    form: OptionForm::Value,
+                },
+            ),
+            (
+                "boot",
+                OptionDescription {
+                    description: "Entry to boot, bypassing the menu",
+                    form: OptionForm::Value,
+                },
+            ),
+            (
+                "help",
+                OptionDescription {
+                    description: "Display Sprout Help",
+                    form: OptionForm::Help,
+                },
+            ),
+        ]
     }
-    Ok(options)
-}
 
-/// Parse the arguments to Sprout as a [SproutOptions] structure.
-pub fn parse() -> Result<SproutOptions> {
-    // Use the default value of sprout options and have the raw options be parsed into it.
-    let mut result = SproutOptions::default();
-    let options = parse_raw().context("unable to parse options")?;
+    /// Produces [SproutOptions] from the parsed raw `options` map.
+    fn produce(options: BTreeMap<String, Option<String>>) -> Result<Self> {
+        // Use the default value of sprout options and have the raw options be parsed into it.
+        let mut result = Self::default();
 
-    for (key, value) in options {
-        match key.as_str() {
-            "config" => {
-                // The configuration file to load.
-                result.config = value.context("--config option requires a value")?;
+        for (key, value) in options {
+            match key.as_str() {
+                "config" => {
+                    // The configuration file to load.
+                    result.config = value.context("--config option requires a value")?;
+                }
+
+                "boot" => {
+                    // The entry to boot.
+                    result.boot = Some(value.context("--boot option requires a value")?);
+                }
+
+                _ => bail!("unknown option: --{key}"),
             }
-
-            "boot" => {
-                // The entry to boot.
-                result.boot = Some(value.context("--boot option requires a value")?);
-            }
-
-            _ => bail!("unknown option: --{key}"),
         }
+        Ok(result)
     }
-    Ok(result)
 }

src/options/parser.rs

@@ -0,0 +1,150 @@
+use anyhow::{Context, Result, bail};
+use std::collections::BTreeMap;
+
+/// The type of option. This disambiguates different behavior
+/// of how options are handled.
+#[derive(Debug, Clone, Ord, PartialOrd, Eq, PartialEq)]
+pub enum OptionForm {
+    /// A flag, like --verbose.
+    Flag,
+    /// A value, in the form --abc 123 or --abc=123.
+    Value,
+    /// Help flag, like --help.
+    Help,
+}
+
+/// The description of an option, used in the options parser
+/// to make decisions about how to progress.
+#[derive(Debug, Clone)]
+pub struct OptionDescription<'a> {
+    /// The description of the option.
+    pub description: &'a str,
+    /// The type of option to parse as.
+    pub form: OptionForm,
+}
+
+/// Represents a type that can be parsed from command line arguments.
+/// This is a super minimal options parser mechanism just for Sprout.
+pub trait OptionsRepresentable {
+    /// The output type that parsing will produce.
+    type Output;
+
+    /// The configured options for this type. This should describe all the options
+    /// that are valid to produce the type. The left hand side is the name of the option,
+    /// and the right hand side is the description.
+    fn options() -> &'static [(&'static str, OptionDescription<'static>)];
+
+    /// Produces the type by taking the `options` and processing it into the output.
+    fn produce(options: BTreeMap<String, Option<String>>) -> Result<Self::Output>;
+
+    /// For minimalism, we don't want a full argument parser. Instead, we use
+    /// a simple --xyz = xyz: None and --abc 123 = abc: Some("123") format.
+    /// We also support --abc=123 = abc: Some("123") format.
+    fn parse_raw() -> Result<BTreeMap<String, Option<String>>> {
+        // Access the configured options for this type.
+        let configured: BTreeMap<_, _> = BTreeMap::from_iter(Self::options().to_vec());
+
+        // Collect all the arguments to Sprout.
+        // Skip the first argument which is the path to our executable.
+        let args = std::env::args().skip(1).collect::<Vec<_>>();
+
+        // Represent options as key-value pairs.
+        let mut options = BTreeMap::new();
+
+        // Iterators makes this way easier.
+        let mut iterator = args.into_iter().peekable();
+
+        loop {
+            // Consume the next option, if any.
+            let Some(option) = iterator.next() else {
+                break;
+            };
+
+            // If the doesn't start with --, that is invalid.
+            if !option.starts_with("--") {
+                bail!("invalid option: {option}");
+            }
+
+            // Strip the -- prefix off.
+            let mut option = option["--".len()..].trim().to_string();
+
+            // An optional value.
+            let mut value = None;
+
+            // Check if the option is of the form --abc=123
+            if option.contains("=") {
+                let Some((part_key, part_value)) = option.split_once("=") else {
+                    bail!("invalid option: {option}");
+                };
+
+                let part_key = part_key.to_string();
+                let part_value = part_value.to_string();
+                option = part_key;
+                value = Some(part_value);
+            }
+
+            // Error on empty option names.
+            if option.is_empty() {
+                bail!("invalid empty option");
+            }
+
+            // Find the description of the configured option, if any.
+            let Some(description) = configured.get(option.as_str()) else {
+                bail!("invalid option: --{option}");
+            };
+
+            // Check if the option requires a value and error if none was provided.
+            if description.form == OptionForm::Value && value.is_none() {
+                // Check for the next value.
+                let maybe_next = iterator.peek();
+
+                // If the next value isn't another option, set the value to the next value.
+                // Otherwise, it is an empty string.
+                value = if let Some(next) = maybe_next
+                    && !next.starts_with("--")
+                {
+                    iterator.next()
+                } else {
+                    None
+                };
+            }
+
+            // If the option form does not support a value and there is a value, error.
+            if description.form != OptionForm::Value && value.is_some() {
+                bail!("option --{} does not take a value", option);
+            }
+
+            // Handle the --help flag case.
+            if description.form == OptionForm::Help {
+                // Generic configured options output.
+                println!("Configured Options:");
+                for (name, description) in &configured {
+                    println!(
+                        "  --{}{}: {}",
+                        name,
+                        if description.form == OptionForm::Value {
+                            " <value>"
+                        } else {
+                            ""
+                        },
+                        description.description
+                    );
+                }
+                // Exit because the help has been displayed.
+                std::process::exit(1);
+            }
+
+            // Insert the option and the value into the map.
+            options.insert(option, value);
+        }
+        Ok(options)
+    }
+
+    /// Parses the program arguments as a [Self::Output], calling [Self::parse_raw] and [Self::produce].
+    fn parse() -> Result<Self::Output> {
+        // Parse the program arguments into a raw map.
+        let options = Self::parse_raw().context("unable to parse options")?;
+        // Produce the options from the map.
+        Self::produce(options)
+    }
+}

src/utils.rs

@@ -12,7 +12,7 @@ pub mod framebuffer;
 /// Support code for the media loader protocol.
 pub mod media_loader;
 
-/// Parses the input [path] as a [DevicePath].
+/// Parses the input `path` as a [DevicePath].
 /// Uses the [DevicePathFromText] protocol exclusively, and will fail if it cannot acquire the protocol.
 pub fn text_to_device_path(path: &str) -> Result<PoolDevicePath> {
     let path = CString16::try_from(path).context("unable to convert path to CString16")?;
@@ -27,7 +27,7 @@ pub fn text_to_device_path(path: &str) -> Result<PoolDevicePath> {
         .context("unable to convert text to device path")
 }
 
-/// Grabs the root part of the [path].
+/// Grabs the root part of the `path`.
 /// For example, given "PciRoot(0x0)/Pci(0x4,0x0)/NVMe(0x1,00-00-00-00-00-00-00-00)/HD(1,MBR,0xBE1AFDFA,0x3F,0xFBFC1)/\EFI\BOOT\BOOTX64.efi"
 /// it will give "PciRoot(0x0)/Pci(0x4,0x0)/NVMe(0x1,00-00-00-00-00-00-00-00)/HD(1,MBR,0xBE1AFDFA,0x3F,0xFBFC1)"
 pub fn device_path_root(path: &DevicePath) -> Result<String> {
@@ -52,7 +52,7 @@ pub fn device_path_root(path: &DevicePath) -> Result<String> {
     Ok(path)
 }
 
-/// Grabs the part of the [path] after the root.
+/// Grabs the part of the `path` after the root.
 /// For example, given "PciRoot(0x0)/Pci(0x4,0x0)/NVMe(0x1,00-00-00-00-00-00-00-00)/HD(1,MBR,0xBE1AFDFA,0x3F,0xFBFC1)/\EFI\BOOT\BOOTX64.efi"
 /// it will give "\EFI\BOOT\BOOTX64.efi"
 pub fn device_path_subpath(path: &DevicePath) -> Result<String> {
@@ -92,8 +92,8 @@ pub struct ResolvedPath {
     pub filesystem_handle: Handle,
 }
 
-/// Resolve a path specified by [input] to its various components.
-/// Uses [default_root_path] as the base root if one is not specified in the path.
+/// Resolve a path specified by `input` to its various components.
+/// Uses `default_root_path` as the base root if one is not specified in the path.
 /// Returns [ResolvedPath] which contains the resolved components.
 pub fn resolve_path(default_root_path: &DevicePath, input: &str) -> Result<ResolvedPath> {
     let mut path = text_to_device_path(input).context("unable to convert text to path")?;
@@ -137,9 +137,9 @@ pub fn resolve_path(default_root_path: &DevicePath, input: &str) -> Result<Resol
     })
 }
 
-/// Read the contents of a file at the location specified with the [input] path.
+/// Read the contents of a file at the location specified with the `input` path.
 /// Internally, this uses [resolve_path] to resolve the path to its various components.
-/// [resolve_path] is passed the [default_root_path] which should specify a base root.
+/// [resolve_path] is passed the `default_root_path` which should specify a base root.
 ///
 /// This acquires exclusive protocol access to the [SimpleFileSystem] protocol of the resolved
 /// filesystem handle, so care must be taken to call this function outside a scope with

src/utils/media_loader.rs

@@ -46,8 +46,8 @@ pub struct MediaLoaderHandle {
 impl MediaLoaderHandle {
     /// The behavior of this function is derived from how Linux calls it.
     ///
-    /// Linux calls this function by first passing a NULL [buffer].
-    /// We must set the size of the buffer it should allocate in [buffer_size].
+    /// Linux calls this function by first passing a NULL `buffer`.
+    /// We must set the size of the buffer it should allocate in `buffer_size`.
     /// The next call will pass a buffer of the right size, and we should copy
     /// data into that buffer, checking whether it is safe to copy based on
     /// the buffer size.
@@ -137,7 +137,7 @@ impl MediaLoaderHandle {
         Ok(false)
     }
 
-    /// Registers the provided [data] with the UEFI stack as media loader.
+    /// Registers the provided `data` with the UEFI stack as media loader.
     /// This uses a special device path that other EFI programs will look at
     /// to load the data from.
     pub fn register(guid: Guid, data: Box<[u8]>) -> Result<MediaLoaderHandle> {