v2.0.0-rc.2

[williamboman]

v2.0.0-rc.2 Release Notes

2025-03-03: v2.0.0-rc.2 has been released

This release has been an ongoing effort for quite some time now and is getting ready to be released. Most users should not experience any breaking changes. If you use any of the Lua APIs that Mason provides you'll find an outline of the changes below, breaking changes are marked with Breaking Change. Note that this is a release candidate and not yet part of the stable branch - you may have to explicitly target the v2.0.0-rc.2 when downloading the plugin.

Please provide feedback/issues within this discussion! Thev2.0.0-rc.2 release can be found in the v2.x branch or the v2.0.0-rc.2 git tag. mason-lspconfig.nvim has a corresponding v2.x branch and v2.0.0-rc.1 git tag, if you use that plugin as well.

Important

If you upgrade to v2.0.0-rc.2 and later choose to downgrade mason.nvim you will experience issues with managing packages installed using v2.0.0-rc.2. It's therefore recommended to uninstall all packages before downgrading.

Mason is looking for core registry maintainers

The core registry is used by a large amount of users and as of writing almost has 500 packages. The scope of the project has long outgrown the capacity of its maintainer (me). Mason is now looking for maintainers to help managing the registry as well as other repositories/projects. If you're interested, please head over to this discussion and reply!

Thanks to all sponsors who help finance monthly costs and all 181 contributors of mason.nvim and 214 contributors of the core registry!

New Features

• Symlinks now uses relative paths instead of absolute paths.
• Uninstalled packages now display their available version in the :Mason UI.
• Official support for custom registries.
• Make registry installations run concurrently.

Bug Fixes

• Only attempt unlinking package if the receipt is found.
• Expand executable paths on Windows before passing to uv_spawn.
• Fix initializing UI state when using multiple registries.

Misc

• Breaking Change Minimum Neovim requirement changed from 0.7.0 to 0.10.0.
• Breaking Change APIs related to custom packages written in Lua has been removed.
  • All require("mason-core.installer.managers") modules have been removed.
  • The package structure of Lua packages has changed, refer to custom registries for information on how to continue using custom packages in Lua.

Event changes

Package

• Breaking Change install:success now provides the receipt as payload argument.
• Breaking Change install:failed now provides the error as payload argument.
• Breaking Change uninstall:success now provides the receipt of the uninstalled package as payload argument.
• uninstall:failed is now emitted when package uninstallation fails.

Registry

• Breaking Change package:install:success now provides the receipt as payload argument.
• Breaking Change package:install:failed now provides the error as payload argument.
• Breaking Change package:uninstall:success now provides the receipt of the uninstalled package as payload argument.
• package:uninstall:failed is now emitted when package uninstallation fails.
• Breaking Change update is no longer emitted when registry is updated. It's replaced by the following events:
  • update:start when the registry starts updating
  • update:success when the registry is successfully updated
  • update:failed when the registry failed to update
  • update:progress is emitted when the registry update process makes progress when multiple registries are used

Package API changes

Package:get_install_path() has been removed.

Breaking Change

This method has been removed to prepare for future changes.

If you're using this method to access an executable, please consider simply using the canonical name of the executable as Mason adds these to your PATH by default. If you're using the method to access other files inside the package, please consider accessing the $MASON/share directory instead.

Example:

Clarification: The $MASON environment variable has been available since v1.0.0.

-- 1a. There's no need to reach into the package directory via Package:get_install_path() to access the executable
print(vim.fn.exepath("kotlin-debug-adapter"))
-- /Users/william/.local/share/nvim/mason/bin/kotlin-debug-adapter

-- 1b. Alternatively if you've configured Mason to not modify PATH
print(vim.fn.expand("$MASON/bin/kotlin-debug-adapter"))
-- /Users/william/.local/share/nvim/mason/bin/kotlin-debug-adapter

-- 2. To access other files inside the package directory, consider accessing them via the share/ directory
vim.print(vim.fn.globpath("$MASON/share/java-debug-adapter", "*.jar", true, true))
-- { "/Users/william/.local/share/nvim/mason/share/java-debug-adapter/com.microsoft.java.debug.plugin-0.53.1.jar", "/Users/william/.local/share/nvim/mason/share/java-debug-adapter/com.microsoft.java.debug.plugin.jar" }

-- 3. If you absolutely need to access the package directory (please consider raising an issue/PR in the registry if possible)
print(vim.fn.expand("$MASON/packages/kotlin-debug-adapter/adapter/bin/kotlin-debug-adapter"))
-- /Users/william/.local/share/nvim/mason/packages/kotlin-debug-adapter/adapter/bin/kotlin-debug-adapter

Note

