docs: add binary distribution reference and expand installation options

mitchmindtree · mitchmindtree · commit a3421947f358 · 2026-04-28T16:23:13.000+10:00
Add guides/12_binary_distribution.md documenting release artifact
structure, target platforms, archive contents, plugin versioning, and
packaging guidelines for downstream distributors (re: leo#29337 section 5,
leo#29355).

Expand the installation page with a `cargo binstall` tab and rewrite the
pre-built binaries tab to cover all 5 supported targets with the new
per-crate artifact naming convention.

Update plugin docs and guides overview with cross-links to the new page.
diff --git a/documentation/cli/18_plugins.md b/documentation/cli/18_plugins.md
@@ -59,17 +59,17 @@ If the plugin binary is not found, Leo prints an error:
 
 ### Installing Plugins
 
-Plugins can be installed via `cargo install`:
+Plugins can be installed via `cargo install` or `cargo binstall`:
 
 ```bash
 cargo install leo-fmt leo-lsp
+# or, to download pre-built binaries:
+cargo binstall leo-fmt leo-lsp
 ```
 
-Pre-built binaries are also available from [Leo releases](https://github.com/ProvableHQ/leo/releases). Release archives include plugin binaries alongside `leo`.
+Pre-built binaries are also available from [Leo releases](https://github.com/ProvableHQ/leo/releases). Each plugin crate is released independently under its own git tag (e.g. `leo-fmt-v1.0.0`).
 
-:::note
-Plugin distribution is evolving. Tag-triggered releases and `cargo binstall` support are in progress. See [Leo #29355](https://github.com/ProvableHQ/leo/pull/29355) for the latest details.
-:::
+For details on release artifacts, target platforms, and packaging guidelines, see the [Binary Distribution Reference](../guides/12_binary_distribution.md).
 
 Running `leo update` will also attempt to update bundled plugins like `leo-fmt` on a best-effort basis.
 
diff --git a/documentation/getting_started/01_installation.md b/documentation/getting_started/01_installation.md
@@ -18,6 +18,7 @@ If you'd like to try Leo without installing it locally on your machine, check ou
 <Tabs defaultValue="cargo"
 values={[
 { label: 'Cargo', value: 'cargo' },
+{ label: 'cargo binstall', value: 'binstall' },
 { label: 'Pre-Built Binaries', value: 'prebuilt' },
 { label: 'Build from Source', value: 'source' },
 ]}>
@@ -35,27 +36,71 @@ cargo install leo-lang leo-fmt
 
 This will install the `leo` and `leo-fmt` executables at `~/.cargo/bin/`.
 </TabItem>
-<TabItem value="prebuilt">
+<TabItem value="binstall">
 
-## MacOS (Apple Silicon):
+## Install `cargo-binstall`
 
-1.  **[Download Leo for Apple Silicon (MacOS)](https://github.com/ProvableHQ/leo/releases/latest/download/leo.zip)**
-2.  Extract the `.zip` file
-3.  Open a terminal and navigate to the extracted directory.
-4.  Run `chmod +x leo leo-fmt` to make the files executable
-5.  Move both binaries to `/usr/local/bin` to use them system wide.
+[`cargo-binstall`](https://github.com/cargo-bins/cargo-binstall) downloads pre-compiled binaries instead of building from source, cutting install time from minutes to seconds.
 
-        mv leo leo-fmt /usr/local/bin
+```bash
+cargo install cargo-binstall
+```
 
-6.  Run `leo --version` to confirm installation
+## Install Leo
 
-:::note
-Release archives now include plugin binaries (such as `leo-fmt`) alongside `leo`. Distribution details are subject to change - see [Leo #29355](https://github.com/ProvableHQ/leo/pull/29355).
+```bash
+cargo binstall leo-lang leo-fmt
+```
+
+To install a specific version:
+
+```bash
+cargo binstall leo-lang@4.0.1 leo-fmt@1.0.0
+```
+
+:::tip
+If no pre-built binary is available for your platform, `cargo binstall` falls back to building from source automatically.
 :::
 
-## Other Platforms:
+</TabItem>
+<TabItem value="prebuilt">
+
+## Download Pre-Built Binaries
+
+Pre-built binaries are available for every release from [GitHub Releases](https://github.com/ProvableHQ/leo/releases).
+
+Each release publishes a ZIP archive per platform:
 
-- **[Browse all Leo releases](https://github.com/ProvableHQ/leo/releases)**
+| Platform | Target |
+|---|---|
+| Linux (x86_64, glibc) | `x86_64-unknown-linux-gnu` |
+| Linux (x86_64, musl) | `x86_64-unknown-linux-musl` |
+| macOS (Intel) | `x86_64-apple-darwin` |
+| macOS (Apple Silicon) | `aarch64-apple-darwin` |
+| Windows (x86_64) | `x86_64-pc-windows-msvc` |
+
+Archives are named `leo-lang-v{version}-{target}.zip` (e.g. `leo-lang-v4.0.1-aarch64-apple-darwin.zip`).
+
+## Install
+
+1. Download the ZIP for your platform from the [latest release](https://github.com/ProvableHQ/leo/releases).
+2. Extract the archive.
+3. On macOS/Linux, make the binaries executable and move them onto your PATH:
+
+```bash
+chmod +x leo leo-fmt
+mv leo leo-fmt /usr/local/bin/
+```
+
+4. Verify the installation:
+
+```bash
+leo --version
+```
+
+:::note
+Plugin binaries such as `leo-fmt` are released separately under their own crate tags (e.g. `leo-fmt-v1.0.0`). Download the matching plugin archives from the same [releases page](https://github.com/ProvableHQ/leo/releases).
+:::
 
 </TabItem>
 <TabItem value="source">
@@ -98,3 +143,7 @@ leo
 
 </TabItem>
 </Tabs>
+
+---
+
+For distribution maintainers and detailed artifact information, see the [Binary Distribution Reference](../guides/12_binary_distribution.md).
diff --git a/documentation/guides/00_overview.md b/documentation/guides/00_overview.md
@@ -32,6 +32,8 @@ There's a lot to learn about Leo! To help tame the complexity, we've put togethe
 
 - [**ABI Generation**](./10_abi.md) - Learn about the ABI format and type lowering for SDK integration.
 
+- [**Binary Distribution Reference**](./12_binary_distribution.md) - Release artifacts, target platforms, and packaging guidelines for distributors.
+
 ## Migration
 
 - [**Migrating from Leo 3.5 to 4.0**](./11_migration_3_5_to_4_0.md) - A complete guide to updating your programs for Leo 4.0.
diff --git a/documentation/guides/12_binary_distribution.md b/documentation/guides/12_binary_distribution.md
@@ -0,0 +1,94 @@
+---
+id: binary-distribution
+title: Binary Distribution Reference
+sidebar_label: Binary Distribution
+---
+
+[general tags]: # "guides, packaging, distribution, releases, binaries"
+
+# Binary Distribution Reference
+
+This page documents Leo's release artifact structure and packaging guidelines. It is intended for community packagers, downstream distributors, and advanced users who want to understand how Leo binaries are published.
+
+For installation instructions, see [Getting Started - Installation](../getting_started/01_installation.md).
+
+## Release Model
+
+Leo uses a per-crate release model. Each publishable crate in the [Leo repository](https://github.com/ProvableHQ/leo) is released independently via git tags matching the pattern `{crate-name}-v{version}` (e.g. `leo-lang-v4.0.1`, `leo-fmt-v1.0.0`).
+
+When a tag is pushed, CI builds cross-platform binaries and publishes them as a GitHub Release under that tag.
+
+## Release URL Pattern
+
+GitHub Releases are published at:
+
+```
+https://github.com/ProvableHQ/leo/releases/tag/{crate-name}-v{version}
+```
+
+Each release contains one ZIP artifact per supported target, named:
+
+```
+{crate-name}-v{version}-{target}.zip
+```
+
+For example, `leo-lang-v4.0.1` produces:
+
+- `leo-lang-v4.0.1-x86_64-unknown-linux-gnu.zip`
+- `leo-lang-v4.0.1-x86_64-unknown-linux-musl.zip`
+- `leo-lang-v4.0.1-x86_64-apple-darwin.zip`
+- `leo-lang-v4.0.1-aarch64-apple-darwin.zip`
+- `leo-lang-v4.0.1-x86_64-pc-windows-msvc.zip`
+
+## Supported Targets
+
+| Target Triple | OS | Architecture | Notes |
+|---|---|---|---|
+| `x86_64-unknown-linux-gnu` | Linux | x86_64 | Dynamically linked against glibc |
+| `x86_64-unknown-linux-musl` | Linux | x86_64 | Statically linked (Alpine, scratch containers, etc.) |
+| `x86_64-apple-darwin` | macOS | Intel | |
+| `aarch64-apple-darwin` | macOS | Apple Silicon | |
+| `x86_64-pc-windows-msvc` | Windows | x86_64 | |
+
+## Archive Contents
+
+Each ZIP contains all binaries produced by the crate. Current crates and their binaries:
+
+| Crate | Binary | Description |
+|---|---|---|
+| `leo-lang` | `leo` | The Leo compiler and CLI |
+| `leo-fmt` | `leo-fmt` | Leo source code formatter |
+| `leo-lsp` | `leo-lsp` | Language server for editor integration |
+
+Future plugin crates will follow the same pattern.
+
+## Plugin Versioning
+
+Plugin crates (`leo-fmt`, `leo-lsp`) are versioned independently from `leo-lang`. Each crate has its own git tag and release cadence, allowing tooling updates to ship without requiring a new compiler release.
+
+When packaging Leo, ensure the installed plugin versions are compatible with the installed `leo-lang` version.
+
+:::note
+A machine-readable `releases.toml` manifest is planned to track version compatibility between `leo-lang` and its plugins. Until it is available, consult the [Leo releases page](https://github.com/ProvableHQ/leo/releases) for release notes on compatible version sets.
+:::
+
+## Packaging Guidelines
+
+Downstream packages (Homebrew taps, AUR PKGBUILDs, distribution packages, etc.) should follow these guidelines:
+
+- **Install all binaries together.** A complete Leo installation includes `leo`, `leo-fmt`, and `leo-lsp`. Users expect the full toolchain.
+- **Place all binaries on `PATH`.** Leo discovers plugins by searching `PATH` for executables matching the `leo-<name>` convention.
+- **Preserve the `leo-<name>` naming convention.** Plugin dispatch depends on it - renaming `leo-fmt` to something else will break `leo fmt`.
+- **Track compatible versions across crates.** Since crates are released independently, packages should pin to known-compatible version sets.
+
+## `cargo binstall` Support
+
+Each binary crate includes `[package.metadata.binstall]` configuration in its `Cargo.toml`, pointing to the GitHub Release artifact URL template. This means `cargo binstall` resolves the correct platform ZIP automatically:
+
+```bash
+cargo binstall leo-lang
+cargo binstall leo-fmt
+cargo binstall leo-lsp
+```
+
+If no pre-built binary is available for the user's platform, `cargo binstall` falls back to building from source via `cargo install`.
