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](RELEASING.md).
add basic development guide 2025-10-19 21:53:52 -07:00			`# 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.`

chore(code): split much of the efi support code to crates/eficore 2025-11-03 20:47:21 -05:00			`## Crate Structure`

			`Sprout is split into multiple crates:`

docs(development): list every crate in the crate structure 2026-09-26 20:26:57 -07:00			- `edera-sprout-boot` at `crates/boot`: Bootloader entrypoint for Sprout.
			- `edera-sprout-bls` at `crates/bls`: Parsing and sorting of Boot Loader Specification entries.
chore(code): sbat section generator build tool 2025-11-03 22:37:06 -05:00			- `edera-sprout-build` at `crates/build`: Build logic for Sprout.
chore(code): split much of the efi support code to crates/eficore 2025-11-03 20:47:21 -05:00			- `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.
docs(development): list every crate in the crate structure 2026-09-26 20:26:57 -07:00			- `edera-sprout-parsing` at `crates/parsing`: Value stamping and other parsing helpers for Sprout.
chore(code): split much of the efi support code to crates/eficore 2025-11-03 20:47:21 -05:00
			`It is intended that overtime Sprout will be split into even more crates.`

add basic development guide 2025-10-19 21:53:52 -07:00			`## 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.`
feat(hack): add scripts to drive the dev environment headless 2026-10-04 10:21:13 -07:00
			`### ./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`.
docs: add CLAUDE.md and document the release process 2026-10-04 12:16:14 -07:00
			`## Releasing`

			`Maintainers cut releases as described in [RELEASING.md](RELEASING.md).`