Why was this method removed? The contents of the package directory is not a stable interface and its structure may change without prior notice. The only stable interfaces on the file system are files available in bin/, share/ and opt/ - these directories are only subject to breaking changes done by the underlying package itself.

---

Package:uninstall(opts, callback) is now asynchronous.

Breaking Change

This method now provides an asynchronous interface and accepts two new optional arguments opts and callback. opts currently doesn't have any valid values other than an empty Lua table {}. callback is called when the package is uninstalled, successfully or not. While the uninstall mechanism under the hood remains synchronous for the time being it is not a guarantee going forward and users are recommended to always use the asynchronous version.

Example:

local registry = require("mason-registry")
local pkg = registry.get_package("lua-language-server")

pkg:uninstall({}, function (success, result)
    if success then
        -- Do something on success.
    else
        -- Do something on error.
    end
end)

---

Package:check_new_version() has been removed.

Breaking Change

Package:check_new_version() is replaced by Package:get_latest_version(). Package:get_latest_version() is a synchronous API.

Note

Similarly to before, this function returns the package version provided by the currently installed registry version.

Example:

local registry = require("mason-registry")
local pkg = registry.get_package("lua-language-server")
local latest_version = pkg:get_latest_version()

---

Package:get_installed_version() is now synchronous.

Breaking Change

This function no longer accepts a callback.

Example:

local registry = require("mason-registry")
local pkg = registry.get_package("lua-language-server")
if pkg:is_installed() then
    local installed_version = pkg:get_installed_version()
end

---

Package:install() will now error if the package is currently being installed.

Breaking Change

Use the new Package:is_installing() method to check whether an installation is already running.

---

Package:uninstall() will now error if the package is not already installed.

Breaking Change

Use the new Package:is_installed() method to check whether the package is installed.

---

Package:install(opts, callback) now accepts a callback.

This optional callback is called by Mason when package installation finishes, successfully or not.

Example:

local registry = require("mason-registry")
local pkg = registry.get_package("lua-language-server")

pkg:install({}, function (success, result)
    if success then
        -- Do something on success.
    else
        -- Do something on error.
    end
end)

---

Custom registries

v2.0.0 introduces official support for custom registries. Currently supported registry protocols are github:, file:, and lua:. See https://github.com/mason-org/registry-examples for examples.

[s1n7ax]

@williamboman Just wondering what would be the programmatical way to inject a custom repository? I have just switched to calling setup since I couldn't find any other way. I'm basically prepending a registry to mason.settings.current.registries list and re calling require('mason').setup({registries=new_reg_list })

[williamboman]

Hello! Is this to make it easier to use plugins that rely on a custom registry? There are two things that need to be considered:

1. The order in which registries are configured matter
2. Registries need to be configured before any interactions with Mason

Addressing the first point is probably just as simple as allowing plugins to either prepend or append their registry. Addressing the second point might be a little trickier. Currently, users have to manually add registries to require("mason").setup() which means registries will always be configured "properly" at the point of setup. If plugins were able to do this on behalf of users instead, it's important that it occurs either when Mason itself is setting up (I'll provide an example below) or after setting up Mason but before any user interaction with Mason (i.e. ideally immediately after setting up Mason). The problem arises when users start to lazy load plugins, for example only loading nvim-java when opening a Java buffer. Plugins that want to add a custom registry automatically will have to be loaded at the same time as Mason in order for the registry to behave properly.

-- mason.nvim's setup
local registry = require("mason-registry")

function M.setup()
    -- ...
    -- 1. Configure registries provided in settings
    registry.prepend(settings.current.registries)
    -- 2. Source all mason/registry.lua files in runtimepath
    vim.cmd.runtime { "mason/registry.lua", bang = true }
end

Plugins would then be able to add a mason/registry.lua file containing:

local registry = require("mason-registry")
registry.prepend("github:nvim-java/mason-registry")

The above approach would ensure that the registry is always configured at the same time. Unfortunately I think this is a non-starter because of how plugin managers tend to delay adding a plugin to runtimepath until it's configured (I believe this is how lazy.nvim works?).

I think simply adding registry.append() and registry.prepend() would be the best way. Again, if plugins want to use these functions it's important that the plugin isn't lazy loaded.

What do you think?

[williamboman]

I've added the following APIs in v2.0.0-rc.2:

local registry = require "mason-registry"

registry.sources:prepend("github:nvim-java/mason-registry")
registry.sources:append("github:nvim-java/mason-registry")

Again, it's important that these methods are called before any interaction with the registry, either from the user or programmatically. Modifying the registry sources after some interaction has occurred (e.g. retrieving a package, starting an installation) will have undefined behavior and I might change these methods in the future to error if they're called after the registry has been accessed already.

[Conarius]

Small good news:

rustaceanvim is already updated for compatibility with 2.0 as of 5.25.0
Here's the pr btw