nixpkgs/doc/languages-frameworks/vim.section.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

272 lines
9.7 KiB
Markdown
Raw Normal View History

# Vim {#vim}
2018-09-09 08:45:45 +00:00
Both Neovim and Vim can be configured to include your favorite plugins
and additional libraries.
2017-01-30 17:27:44 +00:00
Loading can be deferred; see examples.
At the moment we support two different methods for managing plugins:
2018-09-09 08:45:45 +00:00
- Vim packages (*recommended*)
- vim-plug (vim only)
Right now two Vim packages are available: `vim` which has most features that require extra
dependencies disabled and `vim-full` which has them configurable and enabled by default.
::: {.note}
`vim_configurable` is a deprecated alias for `vim-full` and refers to the fact that its
build-time features are configurable. It has nothing to do with user configuration,
and both the `vim` and `vim-full` packages can be customized as explained in the next section.
:::
## Custom configuration {#custom-configuration}
Adding custom .vimrc lines can be done using the following code:
2019-07-15 00:13:34 +00:00
```nix
vim-full.customize {
# `name` optionally specifies the name of the executable and package
name = "vim-with-plugins";
vimrcConfig.customRC = ''
set hidden
'';
}
```
2019-07-15 00:13:34 +00:00
This configuration is used when Vim is invoked with the command specified as name, in this case `vim-with-plugins`.
You can also omit `name` to customize Vim itself. See the
[definition of `vimUtils.makeCustomizable`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/vim-utils.nix#L408)
for all supported options.
2018-09-09 08:45:45 +00:00
For Neovim the `configure` argument can be overridden to achieve the same:
2019-07-15 00:13:34 +00:00
```nix
2018-09-09 08:45:45 +00:00
neovim.override {
configure = {
customRC = ''
# here your custom configuration goes!
'';
};
}
```
2019-07-15 00:13:34 +00:00
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 Neovim:
2019-01-05 12:58:00 +00:00
2019-07-15 00:13:34 +00:00
```nix
2019-01-05 12:58:00 +00:00
neovim-qt.override {
neovim = neovim.override {
configure = {
customRC = ''
# your custom configuration
'';
};
};
}
```
## Managing plugins with Vim packages {#managing-plugins-with-vim-packages}
To store your plugins in Vim packages (the native Vim plugin manager, see `:help packages`) the following example can be used:
2019-07-15 00:13:34 +00:00
```nix
vim-full.customize {
vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
# loaded on launch
start = [ youcompleteme fugitive ];
# manually loadable by calling `:packadd $plugin-name`
2019-07-15 00:13:34 +00:00
# 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
2018-09-09 08:45:45 +00:00
};
}
```
`myVimPackage` is an arbitrary name for the generated package. You can choose any name you like.
2018-09-20 07:05:33 +00:00
For Neovim the syntax is:
2018-09-09 08:45:45 +00:00
2019-07-15 00:13:34 +00:00
```nix
2018-09-09 08:45:45 +00:00
neovim.override {
configure = {
customRC = ''
# here your custom configuration goes!
'';
packages.myVimPackage = with pkgs.vimPlugins; {
# see examples below how to use custom packages
start = [ ];
2019-07-15 00:13:34 +00:00
# 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.
2018-09-09 08:45:45 +00:00
opt = [ ];
};
};
}
```
The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.nix` to make it installable:
2019-07-15 00:13:34 +00:00
```nix
2018-09-09 08:45:45 +00:00
{
packageOverrides = pkgs: with pkgs; {
myVim = vim-full.customize {
# `name` specifies the name of the executable and package
2018-09-09 08:45:45 +00:00
name = "vim-with-plugins";
# add here code from the example section
};
myNeovim = neovim.override {
configure = {
# add code from the example section here
2018-09-09 08:45:45 +00:00
};
};
};
}
```
After that you can install your special grafted `myVim` or `myNeovim` packages.
### What if your favourite Vim plugin isnt already packaged? {#what-if-your-favourite-vim-plugin-isnt-already-packaged}
If one of your favourite plugins isn't packaged, you can package it yourself:
```nix
{ config, pkgs, ... }:
let
easygrep = pkgs.vimUtils.buildVimPlugin {
name = "vim-easygrep";
src = pkgs.fetchFromGitHub {
owner = "dkprice";
repo = "vim-easygrep";
rev = "d0c36a77cc63c22648e792796b1815b44164653a";
hash = "sha256-bL33/S+caNmEYGcMLNCanFZyEYUOUmSsedCVBn4tV3g=";
};
};
in
{
environment.systemPackages = [
(
pkgs.neovim.override {
configure = {
packages.myPlugins = with pkgs.vimPlugins; {
start = [
vim-go # already packaged plugin
easygrep # custom package
];
opt = [];
};
# ...
};
}
)
];
}
```
If your package requires building specific parts, use instead `pkgs.vimUtils.buildVimPlugin`.
### Specificities for some plugins {#vim-plugin-specificities}
#### Treesitter {#vim-plugin-treesitter}
By default `nvim-treesitter` encourages you to download, compile and install
the required Treesitter grammars at run time with `:TSInstall`. This works
poorly on NixOS. Instead, to install the `nvim-treesitter` plugins with a set
of precompiled grammars, you can use `nvim-treesitter.withPlugins` function:
```nix
(pkgs.neovim.override {
configure = {
packages.myPlugins = with pkgs.vimPlugins; {
start = [
(nvim-treesitter.withPlugins (
plugins: with plugins; [
nix
python
]
))
];
};
};
})
```
To enable all grammars packaged in nixpkgs, use `pkgs.vimPlugins.nvim-treesitter.withAllGrammars`.
## Managing plugins with vim-plug {#managing-plugins-with-vim-plug}
2018-09-20 07:05:33 +00:00
To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim
plugins the following example can be used:
2018-09-20 07:05:33 +00:00
2019-07-15 00:13:34 +00:00
```nix
vim-full.customize {
2018-09-20 07:05:33 +00:00
vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
# loaded on launch
plug.plugins = [ youcompleteme fugitive phpCompletion elm-vim ];
};
}
```
Note: this is not possible anymore for Neovim.
2018-09-20 07:05:33 +00:00
## Adding new plugins to nixpkgs {#adding-new-plugins-to-nixpkgs}
Nix expressions for Vim plugins are stored in [pkgs/applications/editors/vim/plugins](https://github.com/NixOS/nixpkgs/tree/master/pkgs/applications/editors/vim/plugins). For the vast majority of plugins, Nix expressions are automatically generated by running [`nix-shell -p vimPluginsUpdater --run vim-plugins-updater`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/updater.nix). This creates a [generated.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/generated.nix) file based on the plugins listed in [vim-plugin-names](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/vim-plugin-names).
After running the updater, if nvim-treesitter received an update, also run [`nvim-treesitter/update.py`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/update.py) to update the tree sitter grammars for `nvim-treesitter`.
Some plugins require overrides in order to function properly. Overrides are placed in [overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/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:
2019-07-15 00:13:34 +00:00
```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, 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.
Finally, 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 the Language Server Protocol integration with Vim/Neovim.
## Updating plugins in nixpkgs {#updating-plugins-in-nixpkgs}
2020-10-28 20:47:00 +00:00
Run 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).
```sh
GITHUB_API_TOKEN=my_token ./pkgs/applications/editors/vim/plugins/update.py
2020-10-28 20:47:00 +00:00
```
Alternatively, set the number of processes to a lower count to avoid rate-limiting.
```sh
nix-shell -p vimPluginsUpdater --run 'vim-plugins-updater --proc 1'
2020-10-28 20:47:00 +00:00
```
## How to maintain an out-of-tree overlay of vim plugins ? {#vim-out-of-tree-overlays}
You can use the updater script to generate basic packages out of a custom vim
plugin list:
```
nix-shell -p vimPluginsUpdater --run vim-plugins-updater -i vim-plugin-names -o generated.nix --no-commit
```
with the contents of `vim-plugin-names` being for example:
```
repo,branch,alias
pwntester/octo.nvim,,
```
You can then reference the generated vim plugins via:
```nix
myVimPlugins = pkgs.vimPlugins.extend (
(pkgs.callPackage ./generated.nix {})
);
```