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