pyrox.dev
1# Vim {#vim}
2
3Both Neovim and Vim can be configured to include your favorite plugins
4and additional libraries.
5
6Loading can be deferred; see examples.
7
8At the moment we support three different methods for managing plugins:
9
10- Vim packages (*recommend*)
11- VAM (=vim-addon-manager)
12- Pathogen
13- vim-plug
14
15## Custom configuration
16
17Adding custom .vimrc lines can be done using the following code:
18
19```nix
20vim_configurable.customize {
21 # `name` specifies the name of the executable and package
22 name = "vim-with-plugins";
23
24 vimrcConfig.customRC = ''
25 set hidden
26 '';
27}
28```
29
30This configuration is used when Vim is invoked with the command specified as name, in this case `vim-with-plugins`.
31
32For Neovim the `configure` argument can be overridden to achieve the same:
33
34```nix
35neovim.override {
36 configure = {
37 customRC = ''
38 # here your custom configuration goes!
39 '';
40 };
41}
42```
43
44If you want to use `neovim-qt` as a graphical editor, you can configure it by overriding Neovim in an overlay
45or passing it an overridden Neovimn:
46
47```nix
48neovim-qt.override {
49 neovim = neovim.override {
50 configure = {
51 customRC = ''
52 # your custom configuration
53 '';
54 };
55 };
56}
57```
58
59## Managing plugins with Vim packages
60
61To store you plugins in Vim packages (the native Vim plugin manager, see `:help packages`) the following example can be used:
62
63```nix
64vim_configurable.customize {
65 vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
66 # loaded on launch
67 start = [ youcompleteme fugitive ];
68 # manually loadable by calling `:packadd $plugin-name`
69 # however, if a Vim plugin has a dependency that is not explicitly listed in
70 # opt that dependency will always be added to start to avoid confusion.
71 opt = [ phpCompletion elm-vim ];
72 # To automatically load a plugin when opening a filetype, add vimrc lines like:
73 # autocmd FileType php :packadd phpCompletion
74 };
75}
76```
77
78`myVimPackage` is an arbitrary name for the generated package. You can choose any name you like.
79For Neovim the syntax is:
80
81```nix
82neovim.override {
83 configure = {
84 customRC = ''
85 # here your custom configuration goes!
86 '';
87 packages.myVimPackage = with pkgs.vimPlugins; {
88 # see examples below how to use custom packages
89 start = [ ];
90 # If a Vim plugin has a dependency that is not explicitly listed in
91 # opt that dependency will always be added to start to avoid confusion.
92 opt = [ ];
93 };
94 };
95}
96```
97
98The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.nix` to make it installable:
99
100```nix
101{
102 packageOverrides = pkgs: with pkgs; {
103 myVim = vim_configurable.customize {
104 # `name` specifies the name of the executable and package
105 name = "vim-with-plugins";
106 # add here code from the example section
107 };
108 myNeovim = neovim.override {
109 configure = {
110 # add here code from the example section
111 };
112 };
113 };
114}
115```
116
117After that you can install your special grafted `myVim` or `myNeovim` packages.
118
119### What if your favourite Vim plugin isn't already packaged?
120
121If one of your favourite plugins isn't packaged, you can package it yourself:
122
123```
124{ config, pkgs, ... }:
125
126let
127 easygrep = pkgs.vimUtils.buildVimPlugin {
128 name = "vim-easygrep";
129 src = pkgs.fetchFromGitHub {
130 owner = "dkprice";
131 repo = "vim-easygrep";
132 rev = "d0c36a77cc63c22648e792796b1815b44164653a";
133 sha256 = "0y2p5mz0d5fhg6n68lhfhl8p4mlwkb82q337c22djs4w5zyzggbc";
134 };
135 };
136in
137{
138 environment.systemPackages = [
139 (
140 pkgs.neovim.override {
141 configure = {
142 packages.myPlugins = with pkgs.vimPlugins; {
143 start = [
144 vim-go # already packaged plugin
145 easygrep # custom package
146 ];
147 opt = [];
148 };
149 # ...
150 };
151 }
152 )
153 ];
154}
155```
156
157## Managing plugins with vim-plug
158
159To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim
160plugins the following example can be used:
161
162```nix
163vim_configurable.customize {
164 vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
165 # loaded on launch
166 plug.plugins = [ youcompleteme fugitive phpCompletion elm-vim ];
167 };
168}
169```
170
171For Neovim the syntax is:
172
173```nix
174neovim.override {
175 configure = {
176 customRC = ''
177 # here your custom configuration goes!
178 '';
179 plug.plugins = with pkgs.vimPlugins; [
180 vim-go
181 ];
182 };
183}
184```
185
186## Managing plugins with VAM
187
188### Handling dependencies of Vim plugins
189
190VAM introduced .json files supporting dependencies without versioning
191assuming that "using latest version" is ok most of the time.
192
193### Example
194
195First create a vim-scripts file having one plugin name per line. Example:
196
197```vim
198"tlib"
199{'name': 'vim-addon-sql'}
200{'filetype_regex': '\%(vim)$', 'names': ['reload', 'vim-dev-plugin']}
201```
202
203Such vim-scripts file can be read by VAM as well like this:
204
205```vim
206call vam#Scripts(expand('~/.vim-scripts'), {})
207```
208
209Create a default.nix file:
210
211```nix
212{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
213nixpkgs.vim_configurable.customize { name = "vim"; vimrcConfig.vam.pluginDictionaries = [ "vim-addon-vim2nix" ]; }
214```
215
216Create a generate.vim file:
217
218```vim
219ActivateAddons vim-addon-vim2nix
220let vim_scripts = "vim-scripts"
221call nix#ExportPluginsForNix({
222\ 'path_to_nixpkgs': eval('{"'.substitute(substitute(substitute($NIX_PATH, ':', ',', 'g'), '=',':', 'g'), '\([:,]\)', '"\1"',"g").'"}')["nixpkgs"],
223\ 'cache_file': '/tmp/vim2nix-cache',
224\ 'try_catch': 0,
225\ 'plugin_dictionaries': ["vim-addon-manager"]+map(readfile(vim_scripts), 'eval(v:val)')
226\ })
227```
228
229Then run
230
231```bash
232nix-shell -p vimUtils.vim_with_vim2nix --command "vim -c 'source generate.vim'"
233```
234
235You should get a Vim buffer with the nix derivations (output1) and vam.pluginDictionaries (output2).
236You can add your Vim to your system's configuration file like this and start it by "vim-my":
237
238```nix
239my-vim =
240 let plugins = let inherit (vimUtils) buildVimPluginFrom2Nix; in {
241 copy paste output1 here
242 }; in vim_configurable.customize {
243 name = "vim-my";
244
245 vimrcConfig.vam.knownPlugins = plugins; # optional
246 vimrcConfig.vam.pluginDictionaries = [
247 copy paste output2 here
248 ];
249
250 # Pathogen would be
251 # vimrcConfig.pathogen.knownPlugins = plugins; # plugins
252 # vimrcConfig.pathogen.pluginNames = ["tlib"];
253 };
254```
255
256Sample output1:
257
258```nix
259"reload" = buildVimPluginFrom2Nix { # created by nix#NixDerivation
260 name = "reload";
261 src = fetchgit {
262 url = "git://github.com/xolox/vim-reload";
263 rev = "0a601a668727f5b675cb1ddc19f6861f3f7ab9e1";
264 sha256 = "0vb832l9yxj919f5hfg6qj6bn9ni57gnjd3bj7zpq7d4iv2s4wdh";
265 };
266 dependencies = ["nim-misc"];
267
268};
269[...]
270```
271
272Sample output2:
273
274```nix
275[
276 ''vim-addon-manager''
277 ''tlib''
278 { "name" = ''vim-addon-sql''; }
279 { "filetype_regex" = ''\%(vim)$$''; "names" = [ ''reload'' ''vim-dev-plugin'' ]; }
280]
281```
282
283## Adding new plugins to nixpkgs
284
285Nix 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`.
286
287Some 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:
288
289```nix
290deoplete-fish = super.deoplete-fish.overrideAttrs(old: {
291 dependencies = with super; [ deoplete-nvim vim-fish ];
292});
293```
294
295Sometimes plugins require an override that must be changed when the plugin is updated. This can cause issues when Vim plugins are auto-updated but the associated override isn't updated. For these plugins, the override should be written so that it specifies all information required to install the plugin, and running `./update.py` doesn't change the derivation for the plugin. Manually updating the override is required to update these types of plugins. An example of such a plugin is `LanguageClient-neovim`.
296
297To 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.
298
299Finally, 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.
300
301## Updating plugins in nixpkgs
302
303Run 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).
304
305```sh
306GITHUB_API_TOKEN=my_token ./pkgs/misc/vim-plugins/update.py
307```
308
309Alternatively, set the number of processes to a lower count to avoid rate-limiting.
310
311```sh
312./pkgs/misc/vim-plugins/update.py --proc 1
313```
314
315## Important repositories
316
317- [vim-pi](https://bitbucket.org/vimcommunity/vim-pi) is a plugin repository
318 from VAM plugin manager meant to be used by others as well used by
319
320- [vim2nix](https://github.com/MarcWeber/vim-addon-vim2nix) which generates the
321 .nix code