mirror of
https://github.com/NotAShelf/nvf.git
synced 2024-11-22 13:20:44 +00:00
839 lines
76 KiB
HTML
839 lines
76 KiB
HTML
<?xml version="1.0" encoding="utf-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
||
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
<title>nvf manual</title>
|
||
<link rel="stylesheet" type="text/css" href="style.css" />
|
||
<script src="highlightjs/highlight.pack.js" type="text/javascript"></script><script src="highlightjs/loader.js" type="text/javascript"></script>
|
||
<meta name="generator" content="nixos-render-docs" />
|
||
<link rel="home" href="index.xhtml" title="nvf manual" />
|
||
<link rel="next" href="plugins.html" title="Appendix A. Plugin specific quirks" />
|
||
</head>
|
||
<body>
|
||
<div class="navheader">
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">nvf manual</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"> </td>
|
||
<th width="60%" align="center"> </th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="plugins.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="book">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div><h1 class="title"><a id="nvf-manual"></a>nvf manual</h1></div>
|
||
<div><h2 class="subtitle">Version v0.6</h2></div>
|
||
</div>
|
||
<hr />
|
||
</div>
|
||
<div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="preface"> <a href="index.xhtml#ch-preface">Preface</a> </span></dt><dt> <span class="preface"> <a href="index.xhtml#ch-try-it-out">Try it out</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-using-prebuild-configs">Using Prebuilt Configs</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-default-configs">Default Configs</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#sec-default-maximal">Maximal</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-default-nix">Nix</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-installation">Installing nvf</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#ch-standalone-installation">Standalone Installation</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#ch-standalone-nixos">Standalone Installation on NixOS</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-standalone-hm">Standalone Installation on Home-Manager</a> </span></dt></dl></dd><dt> <span class="chapter"> <a href="index.xhtml#ch-module-installation">Module Installation</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#ch-nixos-module">NixOS Module</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-hm-module">Home-Manager Module</a> </span></dt></dl></dd></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-configuring">Configuring nvf</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#ch-custom-package">Custom Neovim Package</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-custom-plugins">Custom Plugins</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#ch-adding-plugins">Adding Plugins</a> </span></dt></dl></dd><dt> <span class="chapter"> <a href="index.xhtml#ch-languages">Language Support</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-languages-custom-lsp-packages">LSP Custom Packages/Command</a> </span></dt></dl></dd><dt> <span class="chapter"> <a href="index.xhtml#ch-using-dags">Using DAGs</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entryAnywhere">entryAnywhere</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#ch-types-dag-entryAfter">entryAfter</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#ch-types-dag-entryBefore">entryBefore</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entryBetween">entryBetween</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entriesAnywhere">entriesAnywhere</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entriesAfter">entriesAfter</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entriesBefore">entriesBefore</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entriesBetween">entriesBetween</a> </span></dt></dl></dd></dl></dd><dt> <span class="chapter"> <a href="index.xhtml#ch-hacking">Hacking nvf</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-contrib-getting-started">Getting Started</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines">Guidelines</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-testing-changes">Testing Changes</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-keybinds">Keybinds</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-additional-plugins">Adding Plugins</a> </span></dt></dl></dd><dt> <span class="appendix"> <a href="plugins.html">A. Plugin specific quirks</a> </span></dt><dt> <span class="appendix"> <a href="options.html">B. Neovim Flake Configuration Options</a> </span></dt><dt> <span class="appendix"> <a href="release-notes.html">C. Release Notes</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="release-notes.html#sec-release-0.1">Release 0.1</a> </span></dt><dt> <span class="chapter"> <a href="release-notes.html#sec-release-0.2">Release 0.2</a> </span></dt><dt> <span class="chapter"> <a href="release-notes.html#sec-release-0.3">Release 0.3</a> </span></dt><dt> <span class="chapter"> <a href="release-notes.html#sec-release-0.4">Release 0.4</a> </span></dt><dt> <span class="chapter"> <a href="release-notes.html#sec-release-0.5">Release 0.5</a> </span></dt><dt> <span class="chapter"> <a href="release-notes.html#sec-release-0.6">Release 0.6</a> </span></dt><dt> <span class="chapter"> <a href="release-notes.html#sec-release-0.7">Release 0.7</a> </span></dt></dl></dd> </dl></div>
|
||
<div class="preface"> <div class="titlepage"> <div> <div> <h1 id="ch-preface" class="title" >Preface </h1> </div> </div></div><p>If you noticed a bug caused by <span class="strong"><strong>nvf</strong></span> then please consider reporting it over
|
||
<a class="link" href="https://github.com/notashelf/nvf/issues" target="_top">the issue tracker</a>.</p><p>Bugfixes, feature additions and upstreamed changes from your local configurations
|
||
are always welcome in the <a class="link" href="https://github.com/notashelf/nvf/pulls" target="_top">the pull requests tab</a>.</p>
|
||
</div><div class="preface"> <div class="titlepage"> <div> <div> <h1 id="ch-try-it-out" class="title" >Try it out </h1> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-using-prebuild-configs">Using Prebuilt Configs</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-available-configs">Available Configs</a> </span></dt></dl></dd> </dl></div><p>Thanks to the portability of Nix, you can try out nvf without actually installing it to your machine.
|
||
Below are the commands you may run to try out different configurations provided by this flake. As of v0.5, three
|
||
configurations are provided:</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p>Nix</p></li><li class="listitem"><p>Maximal</p></li></ul></div><p>You may try out any of the provided configurations using the <code class="literal">nix run</code> command on a system where Nix is installed.</p><pre><code class="programlisting console">$ cachix use nvf # Optional: it'll save you CPU resources and time
|
||
$ nix run github:notashelf/nvf#nix # will run the default minimal configuration
|
||
</code></pre><p>Do keep in mind that this is <span class="strong"><strong>susceptible to garbage collection</strong></span> meaning it will be removed from your Nix store
|
||
once you garbage collect.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-using-prebuild-configs" class="title" >Using Prebuilt Configs </h2> </div> </div></div><div class="toc"> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-available-configs">Available Configs</a> </span></dt> </dl></div><pre><code class="programlisting console">$ nix run github:notashelf/nvf#nix
|
||
$ nix run github:notashelf/nvf#maximal
|
||
</code></pre><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-available-configs" class="title" >Available Configs </h3> </div> </div></div><div class="section"> <div class="titlepage"> <div> <div> <h4 id="sec-configs-nix" class="title" >Nix </h4> </div> </div></div><p><code class="literal">Nix</code> configuration by default provides LSP/diagnostic support for Nix alongisde a set of visual and functional plugins.
|
||
By running <code class="literal">nix run .#</code>, which is the default package, you will build Neovim with this config.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h4 id="sec-configs-maximal" class="title" >Maximal </h4> </div> </div></div><p><code class="literal">Maximal</code> is the ultimate configuration that will enable support for more commonly used language as well as additional
|
||
complementary plugins. Keep in mind, however, that this will pull a lot of dependencies.</p><p>You are <span class="emphasis"><em>strongly</em></span> recommended to use the binary cache if you would like to try the Maximal configuration.</p>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 id="ch-default-configs" class="title" >Default Configs </h1> </div> </div></div><div class="partintro"><p>While you can configure <span class="strong"><strong>nvf</strong></span> yourself using the builder, you can also use the pre-built configs that are available.
|
||
Here are a few default configurations you can use.</p><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="chapter"> <a href="index.xhtml#sec-default-maximal">Maximal</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-default-nix">Nix</a> </span></dt> </dl></div></div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="sec-default-maximal" class="title" >Maximal </h2> </div> </div></div><pre><code class="programlisting bash">$ nix shell github:notashelf/nvf#maximal test.nix
|
||
</code></pre><p>It is the same fully configured Neovim as with the <a class="link" href="index.xhtml#sec-default-nix" title="Nix" >Nix</a>
|
||
configuration, but with every supported language enabled.</p><div class="note"><h3 class="title">Note</h3><p>Running the maximal config will download <span class="emphasis"><em>a lot</em></span> of packages as it is
|
||
downloading language servers, formatters, and more.</p></div>
|
||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="sec-default-nix" class="title" >Nix </h2> </div> </div></div><pre><code class="programlisting bash">$ nix run github:notashelf/nvf#nix test.nix
|
||
</code></pre><p>Enables all the of Neovim plugins, with language support for specifically Nix.
|
||
This lets you see what a fully configured neovim setup looks like without
|
||
downloading a whole bunch of language servers and associated tools.</p>
|
||
</div>
|
||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 id="ch-installation" class="title" >Installing nvf </h1> </div> </div></div><div class="partintro"><p>There are multiple ways of installing nvf on your system. You may either choose
|
||
the standalone installation method, which does not depend on a module system and may
|
||
be done on any system that has the Nix package manager or the appropriate modules
|
||
for NixOS and home-manager as described in the <a class="link" href="index.xhtml#ch-module-installation" title="Module Installation" >module installation section</a></p><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="chapter"> <a href="index.xhtml#ch-standalone-installation">Standalone Installation</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#ch-standalone-nixos">Standalone Installation on NixOS</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-standalone-hm">Standalone Installation on Home-Manager</a> </span></dt></dl></dd><dt> <span class="chapter"> <a href="index.xhtml#ch-module-installation">Module Installation</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#ch-nixos-module">NixOS Module</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-hm-module">Home-Manager Module</a> </span></dt></dl></dd> </dl></div></div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-standalone-installation" class="title" >Standalone Installation </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="chapter"> <a href="index.xhtml#ch-standalone-nixos">Standalone Installation on NixOS</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-standalone-hm">Standalone Installation on Home-Manager</a> </span></dt> </dl></div><p>It is possible to install <span class="strong"><strong>nvf</strong></span> without depending on NixOS or home-manager as the parent
|
||
module system, using the <code class="literal">neovimConfiguration</code> function exposed by <span class="strong"><strong>nvf</strong></span> extended library.
|
||
It takes in the configuration as a module, and returns an attribute set as a result.</p><pre><code class="programlisting nix">{
|
||
options = "The options that were available to configure";
|
||
config = "The outputted configuration";
|
||
pkgs = "The package set used to evaluate the module";
|
||
neovim = "The built neovim package";
|
||
}
|
||
</code></pre><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-standalone-nixos" class="title" >Standalone Installation on NixOS </h2> </div> </div></div><p>Your built Neoevim configuration can be exposed as a flake output to make it
|
||
easier to share across machines, repositories and so on. Or it can be added to
|
||
your system packages to make it available across your system.</p><p>The following is an example installation of <code class="literal">nvf</code> as a standalone package with
|
||
the default theme enabled. You may use other options inside <code class="literal">config.vim</code> in
|
||
<code class="literal">configModule</code>, but this example will not cover that.</p><pre><code class="programlisting nix">{
|
||
inputs = {
|
||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||
home-manager.url = "github:nix-community/home-manager";
|
||
nvf.url = "github:notashelf/nvf";
|
||
};
|
||
|
||
outputs = {nixpkgs, nvf, ...}: let
|
||
system = "x86_64-linux";
|
||
pkgs = nixpkgs.legacyPackages.${system};
|
||
configModule = {
|
||
# Add any custom options (and do feel free to upstream them!)
|
||
# options = { ... };
|
||
|
||
config.vim = {
|
||
theme.enable = true;
|
||
# and more options as you see fit...
|
||
};
|
||
};
|
||
|
||
customNeovim = nvf.lib.neovimConfiguration {
|
||
modules = [configModule];
|
||
inherit pkgs;
|
||
};
|
||
in {
|
||
# this will make the package available as a flake input
|
||
packages.${system}.my-neovim = customNeovim.neovim;
|
||
|
||
# this is an example nixosConfiguration using the built neovim package
|
||
nixosConfigurations = {
|
||
yourHostName = nixpkgs.lib.nixosSystem {
|
||
# ...
|
||
modules = [
|
||
./configuration.nix # or whatever your configuration is
|
||
|
||
# this will make wrapped neovim available in your system packages
|
||
{environment.systemPackages = [customNeovim.neovim];}
|
||
];
|
||
# ...
|
||
};
|
||
};
|
||
};
|
||
}
|
||
</code></pre>
|
||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-standalone-hm" class="title" >Standalone Installation on Home-Manager </h2> </div> </div></div><p>Your built Neoevim configuration can be exposed as a flake output to make it
|
||
easier to share across machines, repositories and so on. Or it can be added to
|
||
your system packages to make it available across your system.</p><p>The following is an example installation of <code class="literal">nvf</code> as a standalone package with
|
||
the default theme enabled. You may use other options inside <code class="literal">config.vim</code> in
|
||
<code class="literal">configModule</code>, but this example will not cover that.</p><pre><code class="programlisting nix">{
|
||
inputs = {
|
||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||
home-manager.url = "github:nix-community/home-manager";
|
||
nvf.url = "github:notashelf/nvf";
|
||
};
|
||
|
||
outputs = {nixpkgs, home-manager, nvf, ...}: let
|
||
system = "x86_64-linux";
|
||
pkgs = nixpkgs.legacyPackages.${system};
|
||
configModule = {
|
||
# Add any custom options (and do feel free to upstream them!)
|
||
# options = { ... };
|
||
|
||
config.vim = {
|
||
theme.enable = true;
|
||
# and more options as you see fit...
|
||
};
|
||
};
|
||
|
||
customNeovim = nvf.lib.neovimConfiguration {
|
||
modules = [configModule];
|
||
inherit pkgs;
|
||
};
|
||
in {
|
||
# this will make the package available as a flake input
|
||
packages.${system}.my-neovim = customNeovim.neovim;
|
||
|
||
# this is an example home-manager configuration
|
||
# using the built neovim package
|
||
homeConfigurations = {
|
||
"your-username@your-hostname" = home-manager.lib.homeManagerConfiguration {
|
||
# ...
|
||
modules = [
|
||
./home.nix
|
||
|
||
# this will make wrapped neovim available in your system packages
|
||
{environment.systemPackages = [customNeovim.neovim];}
|
||
];
|
||
# ...
|
||
};
|
||
};
|
||
};
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-module-installation" class="title" >Module Installation </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="chapter"> <a href="index.xhtml#ch-nixos-module">NixOS Module</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-example-installation-nixos">Example Installation</a> </span></dt></dl></dd><dt> <span class="chapter"> <a href="index.xhtml#ch-hm-module">Home-Manager Module</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-example-installation-hm">Example Installation</a> </span></dt></dl></dd> </dl></div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-nixos-module" class="title" >NixOS Module </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-example-installation-nixos">Example Installation</a> </span></dt> </dl></div><p>The NixOS module allows us to customize the different <code class="literal">vim</code> options from inside
|
||
the NixOS configuration without having to call for the wrapper yourself. It is
|
||
the recommended way to use <span class="strong"><strong>nvf</strong></span> alongside the home-manager module depending
|
||
on your needs.</p><p>To use it, we first add the input flake.</p><pre><code class="programlisting nix">{
|
||
inputs = {
|
||
obsidian-nvim.url = "github:epwalsh/obsidian.nvim";
|
||
nvf = {
|
||
url = "github:notashelf/nvf";
|
||
# you can override input nixpkgs
|
||
inputs.nixpkgs.follows = "nixpkgs";
|
||
# you can also override individual plugins
|
||
# for example:
|
||
inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- this will use the obsidian-nvim from your inputs
|
||
};
|
||
};
|
||
}
|
||
</code></pre><p>Followed by importing the NixOS module somewhere in your configuration.</p><pre><code class="programlisting nix">{
|
||
# assuming nvf is in your inputs and inputs is in the argset
|
||
# see example below
|
||
imports = [ inputs.nvf.nixosModules.default ];
|
||
}
|
||
</code></pre><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-example-installation-nixos" class="title" style="clear: both">Example Installation </h2> </div> </div></div><pre><code class="programlisting nix">{
|
||
inputs = {
|
||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||
nvf.url = "github:notashelf/nvf";
|
||
};
|
||
|
||
outputs = { nixpkgs, nvf, ... }: let
|
||
system = "x86_64-linux"; in {
|
||
# ↓ this is your host output in the flake schema
|
||
nixosConfigurations."yourUsername»" = nixpkgs.lib.nixosSystem {
|
||
modules = [
|
||
nvf.nixosModules.default # <- this imports the NixOS module that provides the options
|
||
./configuration.nix # <- your host entrypoint
|
||
];
|
||
};
|
||
};
|
||
}
|
||
</code></pre><p>Once the module is properly imported by your host, you will be able to use the
|
||
<code class="literal">programs.nvf</code> module option anywhere in your configuration in order to
|
||
configure <span class="strong"><strong>nvf</strong></span>.</p><pre><code class="programlisting nix{"> programs.nvf = {
|
||
enable = true;
|
||
# your settings need to go into the settings attribute set
|
||
# most settings are documented in the appendix
|
||
settings = {
|
||
vim.viAlias = false;
|
||
vim.vimAlias = true;
|
||
vim.lsp = {
|
||
enable = true;
|
||
};
|
||
};
|
||
};
|
||
}
|
||
</code></pre><div class="note"><h3 class="title">Note</h3><p><span class="strong"><strong>nvf</strong></span> exposes a lot of options, most of which are not referenced in the
|
||
installation sections of the manual. You may find all avaliable options
|
||
in the <a class="link" href="https://notashelf.github.io/nvf/options" target="_top">appendix</a></p></div>
|
||
</div>
|
||
|
||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-hm-module" class="title" >Home-Manager Module </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-example-installation-hm">Example Installation</a> </span></dt> </dl></div><p>The home-manager module allows us to customize the different <code class="literal">vim</code> options from
|
||
inside the home-manager configuration without having to call for the wrapper
|
||
yourself. It is the recommended way to use <span class="strong"><strong>nvf</strong></span> alongside the NixOS module
|
||
depending on your needs.</p><p>To use it, we first add the input flake.</p><pre><code class="programlisting nix">{
|
||
inputs = {
|
||
obsidian-nvim.url = "github:epwalsh/obsidian.nvim";
|
||
nvf = {
|
||
url = "github:notashelf/nvf";
|
||
# you can override input nixpkgs
|
||
inputs.nixpkgs.follows = "nixpkgs";
|
||
# you can also override individual plugins
|
||
# for example:
|
||
inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- this will use the obsidian-nvim from your inputs
|
||
};
|
||
};
|
||
}
|
||
</code></pre><p>Followed by importing the home-manager module somewhere in your configuration.</p><pre><code class="programlisting nix">{
|
||
# assuming nvf is in your inputs and inputs is in the argset
|
||
# see example below
|
||
imports = [ inputs.nvf.homeManagerModules.default ];
|
||
}
|
||
</code></pre><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-example-installation-hm" class="title" style="clear: both">Example Installation </h2> </div> </div></div><pre><code class="programlisting nix">{
|
||
inputs = {
|
||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||
home-manager.url = "github:nix-community/home-manager";
|
||
nvf.url = "github:notashelf/nvf";
|
||
};
|
||
|
||
outputs = { nixpkgs, home-manager, nvf, ... }: let
|
||
system = "x86_64-linux"; in {
|
||
# ↓ this is your home output in the flake schema, expected by home-manager
|
||
"your-username@your-hostname" = home-manager.lib.homeManagerConfiguration
|
||
modules = [
|
||
nvf.homeManagerModules.default # <- this imports the home-manager module that provides the options
|
||
./home.nix # <- your home entrypoint
|
||
];
|
||
};
|
||
};
|
||
}
|
||
</code></pre><p>Once the module is properly imported by your host, you will be able to use the
|
||
<code class="literal">programs.nvf</code> module option anywhere in your configuration in order to
|
||
configure <span class="strong"><strong>nvf</strong></span>.</p><pre><code class="programlisting nix{"> programs.nvf = {
|
||
enable = true;
|
||
# your settings need to go into the settings attribute set
|
||
# most settings are documented in the appendix
|
||
settings = {
|
||
vim.viAlias = false;
|
||
vim.vimAlias = true;
|
||
vim.lsp = {
|
||
enable = true;
|
||
};
|
||
};
|
||
};
|
||
}
|
||
</code></pre><div class="note"><h3 class="title">Note</h3><p><span class="strong"><strong>nvf</strong></span> exposes a lot of options, most of which are not referenced in the
|
||
installation sections of the manual. You may find all avaliable options
|
||
in the <a class="link" href="https://notashelf.github.io/nvf/options" target="_top">appendix</a></p></div>
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 id="ch-configuring" class="title" >Configuring nvf </h1> </div> </div></div><div class="partintro"><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="chapter"> <a href="index.xhtml#ch-custom-package">Custom Neovim Package</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-custom-plugins">Custom Plugins</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#ch-adding-plugins">Adding Plugins</a> </span></dt></dl></dd><dt> <span class="chapter"> <a href="index.xhtml#ch-languages">Language Support</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-languages-custom-lsp-packages">LSP Custom Packages/Command</a> </span></dt></dl></dd><dt> <span class="chapter"> <a href="index.xhtml#ch-using-dags">Using DAGs</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entryAnywhere">entryAnywhere</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#ch-types-dag-entryAfter">entryAfter</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#ch-types-dag-entryBefore">entryBefore</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entryBetween">entryBetween</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entriesAnywhere">entriesAnywhere</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entriesAfter">entriesAfter</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entriesBefore">entriesBefore</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entriesBetween">entriesBetween</a> </span></dt></dl></dd> </dl></div></div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-custom-package" class="title" >Custom Neovim Package </h2> </div> </div></div><p>As of v0.5, you may now specify the Neovim package that will be wrapped with
|
||
your configuration. This is done with the <code class="literal">vim.package</code> option.</p><pre><code class="programlisting nix">{inputs, pkgs, ...}: {
|
||
# using the neovim-nightly overlay
|
||
vim.package = inputs.neovim-overlay.packages.${pkgs.system}.neovim;
|
||
}
|
||
</code></pre><p>The neovim-nightly-overlay always exposes an unwrapped package. If using a
|
||
different source, you are highly recommended to get an “unwrapped” version of
|
||
the neovim package, similar to <code class="literal">neovim-unwrapped</code> in nixpkgs.</p><pre><code class="programlisting nix">{ pkgs, ...}: {
|
||
# using the neovim-nightly overlay
|
||
vim.package = pkgs.neovim-unwrapped;
|
||
}
|
||
</code></pre>
|
||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-custom-plugins" class="title" >Custom Plugins </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#ch-adding-plugins">Adding Plugins</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-configuring-plugins">Configuring</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-new-method">New Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-old-method">Old Method</a> </span></dt></dl></dd> </dl></div><p><span class="strong"><strong>nvf</strong></span>, by default, exposes a wide variety of plugins as module options
|
||
for your convience and bundles necessary dependencies into <span class="strong"><strong>nvf</strong></span>’s runtime.
|
||
In case a plugin is not available in <span class="strong"><strong>nvf</strong></span>, you may consider making a pull
|
||
request to <span class="strong"><strong>nvf</strong></span> to include it as a module or you may add it to your
|
||
configuration locally.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="ch-adding-plugins" class="title" style="clear: both">Adding Plugins </h2> </div> </div></div><div class="toc"> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-configuring-plugins">Configuring</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-new-method">New Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-old-method">Old Method</a> </span></dt> </dl></div><p>There are multiple ways of adding custom plugins to your <span class="strong"><strong>nvf</strong></span> configuration.</p><p>You can use custom plugins, before they are implemented in the flake. To add a
|
||
plugin to the runtime, you need to add it to the <code class="literal">vim.startPlugins</code> list in
|
||
your configuration.</p><p>Adding a plugin to <code class="literal">startPlugins</code> will not allow you to configure the plugin
|
||
that you have adeed, but <span class="strong"><strong>nvf</strong></span> provides multiple way of configuring any
|
||
custom plugins that you might have added to your configuration.</p><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-configuring-plugins" class="title" >Configuring </h3> </div> </div></div><p>Just making the plugin to your Neovim configuration available might not always
|
||
be enough. In that case, you can write custom vimscript or lua config, using
|
||
either <code class="literal">config.vim.configRC</code> or <code class="literal">config.vim.luaConfigRC</code> respectively. Both of
|
||
these options are attribute sets, and you need to give the configuration you’re
|
||
adding some name, like this:</p><pre><code class="programlisting nix">{
|
||
# this will create an "aquarium" section in your init.vim with the contents of your custom config
|
||
# which will be *appended* to the rest of your configuration, inside your init.vim
|
||
config.vim.configRC.aquarium = "colorscheme aquiarum";
|
||
}
|
||
</code></pre><div class="note"><h3 class="title">Note</h3><p>If your configuration needs to be put in a specific place in the config, you
|
||
can use functions from <code class="literal">inputs.nvf.lib.nvim.dag</code> to order it. Refer to
|
||
https://github.com/nix-community/home-manager/blob/master/modules/lib/dag.nix
|
||
to find out more about the DAG system.</p></div><p>If you successfully made your plugin work, please feel free to create a PR to
|
||
add it to <span class="strong"><strong>nvf</strong></span> or open an issue with your findings so that we can make it
|
||
available for everyone easily.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-new-method" class="title" >New Method </h3> </div> </div></div><p>As of version <span class="strong"><strong>0.5</strong></span>, we have a more extensive API for configuring plugins,
|
||
under <code class="literal">vim.extraPlugins</code>. Instead of using DAGs exposed by the library, you may
|
||
use the extra plugin module as follows:</p><pre><code class="programlisting nix">{
|
||
config.vim.extraPlugins = with pkgs.vimPlugins; {
|
||
aerial = {
|
||
package = aerial-nvim;
|
||
setup = ''
|
||
require('aerial').setup {
|
||
-- some lua configuration here
|
||
}
|
||
'';
|
||
};
|
||
|
||
harpoon = {
|
||
package = harpoon;
|
||
setup = "require('harpoon').setup {}";
|
||
after = ["aerial"];
|
||
};
|
||
};
|
||
}
|
||
</code></pre>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-old-method" class="title" >Old Method </h3> </div> </div></div><p>Prior to version 0.5, the method of adding new plugins was adding the plugin
|
||
package to <code class="literal">vim.startPlugins</code> and add its configuration as a DAG under one of
|
||
<code class="literal">vim.configRC</code> or <code class="literal">vim.luaConfigRC</code>. Users who have not yet updated to 0.5, or
|
||
prefer a more hands-on approach may use the old method where the load order of
|
||
the plugins is determined by DAGs.</p><div class="section"> <div class="titlepage"> <div> <div> <h4 id="sec-adding-plugins" class="title" >Adding plugins </h4> </div> </div></div><p>To add a plugin to <span class="strong"><strong>nvf</strong></span>’s runtime, you may add it</p><pre><code class="programlisting nix">{pkgs, ...}: {
|
||
# add a package from nixpkgs to startPlugins
|
||
vim.startPlugins = [
|
||
pkgs.vimPlugins.aerial-nvim ];
|
||
}
|
||
</code></pre><p>And to configure the added plugin, you can use the <code class="literal">luaConfigRC</code> option to
|
||
provide configuration as a DAG using the <span class="strong"><strong>nvf</strong></span> extended library.</p><pre><code class="programlisting nix">{inputs, ...}: let
|
||
# assuming you have an input called nvf pointing at the nvf repository
|
||
inherit (inputs.nvf.lib.nvim.dag) entryAnywhere;
|
||
in {
|
||
vim.luaConfigRC.aerial-nvim= entryAnywhere ''
|
||
require('aerial').setup {
|
||
-- your configuration here
|
||
}
|
||
'';
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-languages" class="title" >Language Support </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-languages-custom-lsp-packages">LSP Custom Packages/Command</a> </span></dt> </dl></div><p>Language specific support means there is a combination of language specific
|
||
plugins, <code class="literal">treesitter</code> support, <code class="literal">nvim-lspconfig</code> language servers, and <code class="literal">null-ls</code>
|
||
integration. This gets you capabilities ranging from autocompletion to formatting
|
||
to diagnostics. The following languages have sections under the <code class="literal">vim.languages</code>
|
||
attribute.</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p>Rust: <a class="link" href="options.html#opt-vim.languages.rust.enable" >vim.languages.rust.enable</a></p></li><li class="listitem"><p>Nix: <a class="link" href="options.html#opt-vim.languages.nix.enable" >vim.languages.nix.enable</a></p></li><li class="listitem"><p>SQL: <a class="link" href="options.html#opt-vim.languages.sql.enable" >vim.languages.sql.enable</a></p></li><li class="listitem"><p>C/C++: <a class="link" href="options.html#opt-vim.languages.clang.enable" >vim.languages.clang.enable</a></p></li><li class="listitem"><p>Typescript/Javascript: <a class="link" href="options.html#opt-vim.languages.ts.enable" >vim.languages.ts.enable</a></p></li><li class="listitem"><p>Python: <a class="link" href="options.html#opt-vim.languages.python.enable" >vim.languages.python.enable</a>:</p></li><li class="listitem"><p>Zig: <a class="link" href="options.html#opt-vim.languages.zig.enable" >vim.languages.zig.enable</a></p></li><li class="listitem"><p>Markdown: <a class="link" href="options.html#opt-vim.languages.markdown.enable" >vim.languages.markdown.enable</a></p></li><li class="listitem"><p>HTML: <a class="link" href="options.html#opt-vim.languages.html.enable" >vim.languages.html.enable</a></p></li><li class="listitem"><p>Dart: <a class="link" href="options.html#opt-vim.languages.dart.enable" >vim.languages.dart.enable</a></p></li><li class="listitem"><p>Go: <a class="link" href="options.html#opt-vim.languages.go.enable" >vim.languages.go.enable</a></p></li><li class="listitem"><p>Lua: <a class="link" href="options.html#opt-vim.languages.lua.enable" >vim.languages.lua.enable</a></p></li><li class="listitem"><p>PHP: <a class="link" href="options.html#opt-vim.languages.php.enable" >vim.languages.php.enable</a></p></li></ul></div><p>Adding support for more languages, and improving support for existing ones are great places
|
||
where you can contribute with a PR.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-languages-custom-lsp-packages" class="title" style="clear: both">LSP Custom Packages/Command </h2> </div> </div></div><p>In any of the <code class="literal">opt.languages.<language>.lsp.package</code> options you can provide
|
||
your own LSP package, or provide the command to launch the language server, as
|
||
a list of strings. You can use this to skip automatic installation of a language
|
||
server, and instead use the one found in your <code class="literal">$PATH</code> during runtime, for
|
||
example:</p><pre><code class="programlisting nix">vim.languages.java = {
|
||
lsp = {
|
||
enable = true;
|
||
# this expects jdt-language-server to be in your PATH
|
||
# or in `vim.extraPackages`
|
||
package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
|
||
};
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-using-dags" class="title" >Using DAGs </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entryAnywhere">entryAnywhere</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#ch-types-dag-entryAfter">entryAfter</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#ch-types-dag-entryBefore">entryBefore</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entryBetween">entryBetween</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entriesAnywhere">entriesAnywhere</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entriesAfter">entriesAfter</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entriesBefore">entriesBefore</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-types-dag-entriesBetween">entriesBetween</a> </span></dt> </dl></div><p>We conform to the NixOS options types for the most part, however, a noteworthy
|
||
addition for certain options is the <a class="link" href="https://en.wikipedia.org/wiki/Directed_acyclic_graph" target="_top"><span class="strong"><strong>DAG
|
||
(Directed acyclic graph)</strong></span></a>
|
||
type which is borrowed from home-manager’s extended library. This type is most
|
||
used for topologically sorting strings. The DAG type allows the attribute set
|
||
entries to express dependency relations among themselves. This can, for
|
||
example, be used to control the order of configuration sections in your
|
||
<code class="literal">configRC</code> or <code class="literal">luaConfigRC</code>.</p><p>The below section, mostly taken from the <a class="link" href="https://raw.githubusercontent.com/nix-community/home-manager/master/docs/manual/writing-modules/types.md" target="_top">home-manager
|
||
manual</a>
|
||
explains in more detail the overall usage logic of the DAG type.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-types-dag-entryAnywhere" class="title" style="clear: both">entryAnywhere </h2> </div> </div></div><div class="blockquote"><blockquote class="blockquote"><p><code class="literal">lib.dag.entryAnywhere (value: T) : DagEntry<T></code></p></blockquote></div><p>Indicates that <code class="literal">value</code> can be placed anywhere within the DAG.
|
||
This is also the default for plain attribute set entries, that
|
||
is</p><pre><code class="programlisting nix">foo.bar = {
|
||
a = lib.dag.entryAnywhere 0;
|
||
}
|
||
</code></pre><p>and</p><pre><code class="programlisting nix">foo.bar = {
|
||
a = 0;
|
||
}
|
||
</code></pre><p>are equivalent.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="ch-types-dag-entryAfter" class="title" style="clear: both">entryAfter </h2> </div> </div></div><div class="blockquote"><blockquote class="blockquote"><p><code class="literal">lib.dag.entryAfter (afters: list string) (value: T) : DagEntry<T></code></p></blockquote></div><p>Indicates that <code class="literal">value</code> must be placed <span class="emphasis"><em>after</em></span> each of the
|
||
attribute names in the given list. For example</p><pre><code class="programlisting nix">foo.bar = {
|
||
a = 0;
|
||
b = lib.dag.entryAfter [ "a" ] 1;
|
||
}
|
||
</code></pre><p>would place <code class="literal">b</code> after <code class="literal">a</code> in the graph.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="ch-types-dag-entryBefore" class="title" style="clear: both">entryBefore </h2> </div> </div></div><div class="blockquote"><blockquote class="blockquote"><p><code class="literal">lib.dag.entryBefore (befores: list string) (value: T) : DagEntry<T></code></p></blockquote></div><p>Indicates that <code class="literal">value</code> must be placed <span class="emphasis"><em>before</em></span> each of the
|
||
attribute names in the given list. For example</p><pre><code class="programlisting nix">foo.bar = {
|
||
b = lib.dag.entryBefore [ "a" ] 1;
|
||
a = 0;
|
||
}
|
||
</code></pre><p>would place <code class="literal">b</code> before <code class="literal">a</code> in the graph.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-types-dag-entryBetween" class="title" style="clear: both">entryBetween </h2> </div> </div></div><div class="blockquote"><blockquote class="blockquote"><p><code class="literal">lib.dag.entryBetween (befores: list string) (afters: list string) (value: T) : DagEntry<T></code></p></blockquote></div><p>Indicates that <code class="literal">value</code> must be placed <span class="emphasis"><em>before</em></span> the attribute
|
||
names in the first list and <span class="emphasis"><em>after</em></span> the attribute names in the
|
||
second list. For example</p><pre><code class="programlisting nix">foo.bar = {
|
||
a = 0;
|
||
c = lib.dag.entryBetween [ "b" ] [ "a" ] 2;
|
||
b = 1;
|
||
}
|
||
</code></pre><p>would place <code class="literal">c</code> before <code class="literal">b</code> and after <code class="literal">a</code> in the graph.</p><p>There are also a set of functions that generate a DAG from a list.
|
||
These are convenient when you just want to have a linear list of DAG
|
||
entries, without having to manually enter the relationship between
|
||
each entry. Each of these functions take a <code class="literal">tag</code> as argument and the
|
||
DAG entries will be named <code class="literal">${tag}-${index}</code>.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-types-dag-entriesAnywhere" class="title" style="clear: both">entriesAnywhere </h2> </div> </div></div><div class="blockquote"><blockquote class="blockquote"><p><code class="literal">lib.dag.entriesAnywhere (tag: string) (values: [T]) : Dag<T></code></p></blockquote></div><p>Creates a DAG with the given values with each entry labeled
|
||
using the given tag. For example</p><pre><code class="programlisting nix">foo.bar = lib.dag.entriesAnywhere "a" [ 0 1 ];
|
||
</code></pre><p>is equivalent to</p><pre><code class="programlisting nix">foo.bar = {
|
||
a-0 = 0;
|
||
a-1 = lib.dag.entryAfter [ "a-0" ] 1;
|
||
}
|
||
</code></pre>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-types-dag-entriesAfter" class="title" style="clear: both">entriesAfter </h2> </div> </div></div><div class="blockquote"><blockquote class="blockquote"><p><code class="literal">lib.dag.entriesAfter (tag: string) (afters: list string) (values: [T]) : Dag<T></code></p></blockquote></div><p>Creates a DAG with the given values with each entry labeled
|
||
using the given tag. The list of values are placed are placed
|
||
<span class="emphasis"><em>after</em></span> each of the attribute names in <code class="literal">afters</code>. For example</p><pre><code class="programlisting nix">foo.bar =
|
||
{ b = 0; } // lib.dag.entriesAfter "a" [ "b" ] [ 1 2 ];
|
||
</code></pre><p>is equivalent to</p><pre><code class="programlisting nix">foo.bar = {
|
||
b = 0;
|
||
a-0 = lib.dag.entryAfter [ "b" ] 1;
|
||
a-1 = lib.dag.entryAfter [ "a-0" ] 2;
|
||
}
|
||
</code></pre>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-types-dag-entriesBefore" class="title" style="clear: both">entriesBefore </h2> </div> </div></div><div class="blockquote"><blockquote class="blockquote"><p><code class="literal">lib.dag.entriesBefore (tag: string) (befores: list string) (values: [T]) : Dag<T></code></p></blockquote></div><p>Creates a DAG with the given values with each entry labeled
|
||
using the given tag. The list of values are placed <span class="emphasis"><em>before</em></span> each
|
||
of the attribute names in <code class="literal">befores</code>. For example</p><pre><code class="programlisting nix"> foo.bar =
|
||
{ b = 0; } // lib.dag.entriesBefore "a" [ "b" ] [ 1 2 ];
|
||
</code></pre><p>is equivalent to</p><pre><code class="programlisting nix">foo.bar = {
|
||
b = 0;
|
||
a-0 = 1;
|
||
a-1 = lib.dag.entryBetween [ "b" ] [ "a-0" ] 2;
|
||
}
|
||
</code></pre>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-types-dag-entriesBetween" class="title" style="clear: both">entriesBetween </h2> </div> </div></div><div class="blockquote"><blockquote class="blockquote"><p><code class="literal">lib.dag.entriesBetween (tag: string) (befores: list string) (afters: list string) (values: [T]) : Dag<T></code></p></blockquote></div><p>Creates a DAG with the given values with each entry labeled
|
||
using the given tag. The list of values are placed <span class="emphasis"><em>before</em></span> each
|
||
of the attribute names in <code class="literal">befores</code> and <span class="emphasis"><em>after</em></span> each of the
|
||
attribute names in <code class="literal">afters</code>. For example</p><pre><code class="programlisting nix">foo.bar =
|
||
{ b = 0; c = 3; } // lib.dag.entriesBetween "a" [ "b" ] [ "c" ] [ 1 2 ];
|
||
</code></pre><p>is equivalent to</p><pre><code class="programlisting nix">foo.bar = {
|
||
b = 0;
|
||
c = 3;
|
||
a-0 = lib.dag.entryAfter [ "c" ] 1;
|
||
a-1 = lib.dag.entryBetween [ "b" ] [ "a-0" ] 2;
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
|
||
</div>
|
||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h1 id="ch-hacking" class="title" >Hacking nvf </h1> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-contrib-getting-started">Getting Started</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines">Guidelines</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-documentation">Adding Documentation</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-formatting">Formatting Code</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-commit-message-style">Formatting Commits</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-commit-style">Commit Style</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-ex-commit-message">Example Commit</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-code-style">Code Style</a> </span></dt></dl></dd><dt> <span class="section"> <a href="index.xhtml#sec-testing-changes">Testing Changes</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-keybinds">Keybinds</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-custom-key-mappings">Custom Key Mappings Support for a Plugin</a> </span></dt></dl></dd><dt> <span class="section"> <a href="index.xhtml#sec-additional-plugins">Adding Plugins</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-modular-setup-options">Modular setup options</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-details-of-toluaobject">Details of toLuaObject</a> </span></dt></dl></dd> </dl></div><p><span class="strong"><strong>nvf</strong></span> is designed for developers as much as it is for the end user. I would like any potential contributor
|
||
to be able to propagate their desired changes into the repository without the extra effort. As such, below are guides
|
||
(and guidelines) to streamline the contribution process and ensure that your valuable input seamlessly integrates
|
||
into <span class="strong"><strong>nvf</strong></span>’s development without leaving question marks in your head.</p><p>This section is mainly directed towards those who wish to contribute code into <span class="strong"><strong>nvf</strong></span>. If you wish to instead
|
||
report a bug or discuss a potential feature implementation, first look among the
|
||
already <a class="link" href="https://github.com/notashelf/nvf/issues" target="_top">open issues</a> and if no matching issue exists you may open
|
||
a <a class="link" href="https://github.com/notashelf/nvf/issues/new" target="_top">new issue</a> and describe your problem/request. While creating an
|
||
issue, please try to include as much information as you can, ideally also include relevant context in which an issue
|
||
occurs or a feature should be implemented.</p><div class="section"> <div class="titlepage"> <div> <div> <h1 id="sec-contrib-getting-started" class="title" style="clear: both">Getting Started </h1> </div> </div></div><p>You, naturally, would like to start by forking the repository to get started. If
|
||
you are new to Git and GitHub, do have a look at GitHub’s <a class="link" href="https://help.github.com/articles/fork-a-repo/" target="_top">Fork a repo guide</a>
|
||
for instructions on how you can do this. Once you have a fork of <span class="strong"><strong>nvf</strong></span>, you
|
||
should create a separate branch based on the msot recent <code class="literal">main</code> branch. Give
|
||
your branch a reasonably descriptive name (e.g. <code class="literal">feature/debugger</code> or
|
||
<code class="literal">fix/pesky-bug</code>) and you are ready to work on your changes</p><p>Implement your changes and commit them to the newly created branch and when you
|
||
are happy with the result, and positive that it fullfills our <a class="link" href="index.xhtml#sec-guidelines" title="Guidelines" >Contributing
|
||
Guidelines</a>, push the branch to GitHub and <a class="link" href="https://help.github.com/articles/creating-a-pull-request" target="_top">create a pull
|
||
request</a>. The default
|
||
pull request template available on the <span class="strong"><strong>nvf</strong></span> repository will guide you through
|
||
the rest of the process, and we’ll gently nudge you in the correct direction if
|
||
there are any mistakes.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h1 id="sec-guidelines" class="title" style="clear: both">Guidelines </h1> </div> </div></div><div class="toc"> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-guidelines-documentation">Adding Documentation</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-formatting">Formatting Code</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-commit-message-style">Formatting Commits</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-commit-style">Commit Style</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-ex-commit-message">Example Commit</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-code-style">Code Style</a> </span></dt> </dl></div><p>If your contribution tightly follows the guidelines, then there is a good chance
|
||
it will be merged without too much trouble. Some of the guidelines will be
|
||
strictly enforced, others will remain as gentle nudges towards the correct
|
||
direction. As we have no automated system enforcing those guidelines, please
|
||
try to double check your changes before making your pull request in order to
|
||
avoid “faulty” code slipping by.</p><p>If you are uncertain how these rules affect the change you would like to make
|
||
then feel free to start a discussion in the <a class="link" href="https://github.com/NotAShelf/nvf/discussions" target="_top">discussions tab</a>
|
||
ideally (but not necessarily) before you start developing.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-guidelines-documentation" class="title" style="clear: both">Adding Documentation </h2> </div> </div></div><p>Most, if not all, changes warrant changes to the documentation. Module options
|
||
should be documented with <a class="link" href="https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup" target="_top">Nixpkgs-flavoured Markdown</a>,
|
||
albeit with exceptions.</p><div class="note"><h3 class="title">Note</h3><p>As of <span class="strong"><strong>v0.5</strong></span>, <span class="strong"><strong>nvf</strong></span> is itself documented using full markdown in both module
|
||
options and the manual. With <span class="strong"><strong>v0.6</strong></span>, this manual has also been converted to
|
||
markdown in full.</p></div><p>The HTML version of this manual containing both the module option descriptions
|
||
and the documentation of <span class="strong"><strong>nvf</strong></span> (such as this page) can be generated and
|
||
opened by typing the following in a shell within a clone of the <span class="strong"><strong>nvf</strong></span> Git
|
||
repository:</p><pre><code class="programlisting console">$ nix build .#docs-html
|
||
$ xdg-open $PWD/result/share/doc/nvf/index.html
|
||
</code></pre>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-guidelines-formatting" class="title" style="clear: both">Formatting Code </h2> </div> </div></div><p>Make sure your code is formatted as described in <a class="link" href="index.xhtml#sec-guidelines-code-style" title="Code Style" >code-style
|
||
section</a>. To maintain consistency throughout the
|
||
project you are encouraged to browse through existing code and adopt its style
|
||
also in new code.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-guidelines-commit-message-style" class="title" style="clear: both">Formatting Commits </h2> </div> </div></div><p>Similar to <a class="link" href="index.xhtml#sec-guidelines-code-style" title="Code Style" >code style guidelines</a> we encourage a
|
||
consistent commit message format as described in <a class="link" href="index.xhtml#sec-guidelines-commit-style" title="Commit Style" >commit style
|
||
guidelines</a>.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-guidelines-commit-style" class="title" style="clear: both">Commit Style </h2> </div> </div></div><p>The commits in your pull request should be reasonably self-contained. Which
|
||
means each and every commit in a pull request should make sense both on its
|
||
own and in general context. That is, a second commit should not resolve an
|
||
issue that is introduced in an earlier commit. In particular, you will be
|
||
asked to amend any commit that introduces syntax errors or similar problems
|
||
even if they are fixed in a later commit.</p><p>The commit messages should follow the <a class="link" href="https://chris.beams.io/posts/git-commit/#seven-rule" target="_top">seven
|
||
rules</a>, except for
|
||
“Capitalize the subject line”. We also ask you to include the affected code
|
||
component or module in the first line. A commit message ideally, but not
|
||
necessarily, follow the given template from home-manager’s own documentation</p><pre><code class="programlisting"> {component}: {description}
|
||
|
||
{long description}
|
||
</code></pre><p>where <code class="literal">{component}</code> refers to the code component (or module) your change
|
||
affects, <code class="literal">{description}</code> is a very brief description of your change, and
|
||
<code class="literal">{long description}</code> is an optional clarifying description. As a rare
|
||
exception, if there is no clear component, or your change affects many
|
||
components, then the <code class="literal">{component}</code> part is optional. See <a class="link" href="index.xhtml#sec-guidelines-ex-commit-message" title="Example Commit" >example commit
|
||
message</a> for a commit message that
|
||
fulfills these requirements.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-guidelines-ex-commit-message" class="title" style="clear: both">Example Commit </h2> </div> </div></div><p>The commit <a class="link" href="https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef" target="_top">69f8e47e9e74c8d3d060ca22e18246b7f7d988ef</a>
|
||
in home-manager contains the following commit message.</p><pre><code class="programlisting">starship: allow running in Emacs if vterm is used
|
||
|
||
The vterm buffer is backed by libvterm and can handle Starship prompts
|
||
without issues.
|
||
</code></pre><p>Similarly, if you are contributing to <span class="strong"><strong>nvf</strong></span>, you would include the scope of
|
||
the commit followed by the description:</p><pre><code class="programlisting">languages/ruby: init module
|
||
|
||
Adds a language module for Ruby, adds appropriate formatters and Treesitter grammers
|
||
</code></pre><p>Long description can be ommitted if the change is too simple to warrant it. A
|
||
minor fix in spelling or a formatting change does not warrant long description,
|
||
however, a module addition or removal does as you would like to provide the
|
||
relevant context, i.e. the reasoning behind it, for your commit.</p><p>Finally, when adding a new module, say <code class="literal">modules/foo.nix</code>, we use the fixed
|
||
commit format <code class="literal">foo: add module</code>. You can, of course, still include a long
|
||
description if you wish.</p><p>In case of nested modules, i.e <code class="literal">modules/languages/java.nix</code> you are recommended
|
||
to contain the parent as well - for example <code class="literal">languages/java: some major change</code>.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-guidelines-code-style" class="title" style="clear: both">Code Style </h2> </div> </div></div><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-code-style-treewide" class="title" >Treewide </h3> </div> </div></div><p>Keep lines at a reasonable width, ideally 80 characters or less. This also applies
|
||
to string literals and module descriptions and documentation.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-code-style-nix" class="title" >Nix </h3> </div> </div></div><p><span class="strong"><strong>nvf</strong></span> is formatted by the <a class="link" href="https://github.com/kamadorueda/alejandra" target="_top">alejandra</a>
|
||
tool and the formatting is checked in the pull request and push workflows. Run the
|
||
<code class="literal">nix fmt</code> command inside the project repository before submitting your pull request.</p><p>While Alejandra is mostly opinionated on how code looks after formatting,
|
||
certain changes are done at the user’s discretion based on how the original
|
||
code was structured.</p><p>Please use one line code for attribute sets that contain only one subset.
|
||
For example:</p><pre><code class="programlisting nix"># parent modules should always be unfolded
|
||
# which means module = { value = ... } instead of module.value = { ... }
|
||
module = {
|
||
value = mkEnableOption "some description" // { default = true; }; # merges can be done inline where possible
|
||
|
||
# same as parent modules, unfold submodules
|
||
subModule = {
|
||
# this is an option that contains more than one nested value
|
||
someOtherValue = mkOption {
|
||
type = lib.types.bool;
|
||
description = "Some other description";
|
||
default = true;
|
||
};
|
||
};
|
||
}
|
||
</code></pre><p>If you move a line down after the merge operator, Alejandra will automatically
|
||
unfold the whole merged attrset for you, which we <span class="strong"><strong>do not</strong></span> want.</p><pre><code class="programlisting nix">module = {
|
||
key = mkEnableOption "some description" // {
|
||
default = true; # we want this to be inline
|
||
}; # ...
|
||
}
|
||
</code></pre><p>For lists, it is mostly up to your own discretion how you want to format them,
|
||
but please try to unfold lists if they contain multiple items and especially
|
||
if they are to include comments.</p><pre><code class="programlisting nix"># this is ok
|
||
acceptableList = [
|
||
item1 # comment
|
||
item2
|
||
item3 # some other comment
|
||
item4
|
||
];
|
||
|
||
# this is not ok
|
||
listToBeAvoided = [item1 item2 /* comment */ item3 item4];
|
||
|
||
# this is ok
|
||
acceptableList = [item1 item2];
|
||
|
||
# this is also ok if the list is expected to contain more elements
|
||
acceptableList= [
|
||
item1
|
||
item2
|
||
# more items if needed...
|
||
];
|
||
</code></pre>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h1 id="sec-testing-changes" class="title" style="clear: both">Testing Changes </h1> </div> </div></div><p>Once you have made your changes, you will need to test them throughly. If it is
|
||
a module, add your module option to <code class="literal">configuration.nix</code> (located in the root of
|
||
this project) inside <code class="literal">neovimConfiguration</code>. Enable it, and then run the maximal
|
||
configuration with <code class="literal">nix run .#maximal -Lv</code> to check for build errors. If neovim
|
||
opens in the current directory without any error messages (you can check the
|
||
output of <code class="literal">:messages</code> inside neovim to see if there are any errors), then your
|
||
changes are good to go. Open your pull request, and it will be reviewed as soon
|
||
as posssible.</p><p>If it is not a new module, but a change to an existing one, then make sure the
|
||
module you have changed is enabled in the maximal configuration by editing
|
||
<code class="literal">configuration.nix</code>, and then run it with <code class="literal">nix run .#maximal -Lv</code>. Same procedure
|
||
as adding a new module will apply here.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h1 id="sec-keybinds" class="title" style="clear: both">Keybinds </h1> </div> </div></div><div class="toc"> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-custom-key-mappings">Custom Key Mappings Support for a Plugin</a> </span></dt> </dl></div><p>As of 0.4, there exists an API for writing your own keybinds and a couple of
|
||
useful utility functions are available in the <a class="link" href="https://github.com/NotAShelf/nvf/tree/main/lib" target="_top">extended standard
|
||
library</a>. The following
|
||
section contains a general overview to how you may utilize said functions.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-custom-key-mappings" class="title" style="clear: both">Custom Key Mappings Support for a Plugin </h2> </div> </div></div><p>To set a mapping, you should define it in <code class="literal">vim.maps.<<mode>></code>.
|
||
The available modes are:</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p>normal</p></li><li class="listitem"><p>insert</p></li><li class="listitem"><p>select</p></li><li class="listitem"><p>visual</p></li><li class="listitem"><p>terminal</p></li><li class="listitem"><p>normalVisualOp</p></li><li class="listitem"><p>visualOnly</p></li><li class="listitem"><p>operator</p></li><li class="listitem"><p>insertCommand</p></li><li class="listitem"><p>lang</p></li><li class="listitem"><p>command</p></li></ul></div><p>An example, simple keybinding, can look like this:</p><pre><code class="programlisting nix">{
|
||
vim.maps.normal = {
|
||
"<leader>wq" = {
|
||
action = ":wq<CR>";
|
||
silent = true;
|
||
desc = "Save file and quit";
|
||
};
|
||
};
|
||
}
|
||
</code></pre><p>There are many settings available in the options. Please refer to the
|
||
<a class="link" href="https://notashelf.github.io/nvf/options.html#opt-vim.maps.command._name_.action" target="_top">documentation</a>
|
||
to see a list of them.</p><p><span class="strong"><strong>nvf</strong></span> provides a list of helper commands, so that you don’t have to write the
|
||
mapping attribute sets every time:</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p><code class="literal">mkBinding = key: action: desc:</code> - makes a basic binding, with <code class="literal">silent</code> set
|
||
to true.</p></li><li class="listitem"><p><code class="literal">mkExprBinding = key: action: desc:</code> - makes an expression binding, with
|
||
<code class="literal">lua</code>, <code class="literal">silent</code>, and <code class="literal">expr</code> set to true.</p></li><li class="listitem"><p><code class="literal">mkLuaBinding = key: action: desc:</code> - makes an expression binding, with
|
||
<code class="literal">lua</code>, and <code class="literal">silent</code> set to true.</p></li></ul></div><p>Do note that the Lua in these bindings is actual Lua, and not pasted into a
|
||
<code class="literal">:lua</code> command. Therefore, you should either pass in a function like
|
||
<code class="literal">require('someplugin').some_function</code>, without actually calling it, or you
|
||
should define your own functions, for example</p><pre><code class="programlisting lua">function()
|
||
require('someplugin').some_function()
|
||
end
|
||
</code></pre><p>Additionally, to not have to repeat the descriptions, there’s another utility
|
||
function with its own set of functions: Utility function that takes two
|
||
attribute sets:</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p><code class="literal">{ someKey = "some_value" }</code></p></li><li class="listitem"><p><code class="literal">{ someKey = { description = "Some Description"; }; }</code></p></li></ul></div><p>and merges them into <code class="literal">{ someKey = { value = "some_value"; description = "Some Description"; }; }</code></p><pre><code class="programlisting nix">addDescriptionsToMappings = actualMappings: mappingDefinitions:
|
||
</code></pre><p>This function can be used in combination with the same <code class="literal">mkBinding</code> functions as
|
||
above, except they only take two arguments - <code class="literal">binding</code> and <code class="literal">action</code>, and have
|
||
different names:</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p><code class="literal">mkSetBinding = binding: action:</code> - makes a basic binding, with <code class="literal">silent</code>
|
||
set to true.</p></li><li class="listitem"><p><code class="literal">mkSetExprBinding = binding: action:</code> - makes an expression binding, with
|
||
<code class="literal">lua</code>, <code class="literal">silent</code>, and <code class="literal">expr</code> set to true.</p></li><li class="listitem"><p><code class="literal">mkSetLuaBinding = binding: action:</code> - makes an expression binding, with
|
||
<code class="literal">lua</code>, and <code class="literal">silent</code> set to true.</p></li></ul></div><p>You can read the source code of some modules to see them in action, but their
|
||
usage should look something like this:</p><pre><code class="programlisting nix"># plugindefinition.nix
|
||
{lib, ...}: with lib; {
|
||
options.vim.plugin = {
|
||
enable = mkEnableOption "Enable plugin";
|
||
|
||
# Mappings should always be inside an attrset called mappings
|
||
mappings = {
|
||
# mkMappingOption is a helper function from lib,
|
||
# that takes a description (which will also appear in which-key),
|
||
# and a default mapping (which can be null)
|
||
toggleCurrentLine = mkMappingOption "Toggle current line comment" "gcc";
|
||
toggleCurrentBlock = mkMappingOption "Toggle current block comment" "gbc";
|
||
|
||
toggleOpLeaderLine = mkMappingOption "Toggle line comment" "gc";
|
||
toggleOpLeaderBlock = mkMappingOption "Toggle block comment" "gb";
|
||
|
||
toggleSelectedLine = mkMappingOption "Toggle selected comment" "gc";
|
||
toggleSelectedBlock = mkMappingOption "Toggle selected block" "gb";
|
||
};
|
||
|
||
};
|
||
}
|
||
</code></pre><pre><code class="programlisting nix"># config.nix
|
||
{
|
||
config,
|
||
pkgs,
|
||
lib,
|
||
...
|
||
}:
|
||
with lib;
|
||
with builtins; let
|
||
cfg = config.vim.plugin;
|
||
self = import ./plugindefinition.nix {inherit lib;};
|
||
mappingDefinitions = self.options.vim.plugin;
|
||
|
||
# addDescriptionsToMappings is a helper function from lib,
|
||
# that merges mapping values and their descriptions
|
||
# into one nice attribute set
|
||
mappings = addDescriptionsToMappings cfg.mappings mappingDefinitions;
|
||
in {
|
||
config = mkIf (cfg.enable) {
|
||
# ...
|
||
vim.maps.normal = mkMerge [
|
||
# mkSetBinding is another helper function from lib,
|
||
# that actually adds the mapping with a description.
|
||
(mkSetBinding mappings.findFiles "<cmd> Telescope find_files<CR>")
|
||
(mkSetBinding mappings.liveGrep "<cmd> Telescope live_grep<CR>")
|
||
(mkSetBinding mappings.buffers "<cmd> Telescope buffers<CR>")
|
||
(mkSetBinding mappings.helpTags "<cmd> Telescope help_tags<CR>")
|
||
(mkSetBinding mappings.open "<cmd> Telescope<CR>")
|
||
|
||
(mkSetBinding mappings.gitCommits "<cmd> Telescope git_commits<CR>")
|
||
(mkSetBinding mappings.gitBufferCommits "<cmd> Telescope git_bcommits<CR>")
|
||
(mkSetBinding mappings.gitBranches "<cmd> Telescope git_branches<CR>")
|
||
(mkSetBinding mappings.gitStatus "<cmd> Telescope git_status<CR>")
|
||
(mkSetBinding mappings.gitStash "<cmd> Telescope git_stash<CR>")
|
||
|
||
(mkIf config.vim.lsp.enable (mkMerge [
|
||
(mkSetBinding mappings.lspDocumentSymbols "<cmd> Telescope lsp_document_symbols<CR>")
|
||
(mkSetBinding mappings.lspWorkspaceSymbols "<cmd> Telescope lsp_workspace_symbols<CR>")
|
||
|
||
(mkSetBinding mappings.lspReferences "<cmd> Telescope lsp_references<CR>")
|
||
(mkSetBinding mappings.lspImplementations "<cmd> Telescope lsp_implementations<CR>")
|
||
(mkSetBinding mappings.lspDefinitions "<cmd> Telescope lsp_definitions<CR>")
|
||
(mkSetBinding mappings.lspTypeDefinitions "<cmd> Telescope lsp_type_definitions<CR>")
|
||
(mkSetBinding mappings.diagnostics "<cmd> Telescope diagnostics<CR>")
|
||
]))
|
||
|
||
(
|
||
mkIf config.vim.treesitter.enable
|
||
(mkSetBinding mappings.treesitter "<cmd> Telescope treesitter<CR>")
|
||
)
|
||
];
|
||
# ...
|
||
};
|
||
}
|
||
|
||
</code></pre><div class="note"><h3 class="title">Note</h3><p>If you have come across a plugin that has an API that doesn’t seem to easily
|
||
allow custom keybindings, don’t be scared to implement a draft PR. We’ll help
|
||
you get it done.</p></div>
|
||
</div>
|
||
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h1 id="sec-additional-plugins" class="title" style="clear: both">Adding Plugins </h1> </div> </div></div><div class="toc"> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-modular-setup-options">Modular setup options</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-details-of-toluaobject">Details of toLuaObject</a> </span></dt> </dl></div><p>To add a new Neovim plugin, first add the source url in the inputs section of <code class="literal">flake.nix</code>
|
||
with the prefix <code class="literal">plugin-</code></p><pre><code class="programlisting nix">
|
||
{
|
||
inputs = {
|
||
# ...
|
||
plugin-neodev-nvim = {
|
||
url = "github:folke/neodev.nvim";
|
||
flake = false;
|
||
};
|
||
# ...
|
||
};
|
||
}
|
||
</code></pre><p>The addition of the <code class="literal">plugin-</code> prefix will allow <span class="strong"><strong>nvf</strong></span> to autodiscover the
|
||
input from the flake inputs automatically, allowing you to refer to it in areas
|
||
that require a very specific plugin type as defined in <code class="literal">lib/types/plugins.nix</code></p><p>You can now reference this plugin using its string name, the plugin will be
|
||
built with the name and source URL from the flake input, allowing you to
|
||
refer to it as a <span class="strong"><strong>string</strong></span>.</p><pre><code class="programlisting nix">config.vim.startPlugins = ["neodev-nvim"];
|
||
</code></pre><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-modular-setup-options" class="title" style="clear: both">Modular setup options </h2> </div> </div></div><p>Most plugins is initialized with a call to <code class="literal">require('plugin').setup({...})</code>.</p><p>We use a special function that lets you easily add support for such setup options in a modular way:
|
||
<code class="literal">mkPluginSetupOption</code>.</p><p>Once you have added the source of the plugin as shown above, you can define the setup options like
|
||
this:</p><pre><code class="programlisting nix"># in modules/.../your-plugin/your-plugin.nix
|
||
|
||
{lib, ...}:
|
||
let
|
||
inherit (lib.types) bool int;
|
||
inherit (lib.nvim.types) mkPluginSetupOption;
|
||
in {
|
||
options.vim.your-plugin = {
|
||
setupOpts = mkPluginSetupOption "plugin name" {
|
||
enable_feature_a = mkOption {
|
||
type = bool;
|
||
default = false;
|
||
# ...
|
||
};
|
||
|
||
number_option = mkOption {
|
||
type = int;
|
||
default = 3;
|
||
# ...
|
||
};
|
||
};
|
||
};
|
||
}
|
||
</code></pre><pre><code class="programlisting nix"># in modules/.../your-plugin/config.nix
|
||
{lib, config, ...}:
|
||
let
|
||
cfg = config.vim.your-plugin;
|
||
in {
|
||
vim.luaConfigRC = lib.nvim.dag.entryAnywhere ''
|
||
require('plugin-name').setup(${lib.nvim.lua.toLuaObject cfg.setupOpts})
|
||
'';
|
||
}
|
||
</code></pre><p>This above config will result in this lua script:</p><pre><code class="programlisting lua">require('plugin-name').setup({
|
||
enable_feature_a = false,
|
||
number_option = 3,
|
||
})
|
||
</code></pre><p>Now users can set any of the pre-defined option field, and can also add their own fields!</p><pre><code class="programlisting nix"># in user's config
|
||
{
|
||
vim.your-plugin.setupOpts = {
|
||
enable_feature_a = true;
|
||
number_option = 4;
|
||
another_field = "hello";
|
||
size = { # nested fields work as well
|
||
top = 10;
|
||
};
|
||
};
|
||
}
|
||
</code></pre>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-details-of-toluaobject" class="title" style="clear: both">Details of toLuaObject </h2> </div> </div></div><p>As you’ve seen above, <code class="literal">toLuaObject</code> is used to convert our nix attrSet
|
||
<code class="literal">cfg.setupOpts</code>, into a lua table. Here are some rules of the conversion:</p><div class="orderedlist"><ol class="orderedlist compact" type="1"><li class="listitem"><p>nix <code class="literal">null</code> converts to lua <code class="literal">nil</code></p></li><li class="listitem"><p>number and strings convert to their lua counterparts</p></li><li class="listitem"><p>nix attrSet/list convert into lua tables</p></li><li class="listitem"><p>you can write raw lua code using <code class="literal">lib.generators.mkLuaInline</code>. This
|
||
function is part of nixpkgs.</p></li></ol></div><p>Example:</p><pre><code class="programlisting nix">vim.your-plugin.setupOpts = {
|
||
on_init = lib.generators.mkLuaInline ''
|
||
function()
|
||
print('we can write lua!')
|
||
end
|
||
'';
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"> </td>
|
||
<td width="20%" align="center"> </td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="plugins.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top"> </td>
|
||
<td width="20%" align="center"> </td>
|
||
<td width="40%" align="right" valign="top"> Appendix A. Plugin specific quirks</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html> |