From 5d69e5f84bb29fd0d8abd9636717fc2899f919ba Mon Sep 17 00:00:00 2001 From: Malo Bourgon Date: Sun, 14 Jul 2019 16:38:00 -0700 Subject: [PATCH] Update documentation about adding new Vim plugins to nixpkgs --- doc/languages-frameworks/vim.section.md | 27 ++++++++++++++++--------- pkgs/misc/vim-plugins/readme.md | 1 + 2 files changed, 18 insertions(+), 10 deletions(-) create mode 100644 pkgs/misc/vim-plugins/readme.md diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md index c450a09f7bd..c75b6bd32fd 100644 --- a/doc/languages-frameworks/vim.section.md +++ b/doc/languages-frameworks/vim.section.md @@ -235,15 +235,23 @@ Sample output2: ## 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: +```nix +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 +260,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 - diff --git a/pkgs/misc/vim-plugins/readme.md b/pkgs/misc/vim-plugins/readme.md new file mode 100644 index 00000000000..0758a3e9598 --- /dev/null +++ b/pkgs/misc/vim-plugins/readme.md @@ -0,0 +1 @@ +Instructions for adding Vim plugins to `nixpkgs` can be found [here](/doc/languages-frameworks/vim.section.md).