diff options
Diffstat (limited to 'doc/languages-frameworks/vim.section.md')
| -rw-r--r-- | doc/languages-frameworks/vim.section.md | 112 |
1 files changed, 94 insertions, 18 deletions
diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md index 4911509212e..26a01a89aa5 100644 --- a/doc/languages-frameworks/vim.section.md +++ b/doc/languages-frameworks/vim.section.md @@ -1,9 +1,4 @@ ---- -title: User's Guide for Vim in Nixpkgs -author: Marc Weber -date: 2016-06-25 ---- -# Vim +# Vim {#vim} Both Neovim and Vim can be configured to include your favorite plugins and additional libraries. @@ -17,7 +12,7 @@ At the moment we support three different methods for managing plugins: - Pathogen - vim-plug -## Custom configuration +## Custom configuration {#custom-configuration} Adding custom .vimrc lines can be done using the following code: @@ -61,7 +56,7 @@ neovim-qt.override { } ``` -## Managing plugins with Vim packages +## Managing plugins with Vim packages {#managing-plugins-with-vim-packages} To store you plugins in Vim packages (the native Vim plugin manager, see `:help packages`) the following example can be used: @@ -121,7 +116,72 @@ The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.n After that you can install your special grafted `myVim` or `myNeovim` packages. -## Managing plugins with vim-plug +### What if your favourite Vim plugin isn’t already packaged? {#what-if-your-favourite-vim-plugin-isnt-already-packaged} + +If one of your favourite plugins isn't packaged, you can package it yourself: + +```nix +{ config, pkgs, ... }: + +let + easygrep = pkgs.vimUtils.buildVimPlugin { + name = "vim-easygrep"; + src = pkgs.fetchFromGitHub { + owner = "dkprice"; + repo = "vim-easygrep"; + rev = "d0c36a77cc63c22648e792796b1815b44164653a"; + sha256 = "0y2p5mz0d5fhg6n68lhfhl8p4mlwkb82q337c22djs4w5zyzggbc"; + }; + }; +in +{ + environment.systemPackages = [ + ( + pkgs.neovim.override { + configure = { + packages.myPlugins = with pkgs.vimPlugins; { + start = [ + vim-go # already packaged plugin + easygrep # custom package + ]; + opt = []; + }; + # ... + }; + } + ) + ]; +} +``` + +### Specificities for some plugins +#### Tree sitter + +By default `nvim-treesitter` encourages you to download, compile and install +the required tree-sitter 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; [ + tree-sitter-nix + tree-sitter-python + ] + )) + ]; + }; + }; +}) +``` + +To enable all grammars packaged in nixpkgs, use `(pkgs.vimPlugins.nvim-treesitter.withPlugins (plugins: pkgs.tree-sitter.allGrammars))`. + +## Managing plugins with vim-plug {#managing-plugins-with-vim-plug} To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim plugins the following example can be used: @@ -150,18 +210,18 @@ neovim.override { } ``` -## Managing plugins with VAM +## Managing plugins with VAM {#managing-plugins-with-vam} -### Handling dependencies of Vim plugins +### Handling dependencies of Vim plugins {#handling-dependencies-of-vim-plugins} VAM introduced .json files supporting dependencies without versioning assuming that "using latest version" is ok most of the time. -### Example +### Example {#example} First create a vim-scripts file having one plugin name per line. Example: -``` +```vim "tlib" {'name': 'vim-addon-sql'} {'filetype_regex': '\%(vim)$', 'names': ['reload', 'vim-dev-plugin']} @@ -202,7 +262,7 @@ nix-shell -p vimUtils.vim_with_vim2nix --command "vim -c 'source generate.vim'" You should get a Vim buffer with the nix derivations (output1) and vam.pluginDictionaries (output2). You can add your Vim to your system's configuration file like this and start it by "vim-my": -``` +```nix my-vim = let plugins = let inherit (vimUtils) buildVimPluginFrom2Nix; in { copy paste output1 here @@ -222,7 +282,7 @@ my-vim = Sample output1: -``` +```nix "reload" = buildVimPluginFrom2Nix { # created by nix#NixDerivation name = "reload"; src = fetchgit { @@ -247,13 +307,13 @@ Sample output2: ] ``` -## Adding new plugins to nixpkgs +## Adding new plugins to nixpkgs {#adding-new-plugins-to-nixpkgs} Nix expressions for Vim plugins are stored in [pkgs/misc/vim-plugins](/pkgs/misc/vim-plugins). For the vast majority of plugins, Nix expressions are automatically generated by running [`./update.py`](/pkgs/misc/vim-plugins/update.py). This creates a [generated.nix](/pkgs/misc/vim-plugins/generated.nix) file based on the plugins listed in [vim-plugin-names](/pkgs/misc/vim-plugins/vim-plugin-names). Plugins are listed in alphabetical order in `vim-plugin-names` using the format `[github username]/[repository]`. For example https://github.com/scrooloose/nerdtree becomes `scrooloose/nerdtree`. Some plugins require overrides in order to function properly. Overrides are placed in [overrides.nix](/pkgs/misc/vim-plugins/overrides.nix). Overrides are most often required when a plugin requires some dependencies, or extra steps are required during the build process. For example `deoplete-fish` requires both `deoplete-nvim` and `vim-fish`, and so the following override was added: -``` +```nix deoplete-fish = super.deoplete-fish.overrideAttrs(old: { dependencies = with super; [ deoplete-nvim vim-fish ]; }); @@ -263,7 +323,23 @@ Sometimes plugins require an override that must be changed when the plugin is up To add a new plugin, run `./update.py --add "[owner]/[name]"`. **NOTE**: This script automatically commits to your git repository. Be sure to check out a fresh branch before running. -## Important repositories +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 `update.py` at all, and are included separately in `overrides.nix`. Currently, all these plugins are related to the `coc.nvim` ecosystem of Language Server Protocol integration with vim/neovim. + +## 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). + +```sh +GITHUB_API_TOKEN=my_token ./pkgs/misc/vim-plugins/update.py +``` + +Alternatively, set the number of processes to a lower count to avoid rate-limiting. + +```sh +./pkgs/misc/vim-plugins/update.py --proc 1 +``` + +## Important repositories {#important-repositories} - [vim-pi](https://bitbucket.org/vimcommunity/vim-pi) is a plugin repository from VAM plugin manager meant to be used by others as well used by |