alioth/nixpkgs
3
0
Fork 0
forked from mirrors/nixpkgs
Code Releases Activity

Merge pull request #64753 from malob/update-add-vim-plugin-docs

Browse source 
Updating documentation about adding new Vim plugins
This commit is contained in:
Michael Raskin 2019-08-02 21:25:16 +00:00 committed by GitHub
parent 7fb44be46b 2b6012ac39
commit 66644848cb
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 95 additions and 72 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

166
doc/languages-frameworks/vim.section.md
View file

@ -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: Adding custom .vimrc lines can be done using the following code:
``` ```nix
vim_configurable.customize { vim_configurable.customize {
# `name` specifies the name of the executable and package # `name` specifies the name of the executable and package
name = "vim-with-plugins"; 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: For Neovim the `configure` argument can be overridden to achieve the same:
``` ```nix
neovim.override { neovim.override {
configure = { configure = {
customRC = '' 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 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: or passing it an overridden Neovimn:
``` ```nix
neovim-qt.override { neovim-qt.override {
neovim = neovim.override { neovim = neovim.override {
configure = { configure = {
@ -63,16 +63,16 @@ neovim-qt.override {
## 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: 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 { vim_configurable.customize {
vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; { vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
# loaded on launch # loaded on launch
start = [ youcompleteme fugitive ]; start = [ youcompleteme fugitive ];
# manually loadable by calling `:packadd $plugin-name` # manually loadable by calling `:packadd $plugin-name`
# however, if a vim plugin has a dependency that is not explicitly listed in # 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 that dependency will always be added to start to avoid confusion.
opt = [ phpCompletion elm-vim ]; opt = [ phpCompletion elm-vim ];
# To automatically load a plugin when opening a filetype, add vimrc lines like: # To automatically load a plugin when opening a filetype, add vimrc lines like:
# autocmd FileType php :packadd phpCompletion # 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. `myVimPackage` is an arbitrary name for the generated package. You can choose any name you like.
For Neovim the syntax is: For Neovim the syntax is:
``` ```nix
neovim.override { neovim.override {
configure = { configure = {
customRC = '' customRC = ''
@ -92,7 +92,7 @@ neovim.override {
packages.myVimPackage = with pkgs.vimPlugins; { packages.myVimPackage = with pkgs.vimPlugins; {
# see examples below how to use custom packages # see examples below how to use custom packages
start = [ ]; 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 that dependency will always be added to start to avoid confusion.
opt = [ ]; opt = [ ];
}; };
@ -102,7 +102,7 @@ neovim.override {
The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.nix` to make it installable: The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.nix` to make it installable:
``` ```nix
{ {
packageOverrides = pkgs: with pkgs; { packageOverrides = pkgs: with pkgs; {
myVim = vim_configurable.customize { 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 To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim
plugins the following example can be used: plugins the following example can be used:
``` ```nix
vim_configurable.customize { vim_configurable.customize {
vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; { vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
# loaded on launch # loaded on launch
@ -137,7 +137,7 @@ vim_configurable.customize {
For Neovim the syntax is: For Neovim the syntax is:
``` ```nix
neovim.override { neovim.override {
configure = { configure = {
customRC = '' 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: First create a vim-scripts file having one plugin name per line. Example:
"tlib" ```
{'name': 'vim-addon-sql'} "tlib"
{'filetype_regex': '\%(vim)$', 'names': ['reload', 'vim-dev-plugin']} {'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: 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: Create a default.nix file:
{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }: ```nix
nixpkgs.vim_configurable.customize { name = "vim"; vimrcConfig.vam.pluginDictionaries = [ "vim-addon-vim2nix" ]; } { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
nixpkgs.vim_configurable.customize { name = "vim"; vimrcConfig.vam.pluginDictionaries = [ "vim-addon-vim2nix" ]; }
```
Create a generate.vim file: Create a generate.vim file:
ActivateAddons vim-addon-vim2nix ```vim
let vim_scripts = "vim-scripts" ActivateAddons vim-addon-vim2nix
call nix#ExportPluginsForNix({ let vim_scripts = "vim-scripts"
\ 'path_to_nixpkgs': eval('{"'.substitute(substitute(substitute($NIX_PATH, ':', ',', 'g'), '=',':', 'g'), '\([:,]\)', '"\1"',"g").'"}')["nixpkgs"], call nix#ExportPluginsForNix({
\ 'cache_file': '/tmp/vim2nix-cache', \ 'path_to_nixpkgs': eval('{"'.substitute(substitute(substitute($NIX_PATH, ':', ',', 'g'), '=',':', 'g'), '\([:,]\)', '"\1"',"g").'"}')["nixpkgs"],
\ 'try_catch': 0, \ 'cache_file': '/tmp/vim2nix-cache',
\ 'plugin_dictionaries': ["vim-addon-manager"]+map(readfile(vim_scripts), 'eval(v:val)') \ 'try_catch': 0,
\ }) \ 'plugin_dictionaries': ["vim-addon-manager"]+map(readfile(vim_scripts), 'eval(v:val)')
\ })
```
Then run 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 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 { my-vim =
copy paste output1 here let plugins = let inherit (vimUtils) buildVimPluginFrom2Nix; in {
}; in vim_configurable.customize { copy paste output1 here
name = "vim-my"; }; in vim_configurable.customize {
name = "vim-my";
vimrcConfig.vam.knownPlugins = plugins; # optional vimrcConfig.vam.knownPlugins = plugins; # optional
vimrcConfig.vam.pluginDictionaries = [ vimrcConfig.vam.pluginDictionaries = [
copy paste output2 here copy paste output2 here
]; ];
# Pathogen would be
# vimrcConfig.pathogen.knownPlugins = plugins; # plugins
# vimrcConfig.pathogen.pluginNames = ["tlib"];
};
# Pathogen would be
# vimrcConfig.pathogen.knownPlugins = plugins; # plugins
# vimrcConfig.pathogen.pluginNames = ["tlib"];
};
```
Sample output1: Sample output1:
"reload" = buildVimPluginFrom2Nix { # created by nix#NixDerivation ```
name = "reload"; "reload" = buildVimPluginFrom2Nix { # created by nix#NixDerivation
src = fetchgit { name = "reload";
url = "git://github.com/xolox/vim-reload"; src = fetchgit {
rev = "0a601a668727f5b675cb1ddc19f6861f3f7ab9e1"; url = "git://github.com/xolox/vim-reload";
sha256 = "0vb832l9yxj919f5hfg6qj6bn9ni57gnjd3bj7zpq7d4iv2s4wdh"; rev = "0a601a668727f5b675cb1ddc19f6861f3f7ab9e1";
}; sha256 = "0vb832l9yxj919f5hfg6qj6bn9ni57gnjd3bj7zpq7d4iv2s4wdh";
dependencies = ["nim-misc"]; };
dependencies = ["nim-misc"];
}; };
[...] [...]
```
Sample output2: Sample output2:
[ ```nix
''vim-addon-manager'' [
''tlib'' ''vim-addon-manager''
{ "name" = ''vim-addon-sql''; } ''tlib''
{ "filetype_regex" = ''\%(vim)$$''; "names" = [ ''reload'' ''vim-dev-plugin'' ]; } { "name" = ''vim-addon-sql''; }
] { "filetype_regex" = ''\%(vim)$$''; "names" = [ ''reload'' ''vim-dev-plugin'' ]; }
]
```
## Adding new plugins to nixpkgs ## Adding new plugins to nixpkgs
In `pkgs/misc/vim-plugins/vim-plugin-names` we store the plugin names 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`.
for all vim plugins we automatically generate plugins for.
The format of this file `github username/github repository`: 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:
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 deoplete-fish = super.deoplete-fish.overrideAttrs(old: {
`vimPlugins` attribute set (`vimPlugins.nerdtree` in our example). dependencies = with super; [ deoplete-nvim vim-fish ];
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. ```
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 ## 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 - [vim2nix](https://github.com/MarcWeber/vim-addon-vim2nix) which generates the
.nix code .nix code

1
pkgs/misc/vim-plugins/readme.md Normal file
View file

@ -0,0 +1 @@
Instructions for adding Vim plugins to `nixpkgs` can be found [here](/doc/languages-frameworks/vim.section.md).