Introduction

Envy is essentially a Nix-based plugin & configuration manager for neovim, providing:

• A convenient way to pin and package Vim plugins as Nix derivations.
• The ability for Vim plugin derivations to correctly depend on and pull in one another, and system dependencies (including plugin-native-language dependencies, C library dependencies, and executable dependencies).
• A Nix-based configuration mechanism that allows individual plugin configuration to depend on the install-time state of other plugins, dependencies, and potentially the system (in NixOS).
• A way to "layer" per-project plugins+configuration on top of per-user, in turn on top of per-system (albeit at a large memory cost at install-time).
• A method for existing users of NixOS/home-manager to tightly integrate neovim configuration into it, meaning that aspects of their neovim configuration can reliably depend upon aspects of their system or user configuration.
• A means to specify nvimrc configuration in vimscript, Lua, or MoonScript.
• More complexity than you want or need (probably).
• An end to world hunger.

The numbered chapters are intended to be read in order, as they build upon information in earlier chapters. The appendices are intended more as reference material.

Why?

Mostly because neovim plugin configuration is a bit of a clusterfuck. There's a deceptively (and increasingly) large amount of inherent complexity to the problem space, because neo/vim plugins can have dependencies on many axes (inter-plugin, external executable, Lua modules, remote host language modules, etc.), and those in turn have their own dependency closures, and may also depend on the system or user-level configuration.

Trying to reliably manage this cross-language, cross-system complexity using anything other than Nix quickly descends into either A) madness, or B) compromise. I'm not big on compromise.

1. Basic Usage

The main Envy module can basically be used in three different ways:

1. It can be used as a NixOS module, to configure neovim system-wide.
2. It can be used as a home-manager module, to configure neovim on a per-user basis.
3. It can be used standalone, e.g. in order to configure a custom neovim instance for a project's shell.nix.

In each of these uses, the module is configured in basically the same way, but adding/accessing the module to begin with differs.

Module Setup

Both the NixOS and home-manager modules expose the configuration interface under sn.programs.neovim in NixOS; if you want to use a different attribute path for it, take a look at the envy/nixos.nix/envy/home-manager.nix source and manually do the same.

Both modules take an enabled argument, which defaults to true, rather than exposing a sn.programs.neovim.enable option, due to a technical limitation.

NixOS

Add the envy/nixos.nix module to imports in your configuration.nix:

