diff options
Diffstat (limited to 'doc/languages-frameworks/vim.section.md')
-rw-r--r-- | doc/languages-frameworks/vim.section.md | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md new file mode 100644 index 0000000000000..1d6a4fe8da8d6 --- /dev/null +++ b/doc/languages-frameworks/vim.section.md @@ -0,0 +1,135 @@ +--- +title: User's Guide for Vim in Nixpkgs +author: Marc Weber +date: 2016-06-25 +--- +# User's Guide to Vim Plugins/Addons/Bundles/Scripts in Nixpkgs + +You'll get a vim(-your-suffix) in PATH also loading the plugins you want. +Loading can be deferred; see examples. + +Vim packages, VAM (=vim-addon-manager) and Pathogen are supported to load +packages. + +## Custom configuration + +Adding custom .vimrc lines can be done using the following code: + +``` +vim_configurable.customize { + name = "vim-with-plugins"; + + vimrcConfig.customRC = '' + set hidden + ''; +} +``` + +## Vim packages + +To store you plugins in Vim packages the following example can be used: + +``` +vim_configurable.customize { + vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; { + # loaded on launch + start = [ youcompleteme fugitive ]; + # manually loadable by calling `:packadd $plugin-name` + opt = [ phpCompletion elm-vim ]; + # To automatically load a plugin when opening a filetype, add vimrc lines like: + # autocmd FileType php :packadd phpCompletion + } +}; +``` + +## VAM + +### dependencies by Vim plugins + +VAM introduced .json files supporting dependencies without versioning +assuming that "using latest version" is ok most of the time. + +### Example + +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']} + +Such vim-scripts file can be read by VAM as well like this: + + 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" ]; } + +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)') + \ }) + +Then run + + 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": + + 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"]; + + }; + [...] + +Sample output2: + + [ + ''vim-addon-manager'' + ''tlib'' + { "name" = ''vim-addon-sql''; } + { "filetype_regex" = ''\%(vim)$$''; "names" = [ ''reload'' ''vim-dev-plugin'' ]; } + ] + + +## Important repositories + +- [vim-pi](https://bitbucket.org/vimcommunity/vim-pi) is a plugin repository + from VAM plugin manager meant to be used by others as well used by + +- [vim2nix](http://github.com/MarcWeber/vim-addon-vim2nix) which generates the + .nix code + |