nix-doc VS flake-utils

I love nix, I've been using it for the last 2 years, I have a very stable setup from these 2 years of effort [0], and I just can't recommend Nix for Linux beginners, why?

It's not because of the nix language, It's not because of the CLI, it's because everything is scattered, you have to consult many places to find out how to do things with Nix, here is an example:

Usually, when I need a new complex program, like Steam, I first check the system-wide configuration [1], the wiki [2] and the package list [3], if I just want it on my user, I need to check if Home Manager has an option [4], if it doesn't, I can try using the "home.packages" option. Now, if I need to override something on the package, I need to remember how to do it with [5] [6] (while checking the source code for the package in parallel to find the options).

And then sometimes, on very rare occasions, I need to fine tune something with the nix language, so I need to check the builtins/lib docs [7], but some builtins are not there, so I need to either use nix-doc [8] or find the docs inside the code-bases [9] [10] (they are split between both repos)

For me, this is one of the main pain points of using Nix / NixOS that needs to be solved.

[0] - https://github.com/shiryel/nixos-dotfiles

[1] - https://search.nixos.org/options

[2] - https://nixos.wiki/wiki/Steam

[3] - https://search.nixos.org/packages

[4] - https://mipmip.github.io/home-manager-option-search/

[5] - https://nixos.org/manual/nixos/stable/#sec-customising-packa...

[6] - https://nixos.org/guides/nix-pills/nixpkgs-overriding-packag...

[7] - https://teu5us.github.io/nix-lib.html

[8] - https://github.com/lf-/nix-doc

[9] - https://github.com/NixOS/nix

[10] - https://github.com/NixOS/nixpkgs

The ‘flake-utils’ readme is a pretty good jumping off point: https://github.com/numtide/flake-utils

I have this or that nitpick with FL and FLP but overall it’s very solid stuff. FLP is a little more “magical”, and that’s not always the best starting out, but you really can’t go wrong with either.

We added two inputs, the first is nixpkgs which lets us specify which version of nixpkgs we should use. There are many thousands of packages in the nixpkg repository, and they are updated often so here will use the unstable branch. We also added flake-utils which helps us generalize the flake to support multiple systems, not just Linux.

The inputs is how you can import external sources of other flakes into the flake project you have. In other words, any project you may need or tools required to get started, this is where you will define their source. Example below is using the standard nixpkgs and a tool called flake-utils, which provides a set of functions to make flake nix packages simpler to set up without external dependencies.

I'm not sure what nix-shell --pure does, but is it equivalent to using a flakes.nix in your projects? Ie i use https://github.com/numtide/flake-utils and direnv to replicate the old shell.nix with a Flakes setup. Per project i have a flakes.nix and a flakes.lock, so it feels just like my old shell.nix setup, but using flakes instead.

A Nix Flake is just an object - check out those surrounding curly braces. This object has two keys, inputs and outputs. The inputs are where we define the flake's dependencies and where to find all the tools we use. This one has two, nixpkgs and flake-utils. Each of these just points to a GitHub URL, and if you follow those links, you'll see each repo provides its own flake.nix. The outputs of each remote flake get piped into the inputs of my flake, so we can use what they provide.

You can easily transition your shell.nix (and default.nix) to a flake-based one by using flake-utils and flake-compat. The former is actually unnecessary, but I would recommend it for typical project environments. Unless you have an impure dependency, this transition would be easy.

Flakes can provide different types of things: - some flakes provide applications that you can nix run, - some flakes provide functions that you can import (e.g. https://github.com/numtide/flake-utils), - some flakes provide overlays to use with nixpkgs (e.g. that emacs-overlay you posted).