sprout/DEVELOPMENT.md

Sprout Development Guide

This guide is a work in progress.

Development Setup

You can use any Rust development environment to develop Sprout. Rustup is recommended as the Rust toolchain manager to manage Rust versions and targets. We currently only support x86_64-unknown-uefi and aarch64-unknown-uefi targets.

To test your changes in QEMU, please run ./hack/dev/boot.sh, you can specify x86_64 or aarch64 as an argument to boot.sh to boot the specified architecture.

Crate Structure

Sprout is split into multiple crates:

• edera-sprout-boot at crates/boot: Bootloader entrypoint for Sprout.
• edera-sprout-bls at crates/bls: Parsing and sorting of Boot Loader Specification entries.
• edera-sprout-build at crates/build: Build logic for Sprout.
• edera-sprout-config at crates/config: Serialization structures for the Sprout configuration file.
• edera-sprout-eficore at crates/eficore: Core library for Sprout EFI code.
• edera-sprout-parsing at crates/parsing: Value stamping and other parsing helpers for Sprout.

It is intended that overtime Sprout will be split into even more crates.

Hack Scripts

You can use the ./hack scripts to run common development tasks:

./hack/build.sh

Builds the Sprout binary for the target that would support your current machine.

./hack/assemble.sh

Builds both x86_64 and aarch64 binaries into target/assemble.

./hack/clean.sh

Cleans the target directory and any docker images that were built.

./hack/format.sh

Formats the code using rustfmt and shell scripts with shfmt.

./hack/autofix.sh

Applies Clippy and rustfmt fixes to the code, and formats shell scripts with shfmt.

Dev Scripts

./hack/dev/build.sh

Build Sprout as OCI images using Docker, including a kernel, initramfs, xen, and other supporting files.

./hack/dev/boot.sh

Boot Sprout's dev environment using QEMU for testing. This will let you test your changes in a real environment booting Alpine Linux with an initramfs.

./hack/dev/run

Scripts to drive the dev environment without a terminal or a window, which suits automation and coding agents. QEMU runs in the background with a QMP socket, and its consoles are written to target/run/<arch>/. Only one run per architecture at a time, and the scripts need python3 or socat.

• start.sh [arch]: Builds and starts QEMU headless. SPROUT_CONFIG_NAME defaults to graphical.
• screenshot.sh [out.png]: Saves a PNG of the display (QEMU 7.1 or newer) and prints the path.
• key.sh <qcode>...: Presses keys such as down, up, ret or ctrl+alt+delete.
• wait-serial.sh <regex> [seconds]: Waits for text on the firmware or Linux console.
• qmp.sh <json>...: Sends raw QMP commands.
• status.sh and stop.sh: Show the state of QEMU, and stop it.
• smoke.sh [arch]: Starts, drives the graphical menu, waits for the Linux shell and stops.

boot.sh supports this with QEMU_HEADLESS, QEMU_QMP, QEMU_SERIAL_FILE, QEMU_CONSOLE_FILE and QEMU_EXTRA_ARGS.

Releasing

Maintainers cut releases as described in RELEASING.md.