5 years ago, I migrated my VPS from Arch Linux to NixOS.

I had no conception what I became once doing. I had in no diagram passe Nix sooner than. I opinion I’d also figure it out.

5 years later, I’m mild working NixOS. And I mild have not any conception the diagram it works.

Nix is notoriously arduous to tag.¹ Why is that? I don’t know the authorized answer, but I do know why it became once arduous for me: the quantity of indirection. I don’t indicate symlinks; I indicate the disconnect between “what you like to carry out” and “how Nix in fact does it.” Any individual can philosophize “exercise nix-env -i to set up packages,” but in say to make exercise of Nix successfully, you surely desire a succesful unbiased appropriate realizing of what that verbalize does.

Why? If all you like to carry out is set up git with Nix or whatever, then obvious, you don’t if truth be told wish to know the relaxation about Nix. nix-env -i git, appropriate? Unsuitable. I indicate, you may maybe presumably also carry out that. But you in fact are wanting to squawk nix-env -iA nixpkgs.git. Why? Don’t apprehension about it.

But clearly you’re going to apprehension about it. You’re straight away puzzled and upset and odd what the distinction is between those instructions. And in say to tag why you like to make exercise of this most total verbalize, you without observe deserve to study moderately loads about Nix and the expression language and the directory construction that nix-env expects and the diagram channels work and also you detect your self without observe staring at this abrupt complexity explosion that you were utterly no longer searching at for.

So that you end the exercise of Nix. Or you precise memorize the “appropriate capability to carry out it,” and while you form it, a section of you wonders why, till within the extinguish your mind crystallizes round this conception that Nix is confusing and odd and too arduous so that you can figure out.

Now not lower than, that is what I bear in mind from my time making an strive NixOS: heaps of excessive-level abstractions performed on prime of very low-level primitives. It became once easy to regurgitate instructions without realizing them, but any time I wished to carry out something without a detailed tutorial of easy easy recommendations to carry out precisely that thing, I became once utterly misplaced. I felt like a vacationer wandering round Paris with nothing but a phrasebook, desperately making an strive to search out a lavatory.

So I made up my mind to study some French.

I gave Nix one other strive no longer too long ago, and I took a extraordinarily plenty of tack than my first foray 5 years ago. I read the handbook, intimately.² I ran every verbalize. I attempted to tag no longer precise what the instructions “carry out,” but what they carry out: the recordsdata and directories and concrete operations.

And I took notes.

This started as precise a capability to motivate myself: I wrote down questions after I didn’t understand issues, so I wouldn’t forget to come relieve relieve to them later. I wrote down issues that I realized, for the reason that act of writing something down helps me to commit it to memory. I wrote down the capability that I felt as I went via the handbook, because it’s if truth be told easy for frustration to present capability to embarrassment while you tag your “glaring” errors.

At this time after I started doing this, I noticed something: my notes may maybe presumably also compose for a if truth be told dull sequence of blog posts.

Or if truth be told, a extraordinarily niche sequence. Because I form of had an viewers in mind: whatever nameless saint is available, toiling away free of fee, making an strive to compose Nix more approachable for mere mortals.

Despite its repute as hard and even “elitist,” there are other folks that care moderately loads about making Nix more approachable: they’ve written long, thorough manuals; they’ve made a engaging web site, whole with tremendous minute tutorials. Most visibly, maybe, they designed a original nix verbalize-line interface for the initiate of Nix 2.0, so it’s seemingly you’ll form nix search as an replacement of nix-env -qa (for instance).

And wouldn’t or no longer it be tremendous for them – I opinion – if some rando came along and started yelling his opinions about the Nix documentation on the Web? Wouldn’t they precise deal with that? It may maybe per chance presumably be the whole fun of any individual doing an unsolicited code review of one of your GitHub repos, but with the added subjectivity of English prose and pedagogic theory.

I youngster, but finest rather. I acknowledge that no-one asked me to study Nix, and I surely acknowledge that no-one owes me the relaxation. I did this, first and indispensable, because I found it fun. I love to study issues, and I love to jot down. If any individual who contributes to Nix ever in fact sees these blog posts, I’m hoping that they steal them for what they’re: a odd more or less user acceptance take a look at. Now not demands or complaints, precise the epic of one particular person’s experience.

“Now, Ian,” I hear you judge, “while you detect a yell with the documentation, or something you judge will most definitely be clearer, why don’t you precise fix it? It’s begin source, finally.”

First off I are wanting to thanks for bringing that up; that’s a extraordinarily unbiased appropriate point. My answer is 2-fold: (1) I don’t know how, and (2) I may maybe presumably no longer are wanting to by the point I carry out.

To clarify: maybe within the future I may be that Nix contributor. But I will’t be, appropriate now. I don’t know easy easy recommendations to tag Nix! I barely understand it myself. By the point I carry out understand it properly ample, I doubtlessly can like forgotten the whole lot that puzzled me about it within the first build, and I won’t be in a situation to jot down the relaxation focused at newbies. I’ll scrutinize at statements like this (from man nix-env --set up):

By default, args is a assortment of derivation names denoting derivations within the stuffed with life Nix expression. These are realised, and the ensuing output paths are set aside in.

And nod my head wisely. “Crystal distinct,” I’ll philosophize to myself. “Nothing to alternate there.”

However the 2d point is, I specialize in, more likely. I may maybe presumably in no diagram change into that particular person. I may maybe presumably quit. I may maybe presumably opt that Nix isn’t any longer for me, thanks very noteworthy, and bound on to every other gleaming thing. It takes me moderately plenty of dedication to beat the social apprehension of “getting fascinated a pair of neighborhood,” and there’s a official likelihood that I may maybe presumably no longer ever earn there.

So I’m writing this, in a capability, for 2 of us: the hypothetical future Ian that loves Nix and desires to spend plenty of time and vitality making its documentation an even bigger build, and desires a official reminder of what he found confusing all those years ago. But additionally for any individual else: any individual who in fact exists, and who may maybe presumably even be already within the Nix IRC, who stumbles all the diagram via these dusty posts within the future and finds them edifying.

So. What follows may be a exact, appropriate memoir of my experience making an strive to study Nix (again). I will carry out heaps of boring issues, and I will compose heaps of cross assumptions. And it’s seemingly you’ll also earn to spy it all, in excruciating part.

Angry? How may maybe presumably also you no longer be. A series of blog posts about any individual you’ve in no diagram met reading a handbook about an imprecise fragment of know-how you’ve barely heard of? It doesn’t earn considerably higher than that.