Hyrum¶
Hyrum bulk-runs a check (typically lint or unit tests) across many charm repositories, optionally patching one of their dependencies first.
The primary use case is pointing every charm’s ops dependency at a development branch of the operator repository to find out which charms break before shipping the change. Named after Hyrum’s Law: once you have enough users, every observable behaviour of your code is depended on by somebody.
Warning
Hyrum executes third-party code on your machine. Unit tests — and, in principle, even lint hooks — run with your user’s privileges: anything you can do, a test can do. Charm test suites may not mock every side effect, so a test may write or delete files anywhere your user can reach, install packages, modify crontab, download arbitrary content, or reach out to the network.
Always run hyrum in an isolated VM (for example, Multipass or an LXD virtual machine): create a throwaway instance, install hyrum inside it, and dispose of the instance when you are done. Alternatively, run hyrum in the repository’s workshop, which runs the checks in a container as a user that cannot modify the host. Do not run checks on your workstation, laptop, or any host holding data you care about.
Install¶
uv tool install --prerelease=allow hyrum
Quick start¶
# Clone every repository listed in ./charms.csv into ~/.cache/hyrum/charms:
hyrum get-charms
# Run tox -e unit across every charm, with ops patched to a development branch:
hyrum check unit --patch 'ops @ canonical:fix/my-change' --workers 8
# Run without patching any dependency (test charms as they are pinned):
hyrum check unit --no-patch
# Diff the last two runs to see what the patch changed:
hyrum compare ~/.cache/hyrum/results/unit.auto.prev.json \
~/.cache/hyrum/results/unit.auto.json
# Print a saved run again, without rerunning it:
hyrum show ~/.cache/hyrum/results/unit.auto.json
# Remove the build artefacts the runs left behind, keeping the checkouts:
hyrum clean
In this documentation¶
A hands-on walkthrough: populate a charms directory, run hyrum, and read the report.
Task-focused guides: install, filter runs, patch a dependency, triage results, and reclaim disk space.
CLI options, hyrum.toml configuration, output statuses, and what hyrum supports.
Background on Hyrum’s Law and the design decisions behind hyrum.
This documentation uses the Diátaxis documentation structure.
Project and community¶
Hyrum is an open source project (Apache 2.0 license) maintained by the Canonical Charm Tech team.