mirror of
https://github.com/NotAShelf/neovim-flake.git
synced 2024-12-19 09:49:48 +01:00
1018 lines
No EOL
86 KiB
HTML
1018 lines
No EOL
86 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><script src="script/anchor-use.js" type="text/javascript"></script><script src="script/anchor-min.js" type="text/javascript"></script><script src="script/search.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="quirks.html" title="Appendix A. Known Issues and 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="quirks.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.8</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><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-what-is-it">What is nvf</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-bugs-suggestions">Bugs & Suggestions</a> </span></dt></dl></dd><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-prebuilt-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-custom-inputs">Custom Inputs</a> </span></dt><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><dt> <span class="chapter"> <a href="index.xhtml#ch-dag-entries">DAG entries in nvf</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#ch-vim-luaconfigrc"><code class="literal">vim.luaConfigRC</code> (top-level DAG)</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="quirks.html">A. Known Issues and Quirks</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="quirks.html#ch-quirks-nodejs">NodeJS</a> </span></dt></dl></dd><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><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-what-is-it">What is nvf</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-bugs-suggestions">Bugs & Suggestions</a> </span></dt> </dl></div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-what-is-it" class="title" >What is nvf </h2> </div> </div></div><p>nvf is a highly modular, configurable, extensible and easy to use Neovim
|
||
configuration in Nix. Designed for flexibility and ease of use, nvf allows you
|
||
to easily configure your fully featured Neovim instance with a few lines of Nix.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-bugs-suggestions" class="title" >Bugs & Suggestions </h2> </div> </div></div><p>If you notice any issues with nvf, or this documentation, then please consider
|
||
reporting them over at the <a class="link" href="https://github.com/notashelf/nvf/issues" target="_top">issue tracker</a>. Issues tab, in addition to the
|
||
<a class="link" href="https://github.com/notashelf/nvf/discussions" target="_top">discussions tab</a> is a good place as any to request new features.</p><p>You may also consider submitting bugfixes, feature additions and upstreamed
|
||
changes that you think are critical over at the <a class="link" href="https://github.com/notashelf/nvf/pulls" target="_top">pull requests tab</a>.</p>
|
||
</div>
|
||
|
||
</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-prebuilt-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, two specialized
|
||
configurations are provided:</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p><span class="strong"><strong>Nix</strong></span> - Nix language server + simple utility plugins</p></li><li class="listitem"><p><span class="strong"><strong>Maximal</strong></span> - Variable language servers + utility and decorative plugins</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 bash">$ 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-prebuilt-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 bash">$ 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 alongside
|
||
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><div class="tip"><h3 class="title">Tip</h3><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><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><p>::: {.note} 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 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 nvf without depending on NixOS or Home-Manager as the
|
||
parent module system, using the <code class="literal">neovimConfiguration</code> function exposed in the
|
||
extended library. This function will take <code class="literal">modules</code> and <code class="literal">extraSpecialArgs</code> as
|
||
arguments, and return the following schema 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><p>An example flake that exposes your custom Neovim configuration might look like</p><pre><code class="programlisting nix">{
|
||
inputs = {
|
||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||
nvf.url = "github:notashelf/nvf";
|
||
};
|
||
|
||
outputs = {
|
||
self,
|
||
nixpkgs,
|
||
...
|
||
} @ inputs: {
|
||
packages."x86_64-linux" = let
|
||
neovimConfigured = (inputs.nvf.lib.neovimConfiguration {
|
||
inherit (nixpkgs.legacyPackages."x86_64-linux") pkgs;
|
||
modules = [{
|
||
config.vim = {
|
||
# Enable custom theming options
|
||
theme.enable = true;
|
||
|
||
# Enable Treesitter
|
||
tree-sitter.enable = true;
|
||
|
||
# Other options will go here. Refer to the config
|
||
# reference in Appendix B of the nvf manual.
|
||
# ...
|
||
};
|
||
}];
|
||
});
|
||
in {
|
||
# Set the default package to the wrapped instance of Neovim.
|
||
# This will allow running your Neovim configuration with
|
||
# `nix run` and in addition, sharing your configuration with
|
||
# other users in case your repository is public.
|
||
default = neovimConfigured.neovim;
|
||
};
|
||
};
|
||
}
|
||
</code></pre><p>The above setup will allow to set up nvf as a standalone flake, which you can
|
||
build independently from your system configuration while also possibly sharing
|
||
it with others. The next two chapters will detail specific usage of such a setup
|
||
for a package output in the context of NixOS or Home-Manager installation.</p><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 Neovim 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 extensively.</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 {
|
||
inherit pkgs;
|
||
modules = [configModule];
|
||
};
|
||
in {
|
||
# This will make the package available as a flake output under 'packages'
|
||
packages.${system}.my-neovim = customNeovim.neovim;
|
||
|
||
# Example nixosConfiguration using the configured Neovim package
|
||
nixosConfigurations = {
|
||
yourHostName = nixpkgs.lib.nixosSystem {
|
||
# ...
|
||
modules = [
|
||
# 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 Neovim 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 extensively.</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 {
|
||
inherit pkgs;
|
||
modules = [configModule];
|
||
};
|
||
in {
|
||
# This will make the package available as a flake output under 'packages'
|
||
packages.${system}.my-neovim = customNeovim.neovim;
|
||
|
||
# Example Home-Manager configuration using the configured Neovim package
|
||
homeConfigurations = {
|
||
"your-username@your-hostname" = home-manager.lib.homeManagerConfiguration {
|
||
# ...
|
||
modules = [
|
||
# This will make Neovim available to users using the Home-Manager
|
||
# configuration. To make the package available to all users, prefer
|
||
# environment.systemPackages in your NixOS configuration.
|
||
{home.packages = [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><p>The below chapters will describe installing nvf as NixOS and Home-Manager
|
||
modules. Note that those methods are mutually exclusive, and will likely cause
|
||
path collisions if used simultaneously.</p><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 available 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 available 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-custom-inputs">Custom Inputs</a> </span></dt><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><dt> <span class="chapter"> <a href="index.xhtml#ch-dag-entries">DAG entries in nvf</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#ch-vim-luaconfigrc"><code class="literal">vim.luaConfigRC</code> (top-level DAG)</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-lazy-method">Lazy Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-non-lazy-method">Non-lazy Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-legacy-method">Legacy 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 convenience 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-lazy-method">Lazy Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-non-lazy-method">Non-lazy Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-legacy-method">Legacy 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 <a class="xref" href="options.html#opt-vim.startPlugins" ><code class="option">vim.startPlugins</code></a> 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 added, 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 lua config using either
|
||
<code class="literal">config.vim.lazy.plugins.*.setupOpts</code> <code class="literal">config.vim.extraPlugins.*.setup</code> or
|
||
<code class="literal">config.vim.luaConfigRC</code>.</p><p>The first option uses an extended version of <code class="literal">lz.n</code>’s PluginSpec. <code class="literal">setupModule</code>
|
||
and <code class="literal">setupOpt</code> can be used if the plugin uses a <code class="literal">require('module').setup(...)</code>
|
||
pattern. Otherwise, the <code class="literal">before</code> and <code class="literal">after</code> hooks should do what you need.</p><pre><code class="programlisting nix">{
|
||
config.vim.lazy.plugins = {
|
||
aerial.nvim = {
|
||
# ^^^^^^^^^ this name should match the package.pname or package.name
|
||
package = aerial-nvim;
|
||
|
||
setupModule = "aerial";
|
||
setupOpts = {option_name = false;};
|
||
|
||
after = "print('aerial loaded')";
|
||
};
|
||
};
|
||
}
|
||
</code></pre><p>The second option uses an attribute set, which maps DAG section names to a
|
||
custom type, which has the fields <code class="literal">package</code>, <code class="literal">after</code>, <code class="literal">setup</code>. They allow you to
|
||
set the package of the plugin, the sections its setup code should be after (note
|
||
that the <code class="literal">extraPlugins</code> option has its own DAG scope), and the its setup code
|
||
respectively. For example:</p><pre><code class="programlisting nix">config.vim.extraPlugins = with pkgs.vimPlugins; {
|
||
aerial = {
|
||
package = aerial-nvim;
|
||
setup = "require('aerial').setup {}";
|
||
};
|
||
|
||
harpoon = {
|
||
package = harpoon;
|
||
setup = "require('harpoon').setup {}";
|
||
after = ["aerial"]; # place harpoon configuration after aerial
|
||
};
|
||
}
|
||
</code></pre><p>The third option also uses an attribute set, but this one is resolved as a DAG
|
||
directly. The attribute names denote the section names, and the values lua code.
|
||
For example:</p><pre><code class="programlisting nix">{
|
||
# this will create an "aquarium" section in your init.lua with the contents of your custom config
|
||
# which will be *appended* to the rest of your configuration, inside your init.vim
|
||
config.vim.luaConfigRC.aquarium = "vim.cmd('colorscheme aquiarum')";
|
||
}
|
||
</code></pre><div class="note"><h3 class="title">Note</h3><p>One of the greatest strengths of nvf is the ability to order
|
||
snippets of configuration via the DAG system. It will allow specifying positions
|
||
of individual sections of configuration as needed. nvf provides helper functions
|
||
in the extended library, usually under <code class="literal">inputs.nvf.lib.nvim.dag</code> that you may
|
||
use.</p><p>Please refer to the <a class="link" href="/index.xhtml#ch-dag-entries" target="_top">DAG section</a> in the nvf manual
|
||
to find out more about the DAG system.</p></div>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-lazy-method" class="title" >Lazy Method </h3> </div> </div></div><p>As of version <span class="strong"><strong>0.7</strong></span>, we exposed an API for configuring lazy-loaded plugins via
|
||
<code class="literal">lz.n</code> and <code class="literal">lzn-auto-require</code>.</p><pre><code class="programlisting nix">{
|
||
config.vim.lazy.plugins = {
|
||
"aerial.nvim" = {
|
||
package = pkgs.vimPlugins.aerial-nvim;
|
||
setupModule = "aerial";
|
||
setupOpts = {
|
||
option_name = true;
|
||
};
|
||
after = ''
|
||
-- custom lua code to run after plugin is loaded
|
||
print('aerial loaded')
|
||
'';
|
||
|
||
# Explicitly mark plugin as lazy. You don't need this if you define one of
|
||
# the trigger "events" below
|
||
lazy = true;
|
||
|
||
# load on command
|
||
cmd = ["AerialOpen"];
|
||
|
||
# load on event
|
||
event = ["BufEnter"];
|
||
|
||
# load on keymap
|
||
keys = [
|
||
{
|
||
key = "<leader>a";
|
||
action = ":AerialToggle<CR>";
|
||
}
|
||
];
|
||
};
|
||
};
|
||
}
|
||
</code></pre>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-non-lazy-method" class="title" >Non-lazy 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-legacy-method" class="title" >Legacy Method </h3> </div> </div></div><p>Prior to version v0.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 not available in nvf as a module to your configuration, you may
|
||
add it to <a class="xref" href="options.html#opt-vim.startPlugins" ><code class="option">vim.startPlugins</code></a> in order to make it available to Neovim at
|
||
runtime.</p><pre><code class="programlisting nix">{pkgs, ...}: {
|
||
# Add a Neovim plugin from Nixpkgs to the runtime.
|
||
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
|
||
# This assumes you have an input called 'nvf' in your flake inputs
|
||
# and 'inputs' in your specialArgs. In the case you have passed 'nvf'
|
||
# to specialArgs, the 'inputs' prefix may be omitted.
|
||
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-custom-inputs" class="title" >Custom Inputs </h2> </div> </div></div><p>One of the greatest strengths of <span class="strong"><strong>nvf</strong></span> is its ability to get plugins from
|
||
flake inputs and build them locally from any given source. For plugins that do
|
||
not require any kind of additional building step, this is a powerful method of
|
||
adding plugins to your configuration that are not packaged in nixpkgs, or those
|
||
you want to track from source without relying on nixpkgs.</p><p>The <a class="link" href="index.xhtml#sec-additional-plugins" title="Adding Plugins" >additional plugins section</a> details the addition
|
||
of new plugins to nvf under regular circumstances, i.e. while making a pull
|
||
request to the project. You may <span class="emphasis"><em>override</em></span> those plugin inputs in your own
|
||
<code class="literal">flake.nix</code> to change source versions, e.g., to use newer versions of plugins
|
||
that are not yet updated in <span class="strong"><strong>nvf</strong></span>.</p><pre><code class="programlisting nix">{
|
||
|
||
inputs = {
|
||
# ...
|
||
|
||
# The name here is arbitrary, you can name it whatever.
|
||
# This will add a plugin input called "your-neodev-input"
|
||
# that you can reference in a `follows` line.
|
||
your-neodev-input = {
|
||
url = "github:folke/neodev.nvim";
|
||
flake = false;
|
||
};
|
||
|
||
nvf = {
|
||
url = "github:notashelf/nvf";
|
||
|
||
# The name of the input must match for the follows line
|
||
# plugin-neodev-nvim is what the input is called inside nvf
|
||
# so you must match the exact name here.
|
||
inputs.plugin-neodev-nvim.follows = "your-neodev-input";
|
||
};
|
||
# ...
|
||
};
|
||
}
|
||
</code></pre><p>This will override the source for the <code class="literal">neodev.nvim</code> plugin that is used in nvf
|
||
with your own input. You can update your new input via <code class="literal">nix flake update</code> or
|
||
more specifically <code class="literal">nix flake update <name of your input></code> to keep it up to date.</p><div class="warning"><h3 class="title">Warning</h3><p>While updating plugin inputs, make sure that any configuration that has been
|
||
deprecated in newer versions is changed in the plugin’s <code class="literal">setupOpts</code>. If you
|
||
depend on a new version, requesting a version bump in the issues section is a
|
||
more reliable option.</p></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">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 class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-dag-entries" class="title" >DAG entries in nvf </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-vim-luaconfigrc"><code class="literal">vim.luaConfigRC</code> (top-level DAG)</a> </span></dt> </dl></div><p>From the previous chapter, it should be clear that DAGs are useful, because you
|
||
can add code that relies on other code. However, if you don’t know what the
|
||
entries are called, it’s hard to do that, so here is a list of the internal
|
||
entries in nvf:</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="ch-vim-luaconfigrc" class="title" style="clear: both"><code class="literal">vim.luaConfigRC</code> (top-level DAG) </h2> </div> </div></div><div class="orderedlist"><ol class="orderedlist compact" type="1"><li class="listitem"><p>(<code class="literal">luaConfigPre</code>) - not a part of the actual DAG, instead, it’s simply
|
||
inserted before the rest of the DAG</p></li><li class="listitem"><p><code class="literal">globalsScript</code> - used to set globals defined in <code class="literal">vim.globals</code></p></li><li class="listitem"><p><code class="literal">basic</code> - used to set basic configuration options</p></li><li class="listitem"><p><code class="literal">optionsScript</code> - used to set options defined in <code class="literal">vim.o</code></p></li><li class="listitem"><p><code class="literal">theme</code> (this is simply placed before <code class="literal">pluginConfigs</code> and <code class="literal">lazyConfigs</code>,
|
||
meaning that surrounding entries don’t depend on it) - used to set up the
|
||
theme, which has to be done before other plugins</p></li><li class="listitem"><p><code class="literal">lazyConfigs</code> - <code class="literal">lz.n</code> and <code class="literal">lzn-auto-require</code> configs. If <code class="literal">vim.lazy.enable</code>
|
||
is false, this will contain each plugin’s config instead.</p></li><li class="listitem"><p><code class="literal">pluginConfigs</code> - the result of the nested <code class="literal">vim.pluginRC</code> (internal option,
|
||
see the <a class="link" href="/index.xhtml#ch-custom-plugins" target="_top">Custom Plugins</a> page for adding your
|
||
own plugins) DAG, used to set up internal plugins</p></li><li class="listitem"><p><code class="literal">extraPluginConfigs</code> - the result of <code class="literal">vim.extraPlugins</code>, which is not a
|
||
direct DAG, but is converted to, and resolved as one internally</p></li><li class="listitem"><p><code class="literal">mappings</code> - the result of <code class="literal">vim.maps</code></p></li></ol></div>
|
||
</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><dt> <span class="section"> <a href="index.xhtml#sec-lazy-plugins">Lazy plugins</a> </span></dt></dl></dd> </dl></div><p>nvf is designed for the developer as much as it is designed for the end-user. We
|
||
would like for any contributor to be able to propagate their changes, or add new
|
||
features to the project with minimum possible friction. As such, below are the
|
||
guides and guidelines written to streamline the contribution process and to
|
||
ensure that your valuable input integrates into nvf’s development as seamlessly
|
||
as possible without leaving any question marks in your head.</p><p>This section is directed mainly towards those who wish to contribute code into
|
||
the project. If you instead wish to report a bug, or discuss a potential new
|
||
feature implementation (which you do not wish to implement yourself) 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.</p><p>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. If you wish to make a contribution, but feel stuck -
|
||
please do not be afraid to submit a pull request, we will help you get it in.</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 most 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 fulfills 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><p>::: {.note} 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><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 grammars
|
||
</code></pre><p>Long description can be omitted 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 thoroughly. 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 possible.</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.keymaps</code>.</p><p>An example, simple keybinding, can look like this:</p><pre><code class="programlisting nix">{
|
||
vim.keymaps = [
|
||
{
|
||
key = "<leader>wq";
|
||
mode = ["n"];
|
||
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.keymaps" target="_top">documentation</a> to
|
||
see a list of them.</p><p><span class="strong"><strong>nvf</strong></span> provides a helper function, 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">mkKeymap</code>, which mimics neovim’s <code class="literal">vim.keymap.set</code> function</p></li></ul></div><p>You can read the source code of some modules to see them in action, but the
|
||
usage should look something like this:</p><pre><code class="programlisting nix"># plugindefinition.nix
|
||
{lib, ...}: let
|
||
inherit (lib.options) mkEnableOption;
|
||
inherit (lib.nvim.binds) mkMappingOption;
|
||
in {
|
||
options.vim.plugin = {
|
||
enable = mkEnableOption "Enable plugin";
|
||
|
||
# Mappings should always be inside an attrset called mappings
|
||
mappings = {
|
||
workspaceDiagnostics = mkMappingOption "Workspace diagnostics [trouble]" "<leader>lwd";
|
||
documentDiagnostics = mkMappingOption "Document diagnostics [trouble]" "<leader>ld";
|
||
lspReferences = mkMappingOption "LSP References [trouble]" "<leader>lr";
|
||
quickfix = mkMappingOption "QuickFix [trouble]" "<leader>xq";
|
||
locList = mkMappingOption "LOCList [trouble]" "<leader>xl";
|
||
symbols = mkMappingOption "Symbols [trouble]" "<leader>xs";
|
||
};
|
||
}
|
||
</code></pre><pre><code class="programlisting nix"># config.nix
|
||
{
|
||
config,
|
||
lib,
|
||
options,
|
||
...
|
||
}: let
|
||
inherit (lib.modules) mkIf;
|
||
inherit (lib.nvim.binds) mkKeymap;
|
||
|
||
cfg = config.vim.plugin;
|
||
|
||
keys = cfg.mappings;
|
||
inherit (options.vim.lsp.trouble) mappings;
|
||
in {
|
||
config = mkIf cfg.enable {
|
||
vim.keymaps = [
|
||
(mkKeymap "n" keys.workspaceDiagnostics "<cmd>Trouble toggle diagnostics<CR>" {desc = mappings.workspaceDiagnostics.description;})
|
||
(mkKeymap "n" keys.documentDiagnostics "<cmd>Trouble toggle diagnostics filter.buf=0<CR>" {desc = mappings.documentDiagnostics.description;})
|
||
(mkKeymap "n" keys.lspReferences "<cmd>Trouble toggle lsp_references<CR>" {desc = mappings.lspReferences.description;})
|
||
(mkKeymap "n" keys.quickfix "<cmd>Trouble toggle quickfix<CR>" {desc = mappings.quickfix.description;})
|
||
(mkKeymap "n" keys.locList "<cmd>Trouble toggle loclist<CR>" {desc = mappings.locList.description;})
|
||
(mkKeymap "n" keys.symbols "<cmd>Trouble toggle symbols<CR>" {desc = mappings.symbols.description;})
|
||
];
|
||
};
|
||
}
|
||
</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><dt> <span class="section"> <a href="index.xhtml#sec-lazy-plugins">Lazy plugins</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>Prepending <code class="literal">plugin-</code> to the name of the input will allow nvf to automatically
|
||
discover inputs that are marked as plugins, and make them available in
|
||
<code class="literal">vim.startPlugins</code> or other areas that require a very specific plugin type as it
|
||
is defined in <code class="literal">https://github.com/notashelf/nvf/blob/v0.8/lib/types/plugins.nix</code></p><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 class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-lazy-plugins" class="title" style="clear: both">Lazy plugins </h2> </div> </div></div><p>If the plugin can be lazy-loaded, <code class="literal">vim.lazy.plugins</code> should be used to add it.
|
||
Lazy plugins are managed by <code class="literal">lz.n</code>.</p><pre><code class="programlisting nix"># in modules/.../your-plugin/config.nix
|
||
{lib, config, ...}:
|
||
let
|
||
cfg = config.vim.your-plugin;
|
||
in {
|
||
vim.lazy.plugins.your-plugin = {
|
||
# instead of vim.startPlugins, use this:
|
||
package = "your-plugin";
|
||
|
||
# if your plugin uses the `require('your-plugin').setup{...}` pattern
|
||
setupModule = "your-plugin";
|
||
inherit (cfg) setupOpts;
|
||
|
||
# events that trigger this plugin to be loaded
|
||
event = ["DirChanged"];
|
||
cmd = ["YourPluginCommand"];
|
||
|
||
# keymaps
|
||
keys = [
|
||
# we'll cover this in detail in the keymaps section
|
||
{
|
||
key = "<leader>d";
|
||
mode = "n";
|
||
action = ":YourPluginCommand";
|
||
}
|
||
];
|
||
};
|
||
;
|
||
}
|
||
</code></pre><p>This results in the following lua code:</p><pre><code class="programlisting lua">require('lz.n').load({
|
||
{
|
||
"name-of-your-plugin",
|
||
after = function()
|
||
require('your-plugin').setup({--[[ your setupOpts ]]})
|
||
end,
|
||
|
||
event = {"DirChanged"},
|
||
cmd = {"YourPluginCommand"},
|
||
keys = {
|
||
{"<leader>d", ":YourPluginCommand", mode = {"n"}},
|
||
},
|
||
}
|
||
})
|
||
</code></pre><p>A full list of options can be found
|
||
[here](https://notashelf.github.io/nvf/options.html#opt-vim.lazy.plugins</p>
|
||
</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="quirks.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. Known Issues and Quirks</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html> |