diff --git a/documentation/cli/00_overview.md b/documentation/cli/00_overview.md index 712f665bf..ee8657d9f 100644 --- a/documentation/cli/00_overview.md +++ b/documentation/cli/00_overview.md @@ -41,7 +41,8 @@ You can print the list of commands by running `leo --help` - [`update`](./14_update.md) - Update to the latest version of Leo. - [`upgrade`](./15_upgrade.md) - Upgrade a deployed program on the Aleo network. - [`synthesize`](./16_synthesize.md) - Generate proving and verifying keys for a program. -- [`fmt`](./17_fmt.md) - Format Leo source files. +- [`fmt`](./17_fmt.md) - Format Leo source files. *(plugin)* +- [`plugins`](./18_plugins.md) - List installed CLI plugins. ## Universal Flags diff --git a/documentation/cli/14_update.md b/documentation/cli/14_update.md index a2ced4aae..1143275f0 100644 --- a/documentation/cli/14_update.md +++ b/documentation/cli/14_update.md @@ -24,6 +24,8 @@ Checking latest released version... v3.1.0 Leo is already on the latest version ``` +`leo update` also updates bundled plugins (such as `leo-fmt`) on a best-effort basis. + If you'd like to install a specific version of Leo, you can do so by passing the `--name` flag: ```bash diff --git a/documentation/cli/17_fmt.md b/documentation/cli/17_fmt.md index e21fec82a..07be13008 100644 --- a/documentation/cli/17_fmt.md +++ b/documentation/cli/17_fmt.md @@ -6,10 +6,14 @@ toc_min_heading_level: 2 toc_max_heading_level: 2 --- -[general tags]: # "cli, leo_fmt, fmt, format, formatting" +[general tags]: # "cli, leo_fmt, fmt, format, formatting, plugin" # `leo fmt` +:::info +`leo-fmt` is distributed as a **plugin** rather than a built-in command. When you run `leo fmt`, the Leo CLI delegates to the `leo-fmt` binary on your PATH. You can also invoke `leo-fmt` directly. +::: + Format Leo source files, automatically formatting all `.leo` files in your project. ```bash @@ -24,6 +28,26 @@ You can also format specific files or directories: leo fmt src/main.leo ``` +## Installation + +Install `leo-fmt` alongside Leo: + +```bash +cargo install leo-fmt +``` + +Pre-built binaries are available from [Leo releases](https://github.com/ProvableHQ/leo/releases). Release archives include `leo-fmt` alongside the main `leo` binary. + +:::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. +::: + +To verify the plugin is installed and visible to Leo: + +```bash +leo plugins +``` + ## Check Mode To check if files are formatted without modifying them, use the `--check` flag. This prints a colored diff of any unformatted files and exits with code 1 if changes are needed: diff --git a/documentation/cli/18_plugins.md b/documentation/cli/18_plugins.md new file mode 100644 index 000000000..8be52b5ef --- /dev/null +++ b/documentation/cli/18_plugins.md @@ -0,0 +1,82 @@ +--- +id: cli_plugins +title: "" +sidebar_label: Plugins +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +[general tags]: # "cli, leo_plugins, plugins, extensions" + +# `leo plugins` + +List all CLI plugins currently installed and visible to Leo. + +```bash +leo plugins +``` + +```bash title="console output:" +Installed plugins: + + fmt /usr/local/bin/leo-fmt +``` + +If no plugins are found on your PATH: + +```bash title="console output:" +No leo plugins detected on PATH. +``` + +## Plugin System + +Leo supports extending the CLI with external plugin binaries. Plugins follow the `leo-` naming convention and are discovered automatically on your system PATH. + +When you run a command that doesn't match a built-in, Leo looks for a `leo-` binary on your PATH and delegates to it. Arguments are forwarded as-is. For example: + +```bash +leo fmt --check +``` + +is equivalent to: + +```bash +leo-fmt --check +``` + +If the plugin binary is not found, Leo prints an error: + +``` +'leo-fmt' not found. Install the plugin and ensure it is available on your PATH. +``` + +### Available Plugins + +| Plugin | Crate | Description | +|--------|-------|-------------| +| `leo-fmt` | [`leo-fmt`](https://github.com/ProvableHQ/leo) | Format Leo source files | +| `leo-lsp` | [`leo-lsp`](https://github.com/ProvableHQ/leo) | Language server for editor integration | + +### Installing Plugins + +Plugins can be installed via `cargo install`: + +```bash +cargo install 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`. + +:::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. +::: + +Running `leo update` will also attempt to update bundled plugins like `leo-fmt` on a best-effort basis. + +### Writing Custom Plugins + +Any executable named `leo-` on your PATH is discovered as a plugin. Custom plugins can be written in any language - the only requirements are: + +1. The binary is named `leo-` (e.g. `leo-mytools`) +2. The binary is located in a directory on your `PATH` +3. The binary is executable diff --git a/documentation/getting_started/01_installation.md b/documentation/getting_started/01_installation.md index 38af31e8f..0859e2621 100644 --- a/documentation/getting_started/01_installation.md +++ b/documentation/getting_started/01_installation.md @@ -30,10 +30,10 @@ The easiest way to install Cargo is to install the latest stable release of [Rus ## Install Leo ```bash -cargo install leo-lang +cargo install leo-lang leo-fmt ``` -This will generate the executable at `~/.cargo/bin/leo`. +This will install the `leo` and `leo-fmt` executables at `~/.cargo/bin/`. @@ -42,13 +42,17 @@ This will generate the executable at `~/.cargo/bin/leo`. 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` to make the file executable -5. Move `leo` to `/usr/local/bin` to use it system wide. +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. - mv leo /usr/local/bin + mv leo leo-fmt /usr/local/bin 6. Run `leo --version` to confirm installation +:::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). +::: + ## Other Platforms: - **[Browse all Leo releases](https://github.com/ProvableHQ/leo/releases)** @@ -78,11 +82,13 @@ git --version # Download the source code git clone https://github.com/ProvableHQ/leo cd leo -# Build and install +# Build and install Leo cargo install --path . +# Build and install the formatter plugin +cargo install --path crates/fmt ``` -This will generate the executable at `~/.cargo/bin/leo`. +This will install the `leo` and `leo-fmt` executables at `~/.cargo/bin/`. #### To use Leo, run: