diff --git a/docs/architecture.md b/docs/architecture.md index 2c96f75737..f138fa5412 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -54,7 +54,7 @@ pub trait Backend: Debug + Send + Sync { - **Core Backends**: Native Rust implementations for maximum performance - **Language Package Managers**: npm, pipx, cargo, gem, go modules -- **Universal Installers**: ubi (GitHub releases), aqua (comprehensive package management) +- **Universal Installers**: github (GitHub releases), aqua (comprehensive package management) - **Plugin Systems**: [backend plugins](backend-plugin-development.md) (enhanced methods), [tool plugins](tool-plugin-development.md) (hook-based), [asdf plugins](asdf-legacy-plugins.md) (legacy) For guidance on implementing new backends, see the [Contributing Guide](contributing.md#adding-backends). For detailed backend system design, see [Backend Architecture](dev-tools/backend_architecture.md). diff --git a/docs/asdf-legacy-plugins.md b/docs/asdf-legacy-plugins.md index 75055de81b..1c9376d44d 100644 --- a/docs/asdf-legacy-plugins.md +++ b/docs/asdf-legacy-plugins.md @@ -1,5 +1,9 @@ # asdf (Legacy) Plugins +::: warning +asdf plugins are considered legacy. For new tools, prefer [vfox plugins](/dev-tools/backends/vfox.html) which are written in Lua, work cross-platform (including Windows), and have access to built-in modules. See the [feature comparison](/dev-tools/backends/asdf.html#feature-comparison-asdf-vs-vfox) and [hook migration table](/dev-tools/backends/asdf.html#hook-migration-asdf-to-vfox) for details. +::: + mise maintains compatibility with the asdf plugin ecosystem through its asdf backend. These plugins are considered legacy because they have limitations compared to mise's modern plugin system. ## What are asdf (Legacy) Plugins? @@ -12,7 +16,7 @@ asdf plugins have several limitations compared to mise's modern plugin system: - **Platform Support**: Only work on Linux and macOS (no Windows support) - **Performance**: Shell script execution is slower than mise's native backends -- **Features**: Limited compared to modern backends like aqua, ubi, or tool/backend plugins +- **Features**: Limited compared to modern backends like aqua, github, or tool/backend plugins - **Maintenance**: Harder to maintain and debug - **Security**: Less secure than sandboxed modern backends @@ -20,14 +24,14 @@ asdf plugins have several limitations compared to mise's modern plugin system: Only use asdf plugins when: -- The tool is not available through modern backends (aqua, ubi, etc.) +- The tool is not available through modern backends (aqua, github, etc.) - You need compatibility with existing asdf workflows - The tool requires complex shell-based installation logic that can't be handled by modern backends **For new tools, consider these alternatives first:** 1. [aqua backend](dev-tools/backends/aqua.md) - Preferred for GitHub releases -2. [ubi backend](dev-tools/backends/ubi.md) - Simple GitHub/GitLab releases +2. [github backend](dev-tools/backends/github.md) - Simple GitHub releases 3. [Language package managers](dev-tools/backends/) - npm, pipx, cargo, gem, etc. 4. [backend plugins](backend-plugin-development.md) - Enhanced plugins with backend methods 5. [tool plugins](tool-plugin-development.md) - Hook-based cross-platform plugins @@ -323,7 +327,7 @@ chmod +x "$ASDF_INSTALL_PATH/bin/tool" Consider migrating from asdf plugins to modern alternatives: 1. **Check if tool is available in [aqua registry](https://aquaproj.github.io/aqua-registry/)** -2. **Use [ubi backend](dev-tools/backends/ubi.md) for simple GitHub releases** +2. **Use [github backend](dev-tools/backends/github.md) for simple GitHub releases** 3. **Create a [mise plugin](tool-plugin-development.md) for complex tools** - use the [mise-tool-plugin-template](https://github.com/jdx/mise-tool-plugin-template) for a quick start 4. **Use language-specific package managers** (npm, pipx, cargo, gem) diff --git a/docs/backend-plugin-development.md b/docs/backend-plugin-development.md index 2db097b093..9b84c4ef7d 100644 --- a/docs/backend-plugin-development.md +++ b/docs/backend-plugin-development.md @@ -1,5 +1,9 @@ # Backend Plugin Development +::: tip +The [mise-backend-plugin-template](https://github.com/jdx/mise-backend-plugin-template) provides a ready-to-use starting point with LuaCATS type definitions, stylua formatting, and hk linting pre-configured. +::: + Backend plugins in mise use enhanced backend methods to manage multiple tools using the `plugin:tool` format. These plugins are perfect for package managers, tool families, and custom installations that need to manage multiple related tools. ## What are Backend Plugins? diff --git a/docs/dev-tools/backend_architecture.md b/docs/dev-tools/backend_architecture.md index 67762c4345..deb1f5a034 100644 --- a/docs/dev-tools/backend_architecture.md +++ b/docs/dev-tools/backend_architecture.md @@ -119,13 +119,17 @@ terraform = "aqua:hashicorp/terraform" # Use aqua backend ## Backend Capabilities Comparison -| Feature | Core | npm/pipx/cargo | aqua | ubi | Backend Plugins | Tool Plugins (vfox) | asdf Plugins (legacy) | -| ------------------- | ---- | -------------- | ---- | --- | --------------- | ------------------- | --------------------- | -| **Speed** | ✅ | ⚠️ | ✅ | ✅ | ⚠️ | ⚠️ | ⚠️ | -| **Security** | ✅ | ⚠️ | ✅ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | -| **Windows Support** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | -| **Env Var Support** | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | -| **Custom Scripts** | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| Feature | Core | npm/pipx/cargo | aqua | ubi | Backend Plugins | Tool Plugins (vfox) | asdf Plugins (legacy) | +| ------------------------- | ---- | -------------- | ---- | --- | --------------- | ------------------- | --------------------- | +| **Speed** | ✅ | ⚠️ | ✅ | ✅ | ⚠️ | ⚠️ | ⚠️ | +| **Security** | ✅ | ⚠️ | ✅ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| **Windows Support** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | +| **Env Var Support** | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| **Custom Scripts** | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| **Built-in Modules** | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | +| **Security Attestations** | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | +| **Multi-tool Plugins** | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | +| **Progress/Logging** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ## When to Use Each Backend @@ -151,14 +155,18 @@ Core tools should generally always be used when available, as they provide the b - The tool is already available in the [aqua registry](https://github.com/aquaproj/aqua-registry) - You're willing to contribute tools to the aqua registry for tools not yet available -### Use **ubi** when +### Use **github** when -- Installing pre-compiled binaries from GitHub/GitLab releases +- Installing pre-compiled binaries from GitHub releases - The repository follows standard conventions for release tarballs - You want zero configuration - no registry setup required - You need simple, fast binary installation - The tool doesn't require complex build processes or environment setup +::: info +The `ubi` backend still works but is deprecated in favor of `github`. Replace `ubi:owner/repo` with `github:owner/repo`. +::: + ### Use **Backend Plugins** when - You need to manage multiple tools with one plugin diff --git a/docs/dev-tools/backends/asdf.md b/docs/dev-tools/backends/asdf.md index c7bf46b323..746f5e76a4 100644 --- a/docs/dev-tools/backends/asdf.md +++ b/docs/dev-tools/backends/asdf.md @@ -1,19 +1,52 @@ # asdf Backend +::: warning +asdf plugins are considered legacy. For new tools, prefer [vfox plugins](/dev-tools/backends/vfox.html) which are written in Lua, work cross-platform (including Windows), and have access to built-in modules for HTTP, JSON, HTML parsing, and more. +::: + `asdf` is the original backend for mise. It relies on asdf plugins for each tool. asdf plugins are more risky to use because they're typically written by a single developer unrelated to the tool vendor. They also generally do not function on Windows because they're written in bash which is often not available on Windows and the scripts generally are not written to be cross-platform. -asdf plugins are not used for tools inside the [registry](https://github.com/jdx/mise/blob/main/registry/) whenever possible. Sometimes it is not possible to use more secure backends like aqua/ubi because tools have complex install setups or need to export env vars. +asdf plugins are not used for tools inside the [registry](https://github.com/jdx/mise/blob/main/registry/) whenever possible. Sometimes it is not possible to use more secure backends like aqua/github because tools have complex install setups or need to export env vars. All of these are hosted in the mise-plugins org to secure the supply chain so you do not need to rely on plugins maintained by anyone except me. Because of the extra complexity of asdf tools and security concerns we are actively moving tools in -the registry away from asdf where possible to backends like aqua and ubi which don't require plugins. -That said, not all tools can function with ubi/aqua if they have a unique installation process or +the registry away from asdf where possible to backends like aqua and github which don't require plugins. +That said, not all tools can function with github/aqua if they have a unique installation process or need to set env vars other than `PATH`. +## Feature Comparison: asdf vs vfox + +| Feature | asdf Plugins | vfox Plugins | +| ------------------------------- | ------------------ | -------------------- | +| **Language** | Bash scripts | Lua | +| **Windows Support** | ❌ | ✅ | +| **Built-in HTTP module** | ❌ (requires curl) | ✅ | +| **Built-in JSON module** | ❌ (requires jq) | ✅ | +| **Built-in HTML parsing** | ❌ | ✅ | +| **Built-in archive extraction** | ❌ | ✅ | +| **Built-in semver module** | ❌ | ✅ | +| **Built-in logging** | ❌ | ✅ | +| **Post-install hooks** | ❌ | ✅ | +| **Security attestations** | ❌ | ✅ (cosign, SLSA) | +| **Multi-tool plugins** | ❌ | ✅ (backend plugins) | +| **Lock file support** | ❌ | ✅ | +| **Rolling version checksums** | ❌ | ✅ | + +## Hook Migration: asdf to vfox + +| asdf Script | vfox Hook | Notes | +| --------------------------- | ------------------------ | ---------------------------------------------------------------- | +| `bin/list-all` | `Available` | Return structured version objects instead of plain text | +| `bin/download` | `PreInstall` | Return URL and checksum; mise handles the download | +| `bin/install` | `PostInstall` | Runs after mise downloads and extracts the tool | +| `bin/exec-env` | `EnvKeys` | Return structured key/value pairs instead of `export` statements | +| `bin/list-legacy-filenames` | `PLUGIN.legacyFilenames` | Set in `metadata.lua` instead of a script | +| `bin/parse-legacy-file` | `ParseLegacyFile` | Return structured result instead of plain text | + ## Writing asdf (legacy) plugins for mise See the asdf documentation for more information on [writing plugins](https://asdf-vm.com/plugins/create.html). diff --git a/docs/dev-tools/backends/vfox.md b/docs/dev-tools/backends/vfox.md index 859d4d9741..91ee787c46 100644 --- a/docs/dev-tools/backends/vfox.md +++ b/docs/dev-tools/backends/vfox.md @@ -1,7 +1,18 @@ # Vfox Backend +::: tip +Vfox is the recommended plugin system for mise. It provides cross-platform support, built-in modules, and a modern hook-based architecture. +::: + [Vfox](https://github.com/version-fox/vfox) plugins may be used in mise to install tools. +## Why vfox? + +- **Cross-platform** — plugins work on Windows, macOS, and Linux without platform-specific code +- **Built-in modules** — HTTP, JSON, HTML parsing, archive extraction, semver comparison, and logging are all available out of the box, no external dependencies needed +- **Security** — supports attestation verification (cosign signatures, SLSA provenance) for downloaded artifacts +- **Modern architecture** — structured hooks with typed contexts, backend plugins for multi-tool management, rolling version checksums, and lock file support + The code for this is inside the mise repository at [`./src/backend/vfox.rs`](https://github.com/jdx/mise/blob/main/src/backend/vfox.rs). ## Dependencies diff --git a/docs/dev-tools/comparison-to-asdf.md b/docs/dev-tools/comparison-to-asdf.md index 8015b7deab..ba807e9eaa 100644 --- a/docs/dev-tools/comparison-to-asdf.md +++ b/docs/dev-tools/comparison-to-asdf.md @@ -149,7 +149,7 @@ work on Windows. asdf plugins are insecure. They typically are written by individuals with no ties to the vendors that provide the underlying tool. -Where possible, mise does not use asdf plugins and instead uses backends like aqua and ubi which do +Where possible, mise does not use asdf plugins and instead uses backends like aqua and github which do not require separate plugins. Aqua tools include native Cosign/SLSA/Minisign/GitHub attestation verification built into mise. diff --git a/docs/env-plugin-development.md b/docs/env-plugin-development.md index 8d5f71bb85..d00dcc042c 100644 --- a/docs/env-plugin-development.md +++ b/docs/env-plugin-development.md @@ -12,11 +12,17 @@ Unlike [tool plugins](tool-plugin-development.md) and [backend plugins](backend- ## Quick Start -The fastest way to create an environment plugin is to use the [mise-env-plugin-template](https://github.com/jdx/mise-env-sample): +The fastest way to create an environment plugin is to use the [mise-env-plugin-template](https://github.com/jdx/mise-env-plugin-template). + +::: tip +The [mise-env-plugin-template](https://github.com/jdx/mise-env-plugin-template) provides a ready-to-use starting point with LuaCATS type definitions, stylua formatting, and hk linting pre-configured. +::: + +To get started: ```bash # Clone the template -git clone https://github.com/jdx/mise-env-sample my-env-plugin +git clone https://github.com/jdx/mise-env-plugin-template my-env-plugin cd my-env-plugin # Customize for your use case @@ -416,7 +422,7 @@ See [Plugin Publishing](/plugin-publishing.html) for detailed instructions. ## Examples -- [mise-env-sample](https://github.com/jdx/mise-env-sample) - Simple example showing basic usage +- [mise-env-sample](https://github.com/jdx/mise-env-plugin-template) - Simple example showing basic usage - The [mise-plugins](https://github.com/mise-plugins) organization currently hosts tool plugins only—add your environment plugin there (or share it with the community) so others can learn from more examples ## Migration from Tool Plugins diff --git a/docs/environments/index.md b/docs/environments/index.md index fd54dfdd38..58e85b45db 100644 --- a/docs/environments/index.md +++ b/docs/environments/index.md @@ -488,7 +488,7 @@ The plugin could detect the current git branch and set `ENVIRONMENT=production` See [Environment Plugins](/plugins#environment-plugins) in the Plugins documentation for a complete guide to creating your own environment plugins. -For a working example, see the [mise-env-sample](https://github.com/jdx/mise-env-sample) repository. +For a working example, see the [mise-env-plugin-template](https://github.com/jdx/mise-env-plugin-template) repository. ## Multiple `env._` Directives diff --git a/docs/plugins.md b/docs/plugins.md index 135bf2415b..6874620180 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -5,16 +5,16 @@ Plugins in mise are a way to extend `mise` with new functionality like extra too Historically it was the only way to add new tools (as the only backend was [asdf](/dev-tools/backends/asdf.html)). The way that backend works is every tool has its own plugin which needs to be manually installed. However, now with [core tools](/core-tools.html) -and backends like [aqua](/dev-tools/backends/aqua.html)/[ubi](/dev-tools/backends/ubi.html), plugins are no longer necessary to run most tools in mise. +and backends like [aqua](/dev-tools/backends/aqua.html)/[github](/dev-tools/backends/github.html), plugins are no longer necessary to run most tools in mise. Tool plugins should be avoided for security reasons. New tools will not be accepted into mise built with asdf/plugins unless they are very popular and -aqua/ubi is not an option for some reason. +aqua/github is not an option for some reason. The only exception is if the tool needs to set env vars or has a complex installation process, as plugins can provide functionality like [setting env vars globally](/environments/#plugin-provided-env-directives) without relying on a tool being installed. They can also provide [aliases for versions](/dev-tools/aliases.html#aliased-versions). If you want to integrate a new tool into mise, you should either try to get it into the [aqua registry](https://mise.jdx.dev/dev-tools/backends/aqua.html) -or see if it can be installed with [ubi](https://mise.jdx.dev/dev-tools/backends/ubi.html). Then add it to the [registry](https://github.com/jdx/mise/blob/main/registry/). -Aqua is definitely preferred to ubi as it has better UX and more features like slsa verification and the ability to use different logic for older versions. +or see if it can be installed with [github](https://mise.jdx.dev/dev-tools/backends/github.html). Then add it to the [registry](https://github.com/jdx/mise/blob/main/registry/). +Aqua is definitely preferred to github as it has better UX and more features like slsa verification and the ability to use different logic for older versions. You can manage all installed plugins in `mise` with [`mise plugins`](/cli/plugins.html). @@ -93,7 +93,7 @@ Unlike tool plugins, environment plugins: - Are activated via `env._.` syntax - Don't manage tool versions or installations -See [Environment Plugin Development](env-plugin-development.md) for creating environment plugins. The [mise-env-sample](https://github.com/jdx/mise-env-sample) repository provides a working example. +See [Environment Plugin Development](env-plugin-development.md) for creating environment plugins. The [mise-env-plugin-template](https://github.com/jdx/mise-env-plugin-template) repository provides a ready-to-use starting point. ## General Plugin Usage diff --git a/docs/tool-plugin-development.md b/docs/tool-plugin-development.md index 134d95a018..e773969df9 100644 --- a/docs/tool-plugin-development.md +++ b/docs/tool-plugin-development.md @@ -1,5 +1,9 @@ # Tool Plugin Development +::: tip +The [mise-tool-plugin-template](https://github.com/jdx/mise-tool-plugin-template) provides a ready-to-use starting point with LuaCATS type definitions, stylua formatting, and hk linting pre-configured. +::: + Tool plugins use a hook-based architecture to manage individual tools. They are compatible with the standard vfox ecosystem and are perfect for tools that need complex installation logic, environment configuration, or legacy file parsing. ## What are Tool Plugins? diff --git a/docs/walkthrough.md b/docs/walkthrough.md index 397481f156..0c247bc173 100644 --- a/docs/walkthrough.md +++ b/docs/walkthrough.md @@ -66,7 +66,7 @@ If you leave out the version, then mise will default to `node@latest`. ## Dev Tool Backends -Tools are installed with a variety of backends like `asdf`, `ubi`, or `vfox`. See [registry](/registry.html) for +Tools are installed with a variety of backends like `asdf`, `github`, or `vfox`. See [registry](/registry.html) for the full list of shorthands like `node` you can use. You can also use other backends like `npm` or `cargo`