diff --git a/docs/manual/installation/modules/flakes.md b/docs/manual/installation/modules/flakes.md new file mode 100644 index 00000000..273d2b00 --- /dev/null +++ b/docs/manual/installation/modules/flakes.md @@ -0,0 +1,33 @@ +### Prerequisites {#sec-flakes-prerequisites} + +To install nvf with flakes, you must make sure the following requirements are +met. + +1. Nix 2.4 or later must be installed. You may use `nix-shell` to get a later + version of Nix from nixpkgs. +2. Flake-related experimental features must be enabled. Namely, you need + `nix-command` and `flakes`. Some Nix vendors enable those by default, please + consult their documentation if you are not using mainstream Nix. + - When using NixOS, add the following to your `configuration.nix` and rebuild + your system. + + ```nix + nix.settings.experimental-features = "nix-command flakes"; + ``` + + - If you are not using NixOS, add the following to `nix.conf` (located at + `~/.config/nix/` or `/etc/nix/nix.conf`). + + ```bash + experimental-features = nix-command flakes + ``` + + - You may need to restart the Nix daemon with, for example, + `sudo systemctl restart nix-daemon.service`. + + - Alternatively, you can enable flakes on a per-command basis with the + following additional flags to `nix` and `home-manager`: + + ```sh + $ nix --extra-experimental-features "nix-command flakes" + ``` diff --git a/docs/manual/installation/modules/home-manager.md b/docs/manual/installation/modules/home-manager.md index 2b359af5..37d35e2b 100644 --- a/docs/manual/installation/modules/home-manager.md +++ b/docs/manual/installation/modules/home-manager.md @@ -5,9 +5,18 @@ inside the home-manager configuration without having to call for the wrapper yourself. It is the recommended way to use **nvf** alongside the NixOS module depending on your needs. -To use it, we first add the input flake. +## With Flakes {#sec-hm-flakes} + +```{=include=} +flakes.md +``` + +### Usage {#sec-hm-flakes-usage} + +To use **nvf** with flakes, we first need to add the input to our `flake.nix`. ```nix +# flake.nix { inputs = { # Optional, if you intend to follow nvf's obsidian-nvim input @@ -16,7 +25,7 @@ To use it, we first add the input flake. # Required, nvf works best and only directly supports flakes nvf = { - url = "github:notashelf/nvf"; + url = "github:NotAShelf/nvf"; # You can override the input nixpkgs to follow your system's # instance of nixpkgs. This is safe to do as nvf does not depend # on a binary cache. @@ -25,6 +34,8 @@ To use it, we first add the input flake. # for example: inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- this will use the obsidian-nvim from your inputs }; + + # ... }; } ``` @@ -39,7 +50,7 @@ Followed by importing the home-manager module somewhere in your configuration. } ``` -## Example Installation {#sec-example-installation-hm} +### Example Installation {#sec-example-installation-hm} ```nix { @@ -66,7 +77,8 @@ Once the module is properly imported by your host, you will be able to use the `programs.nvf` module option anywhere in your configuration in order to configure **nvf**. -```nix{ +```nix +{ programs.nvf = { enable = true; # your settings need to go into the settings attribute set @@ -89,3 +101,45 @@ installation sections of the manual. You may find all available options in the [appendix](https://notashelf.github.io/nvf/options) ::: + +## Without Flakes {#sec-hm-flakeless} + +As of v0.8, it is possible to install **nvf** on a system if you are not using +flakes. This is possible thanks to the flake-compat project. + +To get started, you must fetch the repository using `builtins.fetchTarball` or a +similar mechanism. + +```nix +# home.nix +let + nvf = import (builtins.fetchTarball { + url = "https://github.com/notashelf/nvf/archive/.tar.gz"; + # Optionally, you can add 'sha256' for verification and caching + # sha256 = ""; + }); +in { + imports = [ + # Import the NixOS module from your fetched input + nvf.homeManagerModules.nvf + ]; + + # Once the module is imported, you may use `programs.nvf` as exposed by the + # NixOS module. + programs.nvf.enable = true; +} +``` + +[npins]: https://github.com/andir/npins +[niv]: https://github.com/nmattia/niv + +::: {.tip} + +Nix2 does not have a builtin lockfile mechanism like flakes. As such you must +manually update the URL and hash for your input. This is annoying to deal with, +and most users choose to defer this task to projects such as [npins] or [niv]. +If you are new to NixOS, I encourage you to look into Flakes and see if they fit +your use case. Alternatively, look into the aforementioned projects for more +convenient dependency management mechanisms. + +::: diff --git a/docs/manual/installation/modules/nixos.md b/docs/manual/installation/modules/nixos.md index bcf7472b..946905c1 100644 --- a/docs/manual/installation/modules/nixos.md +++ b/docs/manual/installation/modules/nixos.md @@ -5,9 +5,18 @@ the NixOS configuration without having to call for the wrapper yourself. It is the recommended way to use **nvf** alongside the home-manager module depending on your needs. -To use it, we first add the input flake. +## With Flakes {#sec-nixos-flakes} + +```{=include=} +flakes.md +``` + +### Usage {#sec-nixos-flakes-usage} + +To use **nvf** with flakes, we first need to add the input to our `flake.nix`. ```nix +# flake.nix { inputs = { # Optional, if you intend to follow nvf's obsidian-nvim input @@ -16,7 +25,7 @@ To use it, we first add the input flake. # Required, nvf works best and only directly supports flakes nvf = { - url = "github:notashelf/nvf"; + url = "github:NotAShelf/nvf"; # You can override the input nixpkgs to follow your system's # instance of nixpkgs. This is safe to do as nvf does not depend # on a binary cache. @@ -25,6 +34,8 @@ To use it, we first add the input flake. # for example: inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- this will use the obsidian-nvim from your inputs }; + + # ... }; } ``` @@ -39,7 +50,7 @@ Followed by importing the NixOS module somewhere in your configuration. } ``` -## Example Installation {#sec-example-installation-nixos} +### Example Installation {#sec-example-installation-nixos} ```nix { @@ -64,10 +75,12 @@ Once the module is properly imported by your host, you will be able to use the `programs.nvf` module option anywhere in your configuration in order to configure **nvf**. -```nix{ +```nix +{ programs.nvf = { enable = true; - # your settings need to go into the settings attribute set + + # Your settings need to go into the settings attribute set # most settings are documented in the appendix settings = { vim.viAlias = false; @@ -87,3 +100,45 @@ installation sections of the manual. You may find all available options in the [appendix](https://notashelf.github.io/nvf/options) ::: + +## Without Flakes {#sec-nixos-flakeless} + +As of v0.8, it is possible to install **nvf** on a system if you are not using +flakes. This is possible thanks to the flake-compat project. + +To get started, you must fetch the repository using `builtins.fetchTarball` or a +similar mechanism. + +```nix +# configuration.nix +let + nvf = import (builtins.fetchTarball { + url = "https://github.com/notashelf/nvf/archive/.tar.gz"; + # Optionally, you can add 'sha256' for verification and caching + # sha256 = ""; + }); +in { + imports = [ + # Import the NixOS module from your fetched input + nvf.nixosModules.nvf + ]; + + # Once the module is imported, you may use `programs.nvf` as exposed by the + # NixOS module. + programs.nvf.enable = true; +} +``` + +[npins]: https://github.com/andir/npins +[niv]: https://github.com/nmattia/niv + +::: {.tip} + +Nix2 does not have a builtin lockfile mechanism like flakes. As such you must +manually update the URL and hash for your input. This is annoying to deal with, +and most users choose to defer this task to projects such as [npins] or [niv]. +If you are new to NixOS, I encourage you to look into Flakes and see if they fit +your use case. Alternatively, look into the aforementioned projects for more +convenient dependency management mechanisms. + +::: diff --git a/docs/manual/try-it-out.md b/docs/manual/try-it-out.md index 5f326b15..a5d20363 100644 --- a/docs/manual/try-it-out.md +++ b/docs/manual/try-it-out.md @@ -5,19 +5,20 @@ 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: -- **Nix** - Nix language server + simple utility plugins -- **Maximal** - Variable language servers + utility and decorative plugins +- **Nix** (`packages.nix`) - Nix language server + simple utility plugins +- **Maximal** (`packages.maximal`) - Variable language servers + utility and + decorative plugins You may try out any of the provided configurations using the `nix run` command on a system where Nix is installed. -```bash +```sh $ cachix use nvf # Optional: it'll save you CPU resources and time -$ nix run github:notashelf/nvf#nix # will run the default minimal configuration +$ nix run github:notashelf/nvf#nix # Will run the default minimal configuration ``` -Do keep in mind that this is **susceptible to garbage collection** meaning it -will be removed from your Nix store once you garbage collect. +Do keep in mind that this is **susceptible to garbage collection** meaning that +the built outputs will be removed from your Nix store once you garbage collect. ## Using Prebuilt Configs {#sec-using-prebuilt-configs} @@ -65,6 +66,7 @@ companion or fun plugins. ::: {.warning} Running the maximal config will download _a lot_ of packages as it is -downloading language servers, formatters, and more. +downloading language servers, formatters, and more. If CPU time and bandwidth +are concerns, please use the default package instead. :::