nix documentation, especially on flakes, absolutely sucks

like sorry but when I look up nix flakes, I should NOT be given a nix.dev page that contains the history of which RFC it’s defined in and which talk the concept came from; I wanna know how to actually use them

There is this high-ranking YouTube video (here) from 2 whole years ago where the beginning of the video talks about how, yes, you cannot find ANY information on how to use them or what they actually are; that seemingly still holds true today

the only distinct thing I know of and understand is that they have a lockfile to lock versions in place.

nobody wants to write documentation

but without documentation nobody except those that were around at the thing’s inception will want to use it, because they don’t even understand it

@alexia

nobody wants to write documentation

it’s not even that. it’s worse.

it’s because they’re still marked as “experimental”, and therefore “the official documentation for nixpkgs and NixOS is de facto not allowed to talk about flakes”

@sodiboo @alexia I’ve never used flakes what do they get me over npins (see https://github.com/easrng/nix-config)

@sodiboo ah, I will murder someone now I think.

how the FUCK is anyone supposed to figure it out then??? read the RFC? watch the original talk? pour HOURS into STUDYING other people’s flakes?????????

why can’t the docs just be versioned? have an experimental section??
and if they’re not allowed to mention it, why is there sections for the nix flake subcommand?????????

@alexia

how the FUCK is anyone supposed to figure it out then??? […] pour HOURS into STUDYING other people’s flakes?????????

i think so? that’s what i did. i didn’t read the RFC and i don’t remember if i watched the talk; but “studying other people’s code” is unfortunately quite a necessary skill in Nix.
this also isn’t exclusive to flakes; but applies to everything. on the bright side, this means that by the time you’re proficient at using Nix for managing an operating system, you will also have mastered the Nix language along the way.

why can’t the docs just be versioned? have an experimental section??

i mean they sorta are. look:

https://nixos.org/manual/nixos/stable/
https://nixos.org/manual/nixos/unstable/

it’s just that. all the docs related to NixOS and Nixpkgs are versioned after… the Nixpkgs release cycle. and this has nothing to do with the Nix language.

Nixpkgs has a flake entrypoint, but it’s just one of several entrypoints. the bulk of the Nixpkgs repository is self-contained and depends only on stable Nix features. Nixpkgs itself doesn’t “use” flakes and as such NixOS isn’t allowed to enable them by default; so all the official documentation about things you normally do with the Nix language (i.e. documentation surrounding Nixpkgs because 99% of Nix code is consuming Nixpkgs), only talks about the default ways to do things (which aren’t flakes).

if they’re not allowed to mention it, why is there sections for the nix flake subcommand?????????

well, it’s not an actual policy that “We shall NEVER document what flakes are”. it’s a consequence of how Nixpkgs and NixOS are versioned and their stability guarantees. also, this de-facto policy does not apply to the Nix language and build system, which are developed separately. (package repo and operating system are in NixOS/nixpkgs, build system and language interpreter are in NixOS/nix). it does document its experimental commands, but it’s just for the command line interface and not the concept as a whole.

the closest thing to cohesive first-party documentation about flakes is on the official NixOS wiki. but discoverability on this is. uh. Not Great. and it’s also not like the holy grail of documentation? it focuses way too much on how the Nix CLI deals with flakes and the holy structure as specified in the RFC. i certainly didn’t read that wiki page and come out with a perfect understanding of everything.

@em @sodiboo @alexia they get you:

• a (somewhat) standardized schema for exposing nix code
• dependency management/locking (but npins/niv already does that)
• pure-eval by default (actually genuinely nice tbh but there’s been virtually zero effort into making it usable without flakes)

those are the main ones i can think of. only pure-eval is worth using flakes for, but imo everything else about them is annoying enough that it’s just not worth it

@srxl @sodiboo @em

are those docs you linked down

@alexia @sodiboo @em shouldn’t be, link works fine on my end

@srxl @sodiboo @em awesome, I blame Vodafone then

@sodiboo

i think so? that’s what i did. i didn’t read the RFC and i don’t remember if i watched the talk; but “studying other people’s code” is unfortunately quite a necessary skill in Nix.

my ADHD ass does NOT have the spoons for this ;w;

@alexia

the only distinct thing I know of and understand is that they have a lockfile to lock versions in place.

it’s worth noting that, this is like, basically all flakes are?

no, really. a “flake” is a file that uses a subset of Nix syntax, where you define some inputs (including overriding the inputs of inputs), and has an attribute called outputs which contains a function that gets passed the stuff defined in inputs, and somewhere in that process there is a lockfile involved.

outputs is just a function that returns some Nix value.

there is a lot of tooling that expects the returned value to follow a particular schema. for instance nixos-rebuild on a computer named twinkpad will want the flake outputs to have an attribute named nixosConfigurations.twinkpad.config.system.build.toplevel, and that particular attribute will be a derivation that can be built, and it’ll want the result to have a particular shape.

likewise, nix fmt will expect there to be an attribute named formatters.x86_64-linux.

or nix run .#hello will expect there to be an attribute named apps.x86_64-linux.hello, packages.x86_64-linux.hello, legacyPackages.x86_64-linux.hello, or hello.

but if you don’t use these tools, then the conventions they follow don’t matter. they’re just conventions. not any intrinsic part of what flakes are.

the thing with the inputs and the lockfiles though? that’s actually the thing that makes flakes, flakes.

flakes, inherently, as a primitive, don’t actually care about NixOS or Nix packages or derivations. that is what flakes are mostly used for, and the tooling certainly has strong opinions about using them in this particular way. but flakes themselves really are just all about that lockfile and absolutely nothing else.

@sodiboo i appreciate the time you spent writing this but unfortunately this does not actually help me that much in getting literally anything working

@alexia wanna tell me more about the specific issues you’re running into and what you’re actually trying to do?

# if you check the git blame for this you'll notice that I have no idea what this does because it's not my code :)

this is the vibe that my flake currently has.

Anyways, here is my flake: https://forge.starlightnet.work/alexia/nxconf

things I wanted to do, but couldn’t due to lack of documentation:

• use the kbct package that someone made for me, instead of hacking something in using nix-ld
• use the Niri flake (it’s even in the inputs still)

those are the only things I can think of off the top of my head, I have not figured them out

anyways the point of this whole thread is to beg for help on making it work and make even a tiny bit of sense

@sodiboo as much as i respect the work you put into writing up the documentation, in terms of energy I am far past the point where and overview of what they’re supposed to be is getting me anywhere

optimally I just skip straight to “this is how you actually make use of the thing you’re trying to use from your inputs without it telling you it doesn’t exist”

@alexia my flake is worse: https://git.gay/mir/nixos

@mir i am not trying to compete on who has the worse flake I am trying to make it work ;w;

@alexia

use the Niri flake (it’s even in the inputs still) <small>(specifically: I wanted niri unstable)</small>

here’s the shortest path to that:

diff --git a/desktop/niri.nix b/desktop/niri.nix
index d5b7566..2ea92b9 100644
--- a/desktop/niri.nix
+++ b/desktop/niri.nix
@@ -1,8 +1,10 @@
-{ niri, pkgs, config, lib, ... }: 
+{ inputs, pkgs, config, lib, ... }:
 
 {
+  nixpkgs.overlays = [ inputs.niri.overlays.niri ];
   programs.niri = {
     enable = true;
+    package = pkgs.niri-unstable;
   };
   environment.variables.NIXOS_OZONE_WL = "1";
   environment.systemPackages = with pkgs; [

the above will not install a binary cache; meaning that niri-unstable may take a while to build.

be aware that by trusting my binary cache you trust me not to upload malware there.

here’s how to also enable my binary cache:

diff --git a/desktop/niri.nix b/desktop/niri.nix
index d5b7566..681e47a 100644
--- a/desktop/niri.nix
+++ b/desktop/niri.nix
@@ -1,8 +1,15 @@
-{ niri, pkgs, config, lib, ... }: 
+{ inputs, pkgs, config, lib, ... }:
 
 {
+  nix.settings = {
+    substituters = [ "https://niri.cachix.org" ];
+    trusted-public-keys = [ "niri.cachix.org-1:Wv0OmO7PsuocRKzfDoJ3mulSl7Z6oezYhGhR+3W2964=" ];
+  };
+
+  nixpkgs.overlays = [ inputs.niri.overlays.niri ];
   programs.niri = {
     enable = true;
+    package = pkgs.niri-unstable;
   };
   environment.variables.NIXOS_OZONE_WL = "1";
   environment.systemPackages = with pkgs; [

the binary cache is also included in the NixOS module i provide, but if you only want the latest version of the niri package and don’t care about anything else my flake does, you shouldn’t be using the module i provide; it’s subtly different from the nixpkgs one.

@alexia

use the kbct package that someone made for me, instead of hacking something in using nix-ld

i see you have a flake package output at the top level, but you don’t really need flakes for that. you can add it from the package set already present in your NixOS configuration.

here’s a way to do that:

diff --git a/desktop/packages.nix b/desktop/packages.nix
index e9904bf..edb3868 100644
--- a/desktop/packages.nix
+++ b/desktop/packages.nix
@@ -1,7 +1,13 @@
 { config, lib, pkgs, ... }:
 
 {
+   nixpkgs.overlays = [
+       (prev: final: {
+           kbct = final.callPackage ../packages/kbct {};
+       })
+   ];
    environment.systemPackages = with pkgs; [
+       kbct
        signal-desktop
        dino
    ];

overlays are nice because they make the package available under pkgs throughout your whole config. you don’t have to use them. callPackage is just a function. you can use it directly:

diff --git a/desktop/packages.nix b/desktop/packages.nix
index e9904bf..bc47494 100644
--- a/desktop/packages.nix
+++ b/desktop/packages.nix
@@ -1,7 +1,11 @@
 { config, lib, pkgs, ... }:
 
+let
+  kbct = pkgs.callPackage ../packages/kbct {};
+in
 {
    environment.systemPackages = with pkgs; [
+       kbct
        signal-desktop
        dino
    ];

and, mica was trying to poke at using the flake output you already have. that works too. here’s the shortest way to do that:

diff --git a/desktop/packages.nix b/desktop/packages.nix
index e9904bf..353d97e 100644
--- a/desktop/packages.nix
+++ b/desktop/packages.nix
@@ -1,7 +1,8 @@
-{ config, lib, pkgs, ... }:
+{ inputs, config, lib, pkgs, ... }:
 
 {
    environment.systemPackages = with pkgs; [
+       inputs.self.packages.x86_64-linux.kbct
        signal-desktop
        dino
    ];

@alexia

use the kbct package that someone made for me

in flake.nix you can pass self in specialArgs and then you can reference it in your config like so:

{ self, ... }:

{
    environment.systemPackages = [ self.packages.x86_64-linux.kbct ];
}

@alexia so basically you would modify the specialArgs line like that:

specialArgs = {inherit inputs self;};

@alexia eep sorry i wasn’t entirely clear ><

yeah you have to add this bit to a module, like desktop/fixkbd.nix adding self to the first line and adding the environment.systemPackages line somewhere between the main curly braces

@alexia oh and i guess maybe the kbct stuff would go in fixkbd.nix instead of packages.nix. organize it however you want.

@alexia

service could look something like that:

diff --git a/desktop/fixkbd.nix b/desktop/fixkbd.nix
index 77f7866..9ab9fef 100644
--- a/desktop/fixkbd.nix
+++ b/desktop/fixkbd.nix
@@ -11,7 +11,7 @@
    systemd.services."kbct" = {
      script = ''
        set -eu
-       /home/alexia/.local/bin/kbct remap --config /etc/kbct.yaml
+       ${lib.getExe pkgs.kbct} remap --config /etc/kbct.yaml
      '';
      serviceConfig = {
        Type = "simple";

adjust pkgs.kbct as necessary if you didn’t use an overlay.

@sodiboo

@mir @alexia behold: hell. over 5000 lines of nix code with bespoke abstractions and mechanisms

no docs and i don’t have the spoons to finish the blog post series about it

https://github.com/micaplush/x

@mica @mir @alexia behold: similar hell just a bit more homegrown.

https://github.com/sodiboo/system

or as i like to call it, “six configurations that are actually one configuration wearing a trenchcoat pretending to be four configurations”. they are interlinked and my eval times are Actually Hellish. it takes 69 seconds of waiting before it starts building stuff. every. single. time.

@sodiboo @mir @mica 69. nice.

@alexia @mir @mica actually i just checked and 69 was to eval all systems, not just one. but also, evaling one system evals all of them, so the difference is kinda negligible.

@alexia and im explaining why i didn’t have anything to offer

@mir I guess…

@sodiboo @mir @alexia @mica mine has an IFD every single time

which depends on such tiny packages like haskell

@sodiboo @alexia @mica @mir my installer got to be the most complex one though, because it’s actually 4 nixos configs in one

@sodiboo @alexia same although on a mac it’s somehow a lot more bearable (but the build takes longer bc remote builders are required for everything but the nix-darwin config)

@alexia @mica @mir @sodiboo please actually send help it’s like 75GB in size

https://hydra.chir.rs/build/297624#tabs-details

@charlotte @mir @sodiboo @mica what the fuck.

@alexia @mir @sodiboo @mica on the upside i only evaluate my nix config on one device (the pc that i use for evals)

@charlotte @mir @alexia @mica i am clearly a rookie. my total NixOS system closure is only 27.7 GiB.

@sodiboo @mir @alexia @mica my pc’s system closure is 48GB

@charlotte @mir @alexia @mica my PC’s closure is 24.3 GiB

@alexia you can have a look at my flake if you need any help :3

https://git.gay/lighty/nixos

@Lilith I shall study everyone’s nix flakes that have been submitted, thank you

@Lilith <small>(also I heard that you find my flake horrifying, which is fair, but also to be expected with the state of documentation and how everyone does things slightly differently and then some flakes have zero docs on how to use them that I could go off of and– it’s just bleh and the brainfog does not help)</small>