[Proposal] Improve Leo's binary distribution

[mitchmindtree]

Context

Leo currently distributes prebuilt binaries via GitHub releases and supports cargo install from source.

With the plugin system landing (PR #29245), Leo will ship multiple binaries (leo + leo-fmt + future plugins) that need to be distributed as a cohesive set. The existing leo update self-update mechanism (#29282) conflicts with immutable environments and proper package managers.

This proposal outlines a phased plan to improve Leo's distribution story end-to-end.

Phases

• 1. Land CLI Plugins PR
• 2. Improve Release Automation with Per-Crate Git Tags
• 3. Add cargo-binstall Support
• 4. Improve leo.nix with Easier Version Selection
• 5. Document Leo's Binary Publishing Details
• 6. Add Leo to Major Package Managers
• 7. Remove leo update

---

1. Land CLI Plugins PR

PR: #29245

The foundation for everything else. Introduces leo-<name> plugin dispatch and migrates leo fmt to a standalone leo-fmt binary. GH release workflow already updated to bundle both binaries per platform.

Status: PR open, ready for review.

Follow-ups (covered in later sections):

• Update leo.nix to include plugins.
• Update leo-docs-source with plugin guide.

---

2. Improve Release Automation with Per-Crate Git Tags

Issue: #29189

Decouple release cadence so tooling (formatter, LSP) can ship independently from the compiler. A single generic CI workflow detects per-crate tags (e.g. leo-fmt-1.0.1), verifies version matches Cargo.toml, publishes to crates.io, and builds cross-platform release binaries.

Key elements:

• Per-crate git tags trigger per-crate releases.
• Append-only releases.toml records compatibility info (snarkVM revision, etc.).
• Phase 1: Decouple leo-fmt. Compiler-core crates remain lockstep.
• Generic workflow - adding a new workspace binary "just works".

This is prerequisite for downstream packagers to reliably track releases.

---

3. Add cargo-binstall Support

Add [package.metadata.binstall] to binary crate Cargo.toml files with URL templates pointing at GH release artifacts.

Benefits:

• cargo binstall leo-lang leo-fmt downloads prebuilt binaries in seconds, avoiding the lengthy from-source builds (~10+ min with LTO).
• Version pinning: cargo binstall leo-lang@4.0.1.
• Falls back to cargo install (source build) if no binary found.
• Works on every platform with a Rust toolchain, including Windows.
• Near-zero maintenance - just keep GH release naming consistent.

Note: users need to be mindful to switch all plugin binaries together when switching versions, since cargo-binstall installs per-crate.

---

4. Improve leo.nix with Easier Version Selection

Issue: ProvableHQ/leo.nix#18

Currently leo.nix builds from source. Add leo-bin and snarkos-bin derivations that fetch upstream prebuilt binaries directly, with an interface for selecting arbitrary versions - similar to how rust-overlay provides arbitrary Rust versions.

Key elements:

• leo-bin derivation fetching GH release artifacts by version.
• Shorthand latest for latest tagged release.
• Shorthand nightly for latest successful master build (if applicable).
• Include plugin binaries (leo-fmt, etc.) alongside leo.

This gives Nix users the fastest install path and proper version switching via flake inputs.

---

5. Document Leo's Binary Publishing Details

Add documentation to leo-docs-source covering how Leo binaries are published, so that:

• Users know what installation options exist and how to use them.
• Community members can package Leo for managers we don't officially support (Gentoo ebuilds, Void Linux, FreeBSD ports, etc.) without reverse-engineering the release process.

Documentation should cover:

• GH release URL pattern and artifact naming convention.
• List of target triples and their corresponding artifacts.
• Which binaries are included in each zip (leo, leo-fmt, future plugins).
• How plugin versioning relates to the main Leo version (especially post-[Proposal] Independent release cadence for workspace crates #29189).
• Minimum expectations for downstream packages (all binaries should be installed together, placed on PATH).
• How releases.toml can be used to determine version compatibility.

---

6. Add Leo to Major Package Managers

Recommended

Manager	Platforms	Binary Sets	Auto-pickup	Approachability
Homebrew tap	macOS, Linux	Good (cask bundles bins)	Excellent (GH Actions)	Easy
AUR	Arch + derivatives	Good (PKGBUILD)	Good (Renovate/Actions)	Easy
nixpkgs	NixOS, any w/ Nix	Excellent	Community bot PRs	Moderate

Homebrew tap - Create ProvableHQ/homebrew-leo with a cask downloading the GH release zip. A GH Actions workflow on the leo repo triggers a bump PR on the tap each release. Cask naturally bundles all binaries from the zip. Largest reach for macOS developers, also works on Linux via Linuxbrew.

AUR (leo-bin) - Single PKGBUILD that downloads the GH release binary zip for linux-gnu. -bin suffix convention tells users it's prebuilt. Automate updates with Renovate bot or GH Actions pushing to AUR on release. Arch/Manjaro devs expect tools to be on AUR.

nixpkgs - The leo.nix flake already covers Nix power users. Submitting to nixpkgs adds discoverability (nix search nixpkgs leo), faster installs via the nixpkgs binary cache, and reaches users who don't know about the flake. Separate effort with minor PR review overhead, best done after leo.nix stabilizes post-plugins.

Notable mentions - omitted for now

The following could be added later if demand shows:

Manager	Why omitted
APT / PPA	High maintenance - GPG key management, repo hosting, per-distro builds.
Snap	classic confinement needed for compiler file access, requires Snap Store review.
Flatpak	Designed for desktop GUI apps. Sandbox model fights compiler file access. No built-in auto-update.
Scoop (Windows)	Windows users can use WSL + any Linux method, or cargo-binstall natively.
WinGet (Windows)	Same as Scoop. Strict review process adds friction.
mise / asdf	Good version-switching UX, but cargo-binstall covers version pinning.

The binary publishing documentation (section 5) is designed to make it straightforward for community members to add Leo to their preferred package manager without our involvement. If someone wants Leo on Gentoo, Void, FreeBSD ports, Chocolatey, etc., they should be able to follow the docs and do it themselves.

---

7. Remove leo update

Issue: #29282

Once Leo is available through proper package managers and cargo-binstall, the self-update mechanism becomes redundant and actively harmful in immutable environments (NixOS, Guix, Docker, Flatpak, Snap).

• Remove the leo update subcommand.
• Keep the check_for_updates() notification mechanism that informs users when a new version is available, pointing them to their package manager or GH releases.

This should be the final step, after the package manager options are in place.

[vicsn]

Overall I think this looks great!

Personally not sure about the value of Nix support - are any partners using Nix? But if it's very easy for you and you are using Nix yourself then why not. :)

My only real hesitancy is regarding "Add Leo to Major Package Managers". This is a long-term commitment, adds work to the release process, and I think we can expect developers to reach cargo or github directly. I have a feeling we can leave this as future work.

Happy to join a future sync to discuss synchronously if needed!

[JoshuaBatty]

Nice one, sounds like an extremely reasonable approach that drastically improves our current method without reinventing yet another package manager.