diff options
Diffstat (limited to 'nixpkgs/doc/languages-frameworks/vim.section.md')
| -rw-r--r-- | nixpkgs/doc/languages-frameworks/vim.section.md | 168 |
1 files changed, 95 insertions, 73 deletions
diff --git a/nixpkgs/doc/languages-frameworks/vim.section.md b/nixpkgs/doc/languages-frameworks/vim.section.md index c450a09f7bd2..537e7b93e523 100644 --- a/nixpkgs/doc/languages-frameworks/vim.section.md +++ b/nixpkgs/doc/languages-frameworks/vim.section.md @@ -21,7 +21,7 @@ At the moment we support three different methods for managing plugins: Adding custom .vimrc lines can be done using the following code: -``` +```nix vim_configurable.customize { # `name` specifies the name of the executable and package name = "vim-with-plugins"; @@ -32,11 +32,11 @@ vim_configurable.customize { } ``` -This configuration is used when vim is invoked with the command specified as name, in this case `vim-with-plugins`. +This configuration is used when Vim is invoked with the command specified as name, in this case `vim-with-plugins`. For Neovim the `configure` argument can be overridden to achieve the same: -``` +```nix neovim.override { configure = { customRC = '' @@ -46,10 +46,10 @@ neovim.override { } ``` -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 neovimn: +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 Neovimn: -``` +```nix neovim-qt.override { neovim = neovim.override { configure = { @@ -63,16 +63,16 @@ neovim-qt.override { ## 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: +To store you plugins in Vim packages (the native Vim plugin manager, see `:help packages`) the following example can be used: -``` +```nix vim_configurable.customize { vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; { # loaded on launch start = [ youcompleteme fugitive ]; # manually loadable by calling `:packadd $plugin-name` - # however, 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. + # however, 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 = [ phpCompletion elm-vim ]; # To automatically load a plugin when opening a filetype, add vimrc lines like: # autocmd FileType php :packadd phpCompletion @@ -83,7 +83,7 @@ vim_configurable.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 = '' @@ -92,7 +92,7 @@ neovim.override { 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 + # 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 = [ ]; }; @@ -102,7 +102,7 @@ neovim.override { The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.nix` to make it installable: -``` +```nix { packageOverrides = pkgs: with pkgs; { myVim = vim_configurable.customize { @@ -126,7 +126,7 @@ After that you can install your special grafted `myVim` or `myNeovim` packages. To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim plugins the following example can be used: -``` +```nix vim_configurable.customize { vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; { # loaded on launch @@ -137,7 +137,7 @@ vim_configurable.customize { For Neovim the syntax is: -``` +```nix neovim.override { configure = { customRC = '' @@ -161,89 +161,112 @@ assuming that "using latest version" is ok most of the time. First create a vim-scripts file having one plugin name per line. Example: - "tlib" - {'name': 'vim-addon-sql'} - {'filetype_regex': '\%(vim)$', 'names': ['reload', 'vim-dev-plugin']} +``` +"tlib" +{'name': 'vim-addon-sql'} +{'filetype_regex': '\%(vim)$', 'names': ['reload', 'vim-dev-plugin']} +``` Such vim-scripts file can be read by VAM as well like this: - call vam#Scripts(expand('~/.vim-scripts'), {}) +```vim +call vam#Scripts(expand('~/.vim-scripts'), {}) +``` Create a default.nix file: - { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }: - nixpkgs.vim_configurable.customize { name = "vim"; vimrcConfig.vam.pluginDictionaries = [ "vim-addon-vim2nix" ]; } +```nix +{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }: +nixpkgs.vim_configurable.customize { name = "vim"; vimrcConfig.vam.pluginDictionaries = [ "vim-addon-vim2nix" ]; } +``` Create a generate.vim file: - ActivateAddons vim-addon-vim2nix - let vim_scripts = "vim-scripts" - call nix#ExportPluginsForNix({ - \ 'path_to_nixpkgs': eval('{"'.substitute(substitute(substitute($NIX_PATH, ':', ',', 'g'), '=',':', 'g'), '\([:,]\)', '"\1"',"g").'"}')["nixpkgs"], - \ 'cache_file': '/tmp/vim2nix-cache', - \ 'try_catch': 0, - \ 'plugin_dictionaries': ["vim-addon-manager"]+map(readfile(vim_scripts), 'eval(v:val)') - \ }) +```vim +ActivateAddons vim-addon-vim2nix +let vim_scripts = "vim-scripts" +call nix#ExportPluginsForNix({ +\ 'path_to_nixpkgs': eval('{"'.substitute(substitute(substitute($NIX_PATH, ':', ',', 'g'), '=',':', 'g'), '\([:,]\)', '"\1"',"g").'"}')["nixpkgs"], +\ 'cache_file': '/tmp/vim2nix-cache', +\ 'try_catch': 0, +\ 'plugin_dictionaries': ["vim-addon-manager"]+map(readfile(vim_scripts), 'eval(v:val)') +\ }) +``` Then run - nix-shell -p vimUtils.vim_with_vim2nix --command "vim -c 'source generate.vim'" +```bash +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": +You can add your Vim to your system's configuration file like this and start it by "vim-my": - my-vim = - let plugins = let inherit (vimUtils) buildVimPluginFrom2Nix; in { - copy paste output1 here - }; in vim_configurable.customize { - name = "vim-my"; - - vimrcConfig.vam.knownPlugins = plugins; # optional - vimrcConfig.vam.pluginDictionaries = [ - copy paste output2 here - ]; - - # Pathogen would be - # vimrcConfig.pathogen.knownPlugins = plugins; # plugins - # vimrcConfig.pathogen.pluginNames = ["tlib"]; - }; +``` +my-vim = + let plugins = let inherit (vimUtils) buildVimPluginFrom2Nix; in { + copy paste output1 here + }; in vim_configurable.customize { + name = "vim-my"; + + vimrcConfig.vam.knownPlugins = plugins; # optional + vimrcConfig.vam.pluginDictionaries = [ + copy paste output2 here + ]; + # Pathogen would be + # vimrcConfig.pathogen.knownPlugins = plugins; # plugins + # vimrcConfig.pathogen.pluginNames = ["tlib"]; + }; +``` Sample output1: - "reload" = buildVimPluginFrom2Nix { # created by nix#NixDerivation - name = "reload"; - src = fetchgit { - url = "git://github.com/xolox/vim-reload"; - rev = "0a601a668727f5b675cb1ddc19f6861f3f7ab9e1"; - sha256 = "0vb832l9yxj919f5hfg6qj6bn9ni57gnjd3bj7zpq7d4iv2s4wdh"; - }; - dependencies = ["nim-misc"]; +``` +"reload" = buildVimPluginFrom2Nix { # created by nix#NixDerivation + name = "reload"; + src = fetchgit { + url = "git://github.com/xolox/vim-reload"; + rev = "0a601a668727f5b675cb1ddc19f6861f3f7ab9e1"; + sha256 = "0vb832l9yxj919f5hfg6qj6bn9ni57gnjd3bj7zpq7d4iv2s4wdh"; + }; + dependencies = ["nim-misc"]; - }; - [...] +}; +[...] +``` Sample output2: - [ - ''vim-addon-manager'' - ''tlib'' - { "name" = ''vim-addon-sql''; } - { "filetype_regex" = ''\%(vim)$$''; "names" = [ ''reload'' ''vim-dev-plugin'' ]; } - ] - +```nix +[ + ''vim-addon-manager'' + ''tlib'' + { "name" = ''vim-addon-sql''; } + { "filetype_regex" = ''\%(vim)$$''; "names" = [ ''reload'' ''vim-dev-plugin'' ]; } +] +``` ## Adding new plugins to nixpkgs -In `pkgs/misc/vim-plugins/vim-plugin-names` we store the plugin names -for all vim plugins we automatically generate plugins for. -The format of this file `github username/github repository`: -For example https://github.com/scrooloose/nerdtree becomes `scrooloose/nerdtree`. -After adding your plugin to this file run the `./update.py` in the same folder. -This will updated a file called `generated.nix` and make your plugin accessible in the -`vimPlugins` attribute set (`vimPlugins.nerdtree` in our example). -If additional steps to the build process of the plugin are required, add an -override to the `pkgs/misc/vim-plugins/default.nix` in the same directory. +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: + +``` +deoplete-fish = super.deoplete-fish.overrideAttrs(old: { + dependencies = with super; [ deoplete-nvim vim-fish ]; +}); +``` + +Sometimes 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`. + +To add a new plugin: + + 1. run `./update.py` and create a commit named "vimPlugins: Update", + 2. add the new plugin to [vim-plugin-names](/pkgs/misc/vim-plugins/vim-plugin-names) and add overrides if required to [overrides.nix](/pkgs/misc/vim-plugins/overrides.nix), + 3. run `./update.py` again and create a commit named "vimPlugins.[name]: init at [version]" (where `name` and `version` can be found in [generated.nix](/pkgs/misc/vim-plugins/generated.nix)), and + 4. create a pull request. ## Important repositories @@ -252,4 +275,3 @@ override to the `pkgs/misc/vim-plugins/default.nix` in the same directory. - [vim2nix](https://github.com/MarcWeber/vim-addon-vim2nix) which generates the .nix code - |