nvim-neorocks/rocks.nvim

github github
plugin-manager
stars 147
issues 16
subscribers 5
forks 5
CREATED

2023-07-05

UPDATED

3 days ago


:star2: Features

  • Cargo-like rocks.toml file for declaring all your plugins.
  • Name-based installation ("nvim-neorg/neorg" becomes :Rocks install neorg instead).
  • Automatic dependency and build script management.
  • True semver versioning!
  • Minimal, non-intrusive UI.
  • Async execution.
  • Extensible, with a Lua API.
  • Command completions for plugins on luarocks.org.

demo

:pencil: Requirements

  • An up-to-date Neovim nightly (>= 0.10) installation.
  • The git command line utility.
  • wget or curl (if running on a UNIX system) - required for the remote :source command to work.
  • netrw enabled in your Neovim configuration - enabled by default but some configurations manually disable the plugin.

[!IMPORTANT] If you are running on Windows or an esoteric architecture, rocks.nvim will attempt to compile its dependencies instead of pulling a prebuilt binary. For the process to succeed you must have a C++17 parser and Rust toolchain installed on your system.

:hammer: Installation

:zap: Installation script (recommended)

The days of bootstrapping and editing your configuration are over. rocks.nvim can be installed directly through an interactive installer within Neovim.

We suggest starting nvim without loading RC files, such that already installed plugins do not interfere with the installer:

nvim -u NORC -c "source https://raw.githubusercontent.com/nvim-neorocks/rocks.nvim/master/installer.lua"

[!IMPORTANT]

For security reasons, we recommend that you read :help :source and the installer code before running it so you know exactly what it does.

[!TIP]

To configure the luarocks installation to use a specific lua install, use environment variables LUA_BINDIR=<Directory of lua binary> and LUA_BINDIR_SET=yes.

For example:

LUA_BINDIR="${XDG_BIN_DIR:-$HOME/.local/bin}" LUA_BINDIR_SET=yes nvim -u NORC -c "source ...

:books: Usage

Installing rocks

You can install rocks with the :Rocks install {rock} {version?} command.

Arguments:

  • rock: The luarocks package.
  • version: Optional. Used to pin a rock to a specific version.

[!NOTE]

  • The command provides fuzzy completions for rocks and versions on luarocks.org.
  • Installs the latest version if version is omitted.
  • This plugin keeps track of installed plugins in a rocks.toml file, which you can commit to version control.

Updating rocks

Running the :Rocks update command will attempt to update every available rock if it is not pinned.

Syncing rocks

The :Rocks sync command synchronizes the installed rocks with the rocks.toml.

[!NOTE]

  • Installs missing rocks.
  • Ensures that the correct versions are installed.
  • Uninstalls unneeded rocks.

Uninstalling rocks

To uninstall a rock and any of its dependencies, that are no longer needed, run the :Rocks prune {rock} command.

[!NOTE]

  • The command provides fuzzy completions for rocks that can safely be pruned without breaking dependencies.

Editing rocks.toml

The :Rocks edit command opens the rocks.toml file for manual editing. Make sure to run :Rocks sync when you are done.

Lazy loading plugins

By default, rocks.nvim will source all plugins at startup. To prevent it from sourcing a plugin, you can specify opt = true in the rocks.toml file.

For example:

[plugins]
neorg = { version = "1.0.0", opt = true }

or

[plugins.neorg]
version = "1.0.0"
opt = true

You can then load the plugin with the :Rocks[!] packadd {rock} command.

[!NOTE]

A note on loading rocks:

Luarocks packages are installed differently than you are used to from Git repositories.

Specifically, luarocks installs a rock's Lua API to the package.path and the package.cpath. It does not have to be added to Neovim's runtime path (e.g. using :Rocks packadd), for it to become available. This does not impact Neovim's startup time.

Runtime directories (:h runtimepath), on the other hand, are installed to a separate location. Plugins that utilise these directories may impact startup time (if it has ftdetect or plugin scripts), so you may or may not benefit from loading them lazily.

:stethoscope: Troubleshooting

The :Rocks log command opens a log file for the current session, which contains the luarocks stderr output, among other logs.

Known issues and fixes

nvim-treesitter parsers

nvim-treesitter version 0.9.2 tries to install its parsers in the plugin's package directory. This is broken when the plugin is installed using luarocks, because the lua and share directories are in separate branches of the file tree. Later versions of nvim-treesitter should fix this by installing parsers to the "site" directory.

For version 0.9.2, you can work around this by explicitly setting the parser_install_dir:

local site_dir = vim.fs.joinpath(vim.fn.stdpath("data"), "site")
require("nvim-treesitter.configs").setup {
  parser_install_dir = site_dir,
}

:package: Extending rocks.nvim

This plugin provides a Lua API for extensibility. See :h rocks.api for details.

Following are some examples:

To extend rocks.nvim, simply install a module with :Rocks install, and you're good to go!

:book: License

rocks.nvim is licensed under GPLv3.

:green_heart: Contributing

Contributions are more than welcome! See CONTRIBUTING.md for a guide.