A variety of people have written similar documents to the one you’re planning They’re generally on github, but usually on the topic of NixOS rather than mac OS, so that should be interesting.
I think the problem is more the distributed nature of all this documentation. For the average person, if it’s not on stackoverflow, it may as well not exist, and this is doubly so if even I can’t point you at prior art.
That said, these are the reference works I consider most important to have a thorough understanding of if you want to learn nix related things:
-
NixOS 23.11 manual | Nix & NixOS
- The configuration syntax primer. Nix is a programming language, sure, but if you stick to only configuration you can get away with only knowing these basics.
-
NixOS Search
- This is your replacement for the arch wiki on nixos. If a pre-made option doesn’t exist, and just installing the packages into
environment.systemPackages
doesn’t work, consider yourself in uncharted territory. Especially if you’re following installation docs from a project upstream instead of using options or a package.
-
https://nix-community.github.io/home-manager/options.html
- Your replacement for the above when using home manager.
Those are the basics. I believe them to be quite easy to follow even for not very advanced users, assuming you have some prior experience with unix systems. After all, you really can just copy paste stuff as log as you stick to options only (and slowly learn the nix syntax while you do so).
It does, however, limit you to only those things already perfectly prepared to run on NixOS, and you’ll very quickly run into that one thing you can’t do this way. Especially if you’re a developer yourself, since you won’t be able to make your own code work with this. Many people give up at this point, since “ubuntu is so much easier” (ignoring the fact that it is only so because upstream projects are designed to work with ubuntu first and foremost for obvious historical reasons, making ubuntu arguably even harder in the reverse world), and that’s where all the hate articles and claims of difficulty come from
This is where the learning curve does get a bit steep, because you actually need to learn how to package software, what building software even means, and understand the quirks and features of nix and the NixOS distro (yes, even when you’re on mac OS. I’d say especially when you’re on mac OS). If you don’t know what a systemd is you’ll get lost pretty quickly. Either way, this is when you start pulling out these things:
-
Nixpkgs 23.11 manual | Nix & NixOS
- Especially the sectons on the “standard environment” and “builders”. This goes beyond basics, but if you were unhappy about being restricted to what’s in nixpkgs, this is what you need to learn.
-
https://nixos.org/manual/nix/stable/expressions/writing-nix-expressions.html
- Yes, there are three official manuals. This one covers the actual syntax in detail, because by the time you start packaging you need to understand it.
-
Nix Pills | Nix & NixOS
- Parts of this are very technical. Parts of it explain in excruciating detail how stuff works that you should never use in this form. Only read this after you’ve written at least one or two packages using the stdenv, but once you have, this will explain everything, and suddenly nix will make sense. Read the whole thing, this is not a good document to skim. It’s like an updated, simpler version of eelco’s thesis.
-
https://nix.dev/
- Very good reference for a lot of the more advanced topics, and has my favorite listing of nix antipatterns.
-
https://xeiaso.net/blog
- If you like learning from blogs, xe is probably the best nix related blogger out there.
But yes, this gets pretty messy. You might notice that the “intermediate” documentation is a little missing. You might also notice that it’s spread out, in the form of references rather than howtos, and finding an answer to “how do I change the firefox version I’m using” is hard.
This is where the nix documentation is sadly lacking, and while lots of people write blog posts and github gists and such, it’s hard to coordinate this effort. Ultimately a lot of it ends up here on the discourse, in answers by the very people who maintain nixpkgs (and occasionally yours truly), but obviously it’s borderline impossible to index and search here.
Tweag has recently announced they will be writing a nix “book” akin to the rust one, so I’m hopeful the situation will improve
My final note is that https://nix.dev/ is probably worth a look either way. It’s a good place for documentation efforts that aren’t references, but it’s naturally become more “advanced” than what I think is required.