From 9c734442576975dc3aadac4df97c43ccb3298e0b Mon Sep 17 00:00:00 2001 From: Matthieu Coudron <886074+teto@users.noreply.github.com> Date: Sat, 18 Jan 2025 00:03:13 +0100 Subject: [PATCH] doc/neovim: better document the wrappers (#373805) * doc/neovim: better document the wrappers there is new wrapper interface `wrapNeovimUnstable` in development intended to be easier to use than the old `wrapNeovim`. It provides new fancy features that we would like to leverage/advertise The interface is not definitive yet so we provide a translation layer to avoid breaking user configurations such that `wrapNeovim` still works. This explains why we document both at the moment with the goal to remove the old one once we ciment the interface. * doc/neovim: explain what buildNeovimPlugin does --- doc/languages-frameworks/neovim.section.md | 92 +++++++++++++++++++++- doc/languages-frameworks/vim.section.md | 28 ------- doc/redirects.json | 6 +- 3 files changed, 95 insertions(+), 31 deletions(-) diff --git a/doc/languages-frameworks/neovim.section.md b/doc/languages-frameworks/neovim.section.md index f26e4a2ffa4fc..b1dafe8543ca6 100644 --- a/doc/languages-frameworks/neovim.section.md +++ b/doc/languages-frameworks/neovim.section.md @@ -1,12 +1,22 @@ # Neovim {#neovim} Install `neovim-unwrapped` to get a barebone neovim to configure imperatively. -Neovim can be configured to include your favorite plugins and additional libraries by installing `neovim` instead. +This is the closest to what you encounter on other distributions. + +`neovim` is a wrapper around neovim with some extra configuration to for +instance set the various language providers like python. +The wrapper can be further configured to include your favorite plugins and +configurations for a reproducible neovim across machines. See the next section for more details. ## Custom configuration {#neovim-custom-configuration} -For Neovim the `configure` argument can be overridden to achieve the same: +There are two wrappers available to provide additionnal configuration around the vanilla package `pkgs.neovim-unwrapped`: +1. `wrapNeovim`: the historical one you should use +2. `wrapNeovimUnstable` intended to replace the former. It has more features but + the interface is not stable yet. + +You can configure the former via: ```nix neovim.override { @@ -14,9 +24,17 @@ neovim.override { customRC = '' # here your custom configuration goes! ''; + packages.myVimPackage = with pkgs.vimPlugins; { + # See examples below on how to use custom packages. + start = [ ]; + # If a Vim plugin has a dependency that is not explicitly listed in + # `opt`, that dependency will always be added to `start` to avoid confusion. + opt = [ ]; + }; }; } ``` +`myVimPackage` is an arbitrary name for the generated package. You can choose any name you like. If you want to use `neovim-qt` as a graphical editor, you can configure it by overriding Neovim in an overlay or passing it an overridden Neovim: @@ -33,7 +51,77 @@ neovim-qt.override { } ``` +You can use the new unstable wrapper but the interface may change: +- `autoconfigure`: certain plugins need a custom configuration to work with nix. +For instance, `sqlite-lua` needs `g:sqlite_clib_path` to be set to work. Nixpkgs historically patched these in the plugins with several drawbacks: harder maintenance and making upstream work harder. Per convention, these mandatory bits of configuration are bookmarked in nixpkgs in `passthru.initLua`. Enabling `autoconfigure` automatically adds the snippets required for the plugins to work. +- `autowrapRuntimeDeps`: Appends plugin's runtime dependencies to `PATH`. For instance, `rest.nvim` requires `curl` to work. Enabling `autowrapRuntimeDeps` adds it to the `PATH` visible by your Neovim wrapper (but not your global `PATH`). +- `luaRcContent`: Extra lua code to add to the generated `init.lua`. +- `neovimRcContent`: Extra vimL code sourced by the generated `init.lua`. +- `wrapperArgs`: Extra arguments forwarded to the `makeWrapper` call. +- `wrapRc`: Nix, not being able to write in your `$HOME`, loads the + generated Neovim configuration via its `-u` argument, i.e. : `-u /nix/store/...generatedInit.lua`. This has side effects like preventing Neovim from reading your config in `$XDG_CONFIG_HOME` (see bullet 7 of [`:help startup`](https://neovim.io/doc/user/starting.html#_initialization) in Neovim). Disable it if you want to generate your own wrapper. You can still reuse while reusing the logic of the nixpkgs wrapper and access the generated config via `neovim.passthru.initRc`. +- `plugins`: A list of plugins to add to the wrapper. + +``` +wrapNeovimUnstable { + autoconfigure = true; + autowrapRuntimeDeps = true; + luaRcContent = '' + vim.o.sessionoptions = 'buffers,curdir,help,tabpages,winsize,winpos,localoptions' + vim.g.mapleader = ' ' + vim.g.maplocalleader = ' ' + vim.opt.smoothscroll = true + vim.opt.colorcolumn = { 100 } + vim.opt.termguicolors = true + ''; + # plugins accepts a list of either plugins or { plugin = ...; config = ..vimscript.. }; + plugins = with vimPlugins; [ + { + plugin = vim-obsession; + config = '' + map $ Obsession + ''; + } + (nvim-treesitter.withPlugins (p: [ p.nix p.python ])) + hex-nvim + ]; +} +``` + +You can explore the configuration with`nix repl` to discover these options and +override them. For instance: +```nix +neovim.overrideAttrs(oldAttrs: { + autowrapRuntimeDeps = false; +}) +``` + ### Specificities for some plugins {#neovim-plugin-specificities} + +### Plugin optional configuration {#neovim-plugin-required-snippet} + +Some plugins require specific configuration to work. We choose not to +patch those plugins but expose the necessary configuration under +`PLUGIN.passthru.initLua` for neovim plugins. For instance, the `unicode-vim` plugin +needs the path towards a unicode database so we expose the following snippet `vim.g.Unicode_data_directory="${self.unicode-vim}/autoload/unicode"` under `vimPlugins.unicode-vim.passthru.initLua`. + +#### {#neovim-luarocks-based-plugins} + +In order to automatically handle plugin dependencies, several neovim plugins +upload their package to [](www.luarocks.org). This means less work for nixpkgs maintainers in the long term as dependencies get updated automatically. +This means several neovim plugins are first packaged as nixpkgs [lua +packages](#packaging-a-library-on-luarocks), and converted via `buildNeovimPlugin` in +a vim plugin. This conversion is necessary because neovim expects lua folders to be +top-level while luarocks installs them in varous subfolders by default. + +For instance: +```nix +rtp-nvim = neovimUtils.buildNeovimPlugin { + luaAttr = luaPackages.rtp-nvim; +}; +``` +To update these packages, you should use the lua updater rather than vim's. + #### Treesitter {#neovim-plugin-treesitter} By default `nvim-treesitter` encourages you to download, compile and install diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md index 9d7dab9eb496a..9a591bd0129a1 100644 --- a/doc/languages-frameworks/vim.section.md +++ b/doc/languages-frameworks/vim.section.md @@ -58,25 +58,6 @@ vim-full.customize { } ``` -`myVimPackage` is an arbitrary name for the generated package. You can choose any name you like. -For Neovim the syntax is: - -```nix -neovim.override { - configure = { - customRC = '' - # here your custom configuration goes! - ''; - packages.myVimPackage = with pkgs.vimPlugins; { - # see examples below how to use custom packages - start = [ ]; - # If a Vim plugin has a dependency that is not explicitly listed in - # opt that dependency will always be added to start to avoid confusion. - opt = [ ]; - }; - }; -} -``` The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.nix` to make it installable: @@ -178,15 +159,6 @@ To add a new plugin, run `nix-shell -p vimPluginsUpdater --run 'vim-plugins-upda Finally, there are some plugins that are also packaged in nodePackages because they have Javascript-related build steps, such as running webpack. Those plugins are not listed in `vim-plugin-names` or managed by `vimPluginsUpdater` at all, and are included separately in `overrides.nix`. Currently, all these plugins are related to the `coc.nvim` ecosystem of the Language Server Protocol integration with Vim/Neovim. - -### Plugin optional configuration {#vim-plugin-required-snippet} - -Some plugins require specific configuration to work. We choose not to -patch those plugins but expose the necessary configuration under -`PLUGIN.passthru.initLua` for neovim plugins. For instance, the `unicode-vim` plugin -needs the path towards a unicode database so we expose the following snippet `vim.g.Unicode_data_directory="${self.unicode-vim}/autoload/unicode"` under `vimPlugins.unicode-vim.passthru.initLua`. - - ## Updating plugins in nixpkgs {#updating-plugins-in-nixpkgs} Run the update script with a GitHub API token that has at least `public_repo` access. Running the script without the token is likely to result in rate-limiting (429 errors). For steps on creating an API token, please refer to [GitHub's token documentation](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token). diff --git a/doc/redirects.json b/doc/redirects.json index 254e6ceb6fc6e..dfc5bc5a1eaa9 100644 --- a/doc/redirects.json +++ b/doc/redirects.json @@ -8,6 +8,9 @@ "neovim-custom-configuration": [ "index.html#neovim-custom-configuration" ], + "neovim-luarocks-based-plugins": [ + "index.html#neovim-luarocks-based-plugins" + ], "nixpkgs-manual": [ "index.html#nixpkgs-manual" ], @@ -3799,7 +3802,8 @@ "testing-neovim-plugins-neovim-require-check": [ "index.html#testing-neovim-plugins-neovim-require-check" ], - "vim-plugin-required-snippet": [ + "neovim-plugin-required-snippet": [ + "index.html#neovim-plugin-required-snippet", "index.html#vim-plugin-required-snippet" ], "updating-plugins-in-nixpkgs": [