Skip to content

Latest commit

 

History

History
111 lines (81 loc) · 4.02 KB

AGENTS.md

File metadata and controls

111 lines (81 loc) · 4.02 KB

AGENTS.md

Quickemu is a Bash wrapper around QEMU that automates VM creation for ~1000 operating systems (Linux, macOS, Windows, BSDs). Two main tools: quickget downloads ISOs and creates configs; quickemu launches VMs with optimised hardware detection.

Project structure

quickemu        # Main VM launcher script (Bash)
quickget        # OS downloader and config generator (Bash)
quickreport     # System diagnostics tool (Bash)
chunkcheck      # Download verification utility (Bash)
flake.nix       # Nix flake for packaging
package.nix     # Nix package definition
devshell.nix    # Development environment

Development environment

nix develop                    # Enter devshell with all dependencies
direnv reload                  # Update .direnv/bin/quickemu for testing

The devshell patches quickemu to use Nix store paths for OVMF and Samba, writing to .direnv/bin/quickemu.

Build and test commands

  • Lint scripts: shellcheck quickemu quickget quickreport chunkcheck
  • Test quickget URLs: ./quickget --check <os> [release] [edition]
  • Test ARM64 downloads: ./quickget --arch arm64 --check <os> [release] [edition]
  • Test all architectures: ./quickget --check-all-arch <os> [release] [edition]
  • List all supported OSes: ./quickget --list
  • Run VM: ./quickemu --vm <name>.conf

Code style

All scripts are Bash 4.0+ with ShellCheck compliance.

File Indent Notes
quickemu 2 spaces Main VM launcher
quickget 4 spaces OS definitions and download logic

General conventions:

  • UTF-8, LF line endings, final newline
  • Trim trailing whitespace (except Markdown)
  • Functions use function name() { syntax
  • Many functions are invoked indirectly via dynamic dispatch - SC2317 is disabled globally in quickget

Adding a new OS to quickget

Follow the guide in the wiki. Each OS requires:

  1. Entry in os_info() case statement
  2. releases_<os>() function returning available versions
  3. editions_<os>() function if multiple editions exist
  4. arch_<os>() function if ARM64 is supported (defaults to amd64 only if omitted)
  5. Download URL construction logic

Commit message format

Commits must follow Conventional Commits. PR titles are validated against this format.

Common prefixes:

  • fix(quickget): - Fix distro downloads, update editions/releases
  • fix(quickemu): - Fix VM configuration or runtime issues
  • feat(quickget): - Add new OS support
  • feat(quickemu): - Add new VM features
  • ci: - CI/workflow changes
  • docs: - Documentation updates

Examples from recent history:

fix(quickget): update Zorin OS download method and editions
fix(quickget): handle Solus Xfce beta naming for older releases
fix(quickget): remove Athena OS (no longer getting updates)

Pull request guidelines

  • PR titles must match Conventional Commits format (enforced by CI)
  • Single-commit PRs: commit message must match PR title
  • Run shellcheck before submitting
  • Test affected OS downloads with ./quickget --check <os> <release>

CI workflows

Workflow Trigger Purpose
lint-shellcheck PR ShellCheck with severity: warning
lint-pr PR Validates PR title matches Conventional Commits
test-quickget PR Tests quickget functionality
test-build-quickemu PR Build verification
flake-checker PR Nix flake validation

Platform support

  • Host: Linux (x86_64, aarch64), macOS (x86_64, aarch64)
  • Guest: x86_64 (default), aarch64 (set arch="aarch64" in VM config)
  • ARM64 guests use AAVMF firmware and virt machine type
  • Cross-arch emulation uses TCG (no KVM acceleration)
  • OVMF/UEFI firmware: Linux only
  • Bash 4.0+ required (explicit version check at runtime)

Key dependencies

Runtime: qemu, cdrtools, curl, jq, spice-gtk, swtpm, samba, zsync Linux-specific: OVMF (x86_64 guests), AAVMF (aarch64 guests), usbutils, mesa-demos