diff --git a/doc/languages-frameworks/index.md b/doc/languages-frameworks/index.md index fe5f0e65a52e3..c3f192a1a38bf 100644 --- a/doc/languages-frameworks/index.md +++ b/doc/languages-frameworks/index.md @@ -96,4 +96,5 @@ swift.section.md tcl.section.md texlive.section.md vim.section.md +neovim.section.md ``` diff --git a/doc/languages-frameworks/neovim.section.md b/doc/languages-frameworks/neovim.section.md new file mode 100644 index 0000000000000..f26e4a2ffa4fc --- /dev/null +++ b/doc/languages-frameworks/neovim.section.md @@ -0,0 +1,107 @@ +# 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. +See the next section for more details. + +## Custom configuration {#neovim-custom-configuration} + +For Neovim the `configure` argument can be overridden to achieve the same: + +```nix +neovim.override { + configure = { + customRC = '' + # here your custom configuration goes! + ''; + }; +} +``` + +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: + +```nix +neovim-qt.override { + neovim = neovim.override { + configure = { + customRC = '' + # your custom configuration + ''; + }; + }; +} +``` + +### Specificities for some plugins {#neovim-plugin-specificities} +#### Treesitter {#neovim-plugin-treesitter} + +By default `nvim-treesitter` encourages you to download, compile and install +the required Treesitter grammars at run time with `:TSInstall`. This works +poorly on NixOS. Instead, to install the `nvim-treesitter` plugins with a set +of precompiled grammars, you can use the `nvim-treesitter.withPlugins` function: + +```nix +(pkgs.neovim.override { + configure = { + packages.myPlugins = with pkgs.vimPlugins; { + start = [ + (nvim-treesitter.withPlugins ( + plugins: with plugins; [ + nix + python + ] + )) + ]; + }; + }; +}) +``` + +To enable all grammars packaged in nixpkgs, use `pkgs.vimPlugins.nvim-treesitter.withAllGrammars`. + + +### Testing Neovim plugins {#testing-neovim-plugins} + +#### neovimRequireCheck {#testing-neovim-plugins-neovim-require-check} +`neovimRequireCheck` is a simple test which checks if Neovim can requires lua modules without errors. This is often enough to catch missing dependencies. + +It accepts a single string for a module, or a list of module strings to test. +- `nvimRequireCheck = MODULE;` +- `nvimRequireCheck = [ MODULE1 MODULE2 ];` + +When `nvimRequireCheck` is not specified, we will search the plugin's directory for lua modules to attempt loading. This quick smoke test can catch obvious dependency errors that might be missed. +The check hook will fail the build if any modules cannot be loaded. This encourages inspecting the logs to identify potential issues. + +To only check a specific module, add it manually to the plugin definition [overrides](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/overrides.nix). + +```nix + gitsigns-nvim = super.gitsigns-nvim.overrideAttrs { + dependencies = [ self.plenary-nvim ]; + nvimRequireCheck = "gitsigns"; + }; +``` +Some plugins will have lua modules that require a user configuration to function properly or can contain optional lua modules that we dont want to test requiring. +We can skip specific modules using `nvimSkipModule`. Similar to `nvimRequireCheck`, it accepts a single string or a list of strings. +- `nvimSkipModule = MODULE;` +- `nvimSkipModule = [ MODULE1 MODULE2 ];` + +```nix + asyncrun-vim = super.asyncrun-vim.overrideAttrs { + nvimSkipModule = [ + # vim plugin with optional toggleterm integration + "asyncrun.toggleterm" + "asyncrun.toggleterm2" + ]; + }; +``` + +In rare cases, we might not want to actually test loading lua modules for a plugin. In those cases, we can disable `neovimRequireCheck` with `doCheck = false;`. + +This can be manually added through plugin definition overrides in the [overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/overrides.nix). +```nix + vim-test = super.vim-test.overrideAttrs { + # Vim plugin with a test lua file + doCheck = false; + }; +``` diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md index 0b5c26ef44a08..9d7dab9eb496a 100644 --- a/doc/languages-frameworks/vim.section.md +++ b/doc/languages-frameworks/vim.section.md @@ -1,7 +1,6 @@ # Vim {#vim} -Both Neovim and Vim can be configured to include your favorite plugins -and additional libraries. +Vim can be configured to include your favorite plugins and additional libraries. Loading can be deferred; see examples. @@ -19,7 +18,7 @@ build-time features are configurable. It has nothing to do with user configurati and both the `vim` and `vim-full` packages can be customized as explained in the next section. ::: -## Custom configuration {#custom-configuration} +## Custom configuration {#vim-custom-configuration} Adding custom .vimrc lines can be done using the following code: @@ -39,32 +38,6 @@ You can also omit `name` to customize Vim itself. See the [definition of `vimUtils.makeCustomizable`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/vim-utils.nix#L408) for all supported options. -For Neovim the `configure` argument can be overridden to achieve the same: - -```nix -neovim.override { - configure = { - customRC = '' - # here your custom configuration goes! - ''; - }; -} -``` - -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: - -```nix -neovim-qt.override { - neovim = neovim.override { - configure = { - customRC = '' - # your custom configuration - ''; - }; - }; -} -``` ## Managing plugins with Vim packages {#managing-plugins-with-vim-packages} @@ -166,33 +139,6 @@ in If your package requires building specific parts, use instead `pkgs.vimUtils.buildVimPlugin`. -### Specificities for some plugins {#vim-plugin-specificities} -#### Treesitter {#vim-plugin-treesitter} - -By default `nvim-treesitter` encourages you to download, compile and install -the required Treesitter grammars at run time with `:TSInstall`. This works -poorly on NixOS. Instead, to install the `nvim-treesitter` plugins with a set -of precompiled grammars, you can use `nvim-treesitter.withPlugins` function: - -```nix -(pkgs.neovim.override { - configure = { - packages.myPlugins = with pkgs.vimPlugins; { - start = [ - (nvim-treesitter.withPlugins ( - plugins: with plugins; [ - nix - python - ] - )) - ]; - }; - }; -}) -``` - -To enable all grammars packaged in nixpkgs, use `pkgs.vimPlugins.nvim-treesitter.withAllGrammars`. - ## Managing plugins with vim-plug {#managing-plugins-with-vim-plug} To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim @@ -232,50 +178,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. -### Testing Neovim plugins {#testing-neovim-plugins} - -#### neovimRequireCheck {#testing-neovim-plugins-neovim-require-check} -`neovimRequireCheck` is a simple test which checks if Neovim can requires lua modules without errors. This is often enough to catch missing dependencies. - -It accepts a single string for a module, or a list of module strings to test. -- `nvimRequireCheck = MODULE;` -- `nvimRequireCheck = [ MODULE1 MODULE2 ];` - -When `nvimRequireCheck` is not specified, we will search the plugin's directory for lua modules to attempt loading. This quick smoke test can catch obvious dependency errors that might be missed. -The check hook will fail the build if any failures are detected to encourage inspecting the logs to identify potential issues. - -If you would like to only check a specific module, this can be manually added through plugin definition overrides in the [overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/overrides.nix). - -```nix - gitsigns-nvim = super.gitsigns-nvim.overrideAttrs { - dependencies = [ self.plenary-nvim ]; - nvimRequireCheck = "gitsigns"; - }; -``` -Some plugins will have lua modules that require a user configuration to function properly or can contain optional lua modules that we dont want to test requiring. -We can skip specific modules using `nvimSkipModule`. Similar to `nvimRequireCheck`, it accepts a single string or a list of strings. -- `nvimSkipModule = MODULE;` -- `nvimSkipModule = [ MODULE1 MODULE2 ];` - -```nix - asyncrun-vim = super.asyncrun-vim.overrideAttrs { - nvimSkipModule = [ - # vim plugin with optional toggleterm integration - "asyncrun.toggleterm" - "asyncrun.toggleterm2" - ]; - }; -``` - -In rare cases, we might not want to actually test loading lua modules for a plugin. In those cases, we can disable `neovimRequireCheck` with `doCheck = false;`. - -This can be manually added through plugin definition overrides in the [overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/overrides.nix). -```nix - vim-test = super.vim-test.overrideAttrs { - # Vim plugin with a test lua file - doCheck = false; - }; -``` ### Plugin optional configuration {#vim-plugin-required-snippet} diff --git a/doc/redirects.json b/doc/redirects.json index d5360283e4613..254e6ceb6fc6e 100644 --- a/doc/redirects.json +++ b/doc/redirects.json @@ -2,6 +2,12 @@ "chap-release-notes": [ "release-notes.html#chap-release-notes" ], + "neovim": [ + "index.html#neovim" + ], + "neovim-custom-configuration": [ + "index.html#neovim-custom-configuration" + ], "nixpkgs-manual": [ "index.html#nixpkgs-manual" ], @@ -3763,7 +3769,8 @@ "vim": [ "index.html#vim" ], - "custom-configuration": [ + "vim-custom-configuration": [ + "index.html#vim-custom-configuration", "index.html#custom-configuration" ], "managing-plugins-with-vim-packages": [ @@ -3772,10 +3779,12 @@ "what-if-your-favourite-vim-plugin-isnt-already-packaged": [ "index.html#what-if-your-favourite-vim-plugin-isnt-already-packaged" ], - "vim-plugin-specificities": [ - "index.html#vim-plugin-specificities" + "neovim-plugin-specificities": [ + "index.html#neovim-plugin-specificities", + "neovim-plugin-specificities#vim-plugin-specificities" ], - "vim-plugin-treesitter": [ + "neovim-plugin-treesitter": [ + "index.html#neovim-plugin-treesitter", "index.html#vim-plugin-treesitter" ], "managing-plugins-with-vim-plug": [