{ config, lib, pkgs, ... }:
let
  envy = (builtins.fetchgit { url = https://github.com/Shados/envy; ref = "master"; });
in
{
  imports = [
    (import "${envy}/nixos.nix" { })
    ...
  ];
  ...
}

home-manager

Add the envy/home-manager.nix module to imports in your configuration.nix:

{ config, lib, pkgs, ... }:
let
  envy = (builtins.fetchgit { url = https://github.com/Shados/envy; ref = "master"; });
in
{
  imports = [
    (import "${envy}/home-manager.nix" { mergeNixosDefinitions = false; })
    ...
  ];
  ...
}

mergeNixosDefinitions controls whether or not any sn.programs.neovim settings from the current system's NixOS configuration should be merged into the home-manager defintions. This allows for "layering" user-level neovim configuration on top of the system-wide config. It is false by default.

NOTE: You are likely better off just directly including your NixOS envy-configuration module in your hm config, if you want to layer the two, but this approach is not always possible/viable.

Standalone Setup

Usage as a standalone module is slightly more complicated, and is most easily done by use of the configuredNeovimModule in Envy's lib module:

{ nixpkgs ? import <nixpkgs> { } }:
let
  envy = (builtins.fetchgit { url = https://github.com/Shados/envy; ref = "master"; });
  envyLib = (import "${envy}/lib.nix" { inherit nixpkgs; });
  envyModule = envyLib.configuredNeovimModule {
    # Whether or not to merge in Envy config pulled from the current NixOS Envy
    # module configuration
    withNixosConfig = false;
    # Whether or not to merge in Envy config pulled from the current
    # home-manager-in-NixOS Envy module configuration
    withNixosHMConfig = false;
    # Whether or not to merge in Envy config pulled from the current
    # home-manager Envy module configuration
    withHMConfig = false;
    nvimConfig = { config, lib, pkgs, ... }: {
      # Envy module config here
      pluginRegistry = {
        ...
      };
    };
  }
in
nixpkgs.mkShell {
  ...
  buildInputs = [
    envyModule.wrappedNeovim
    ...
  ];
}

2. Module Configuration

The full set of available configuration options is documented in Appendix A; this chapter serves as an overview of the configuration process and provides examples of how the options may be used.

Broadly, the process for configuring Envy is:

1. Add non-plugin init.vim configuration.
2. Enable the plugins you want to use.
3. Specify any additional dependencies the plugins may have.
4. Add per-plugin configuration.
5. Pre-fetch and pin any shortname plugins (see chapter 3).

Non-plugin Configuration

Adapt your non-plugin init.vim configuration to use Envy's module options.

By "non-plugin" here we mean specifically things that either don't depend on/configure any plugin, or that could depend on any one of several plugins (in which case, you should use Nix functionality to check which/whether any of those plugins are enabled and adapt the generated configuration appropriately).

Envy provides a wide array of options here, so some examples may be helpful:

{ config, lib, pkgs, ... }:
{
  # Configuration items that should be done prior to any per-plugin configuration
  prePluginConfig = ''
    let mapleader = "\<Space>"
    augroup vimrc
      autocmd!
    augroup END
    set termguicolors
  '';
  # General configuration items that are appended to the end of the generated
  # vimrc. You can use e.g. `lib.mkAfter` if you need something to go at the
  # very end of the file.
  extraConfig = ''
    set incsearch
    set hlsearch
    set ignorecase
    set smartcase
    set number
    set relativenumber
    set autoindent
    set shiftwidth=2
    set softtabstop=2
    set tabstop=2
    set expandtab

    " Use Ripgrep (rg) for search backend
    let g:ackprg = '${pkgs.ripgrep}/bin/rg --vimgrep --smart-case --no-heading --max-filesize=4M'
    set grepprg:${pkgs.ripgrep}/bin/rg\ --vimgrep\ --smart-case\ --no-heading\ --max-filesize=4M

    nnoremap <Leader>o :exe ':silent !${pkgs.xdg-utils}/bin/xdg-open % &'<CR>
  '';
  # A list of packages whose executables should be added to the $PATH for
  # neovim. These will *only* be added to neovim's path, not to the system or
  # user profiles.
  extraBinPackages = with pkgs; [
    silver-searcher
    xdg_utils # xdg-open
  ];
  # See chapter 3
  mergePlugins = true;
  # `files` can be used to build a symlink tree of files and folders, which
  # would typically consist of any extra/local contents of .config/nvim/ in a
  # non-Nix neovim setup.
  files = {
    neosnippets.source = "/my/snippet/files/";
  };
}

Enabling Plugins

You can enable both pre-existing Nix vim plugin derivations (e.g. from nixpkgs), and vim plugins on github, both by using pluginRegistry.<pluginName>.enable.

There are several ways to specify the source for a plugin, depending on what you want:

{ config, lib, pkgs, ... }:
{
  pluginRegistry = {
    # In this case, the name 'ale' is automatically 'resolved' against
    # pkgs.vimPlugins to select the plugin source
    ale.enable = true;
    # In this case, `source` is explicitly pointed to an existing Vim plugin
    # derivation.
    "denite.nvim" = {
      enable = true;
      source = pkgs.vimPlugins.denite-nvim;
    };
    # In this case, the name fails to resolve against pkgs.vimPlugins, so
    # `source` is automatically inferred from the `name`, on the assumption
    # that it is a vim-plug-compatible 'shortname', which will be used to
    # dynamically construct a derivation from a Vim plugin sourced from
    # https://github.com/Shados/vim-session (see chapter 3).
    "Shados/vim-session".enable = true;
    vim-buffet = {
      enable = true;
      # In this case, we again are using a shortname for the source, but we set
      # it explicitly.
      source = "bagrat/vim-buffet";
      # Additionally, we specify the exact commit we want to pin and use for the git source.
      # Generally you are better off relying on the separate JSON pin files to
      # pin to a specific commit, but in this case the version after this
      # commit has breaking changes, which would mean the configuration of the
      # plugin would also have to change, meaning that the commit information
      # is more an element of configuration than of state. 'branch' and 'tag'
      # are also supported for specifying what to fetch.
      commit = "044f2954a5e49aea8625973de68dda8750f1c42d";
    };
    localPlugin = {
      enable = true;
      # In this case, Envy will dynamically construct a derivation using the
      # given Nix store path as the source.
      source = /some/local/path/or/store/path;
    };
    inDevPlugin = {
      enable = true;
      # Here we instead instruct Envy to have Vim load the plugin from a local
      # filesystem path at run-time, rather than bundling it into the Nix
      # store. This is useful for doing plugin development, or if you otherwise
      # want to use a plugin outside of the Nix store, while still allowing you
      # to leverage Envy's configuration and dependency
      # specification/resolution mechanisms.
      dir = "/a/local/path/string";
    };
  };
}

Specifying Dependencies

Envy allows for specifying a wide variety of dependency types:

{ config, lib, pkgs, ... }:
{
  pluginRegistry = {
    # Inter-plugin dependencies; the items should preferably be the names of
    # `pluginRegistry` or `vim.vimPlugins` items, but can alternatively be Vim
    # plugin derivations.
    neosnippet-snippets.dependencies = [ "neosnippet-vim" ];
    # Specifies that a plugin needs external executables from the given
    # packages made available in neovim's $PATH.
    ale.binDeps = with pkgs; [
      bash
      shellcheck
      shfmt
    ];
    # Ensures that the specified Lua modules will be made available in
    # neovim's LUA_PATH/LUA_CPATH, meaning that the main neovim process can
    # load them for in-process Lua plugins and scripts to use.
    "Shados/precog.nvim".luaDeps = ps: with ps; [
      luafilesystem
    ];
    # Flags a plugin as being a 'remote' plugin requiring a plugin host for a
    # specific language (here, Python 3).
    denite-nvim.remote.python3 = true;
    # Pulls in plugin-host-language dependencies.
    # Automatically implies `remote.python2 = true;`.
    aPythonPlugin.remote.python2Deps = ps: with ps; [
      requests
    ];
  };
}

Inter-plugin dependencies also determine the order in which Vim plugins are loaded at Vim run-time (by vim-plug).

There are additionally two "soft" dependency options (before and after, both of which take lists of plugin names only), that change how plugins are ordered if both are enabled, but does not cause the "dependency" to be enabled if the "dependent" plugin is, e.g.:

{ config, lib, pkgs, ... }:
{
  pluginRegistry = {
    # vim-devicons needs to be loaded after these plugins, if they
    # are being used, as per its installation guide
    vim-devicons.after = [
      "nerdtree" "vim-airline" "ctrlp-vim" "powerline/powerline" "denite-nvim"
      "unite-vim" "lightline-vim" "vim-startify" "vimfiler" "vim-flagship"
    ];
  };
}

It should be noted that lazy-loaded plugins don't fully respect ordering options, and don't trigger lazy-loading of dependencies. Either ensure dependencies aren't also being lazy-loaded, or put them behind the same lazy-load triggers as their dependents.

Plugin Configuration

There is a per-plugin version of the extraConfig option, under pluginRegistry.<pluginName>.extraConfig. These are inserted into the generated nvimrc after the prePluginConfig, before the top-level extraConfig, and in the same order plugins are loaded (that is, based on dependencies and explicit ordering information).

3. Packaging Plugins

If you are using any plugins whose source is specified by 'shortname', then you will need to prefetch those sources, pin the versions, and provide the pinned source information to the Envy module in order for it to construct Vim plugin derivations from the sources.

Pinning Sources

The envy-pins tool is provided to do this. It has a myriad of modes of usage depending on how you are set up, but the easiest way to do things is:

# If you are using the NixOS module, use -n to have envy-pins source the list
# of 'shortname' # plugins to pin directly from the module
envy-pins -n ./pin/storage/directory/ update-all
# -m for the home-manager module
envy-pins -m ./pin/storage/directory/ update-all
# -s for the home-manager NixOS sub-module
envy-pins -s ./pin/storage/directory/ update-all

envy-pins will be installed if you enable either the NixOS or home-maanger Envy modules. Alternatively, you could access just it with a Nix expression like:

{ pkgs }:
let
  envy = (builtins.fetchgit { url = https://github.com/Shados/envy; ref = "master"; });
in pkgs.callPackage "${envy}/envy-pins-package.nix" { }

In order to limit the installation closure size on systems where it may not directly be used (but is still pulled in by an Envy module), envy-pins makes use of a nix-shell's shebang functionality, meaning that it uses Nix to download its dependencies at run-time, rather than at install-time. This also means that it can be run directly from a checkout of Envy.

Specifying Pins To Use

The top-level sourcePins option maps pluginRegistry attribute names to source information. While the individual source pins can be manually set if desired, it is easier to make use of the JSON pin files produced by envy-pins and the built-in helpers to read them:

{ config, lib, pkgs, ... }:
{
  sourcePins = config.sn.programs.neovim.lib.fillPinsFromDir /directory/of/envy-pins/output/;
}

or:

{ config, lib, pkgs, ... }:
let
  envy = (builtins.fetchgit { url = https://github.com/Shados/envy; ref = "master"; });
  envyLib = import "${envy}/lib.nix" { nixpkgs = pkgs; };
in
{
  sourcePins = lib.fillPinsFromDir /directory/of/envy-pins/output/;
}

4. Advanced Usage

This chapter provides some notes on more complicated usages of Envy.

Plugin Merging

The mergePlugins option can be used to merge plugin directories into symlink trees. This is useful because it reduces the number of directories that have to be added to neovim's runtimepath, and as a result it can significantly improve neovim startup times.

There are some restrictions:

• It may break some plugins outright.
• It will only merge plugins that are within the same 'bucket' in the plugin load order (so that dependent plugins are still loaded after their dependencies).
• It will likely cause issues in cases of colliding file names.

As such, it is not enabled by default. If you do enable it, you can disable merging on a per-plugin basis using the pluginRegistry.<pluginName>.mergeable option.

Layering Configuration

TODO

A. Configuration Options

' . $HOME. '/.config/vim/local/some-plugin

B. Tools

TODO: Automatically generate a man-page-like segment for here, from envy-pins, using the argparse parser object?