New reader finding documentation unnecessarily confusing

[fricklerhandwerk]

Hi @gdennie and thanks for your feedback!

@gdennie

following the completion of the “hello.nix” packaging tutorial I did not “see” a package

What exactly do you mean by that? As described in the note on what we mean by “package”, the expression in hello.nix is the package (recipe).

@gdennie

I suppose the directory tree of ./result/ may constitute the package though I did not expect a directory tree.

Indeed, it’s also the package (artifact). Admittedly the terminology is not great. @tomberek proposed uniformly calling the expression a recipe in his 2024 FOSDEM talk, and I agree with that, but doing this consistently will be quite an undertaking. Why did you not expect it to be a directory tree? Maybe we can improve the introductory note to reduce the surprise.

@gdennie

Specifically, instead of one nix file there were two, default.nix and hello.nix

@gdennie

In particular, the use of -A hello made no sense at this point since default.nix already refers to hello.nix.

Well, yes, there’s this cumbersome aspect about Nixpkgs conventions, but the reasons for separating recipe expressions from their collections are not that arbitrary: it simply helps with organising code. We decided to follow Nixpkgs conventions because that’s what allows you a somewhat seamless ramp-up to upstream your own packages eventually. There are a few (not necessarily exclusive) alternatives:

• Stuff everything into one Nix file that only returns the derivation

  This could potentially be better for a tutorial, because it involves fewer steps. But it doesn’t allow adding a second package, as we do in the very next section. You’d have to do a bit of refactoring then, which means unproductive, cognitively taxing steps in a learning situation that already binds most available attention.

• Don’t introduce an additional file and run nix-build -E 'with import <nixpkgs> {}; callPackage ./hello.nix {}'

  This is a common pattern for doing things quickly, and definitely worth mentioning at some point, but not necessarily here. It has two downsides: It’s a cumbersome invocation, and you’ll almost certainly have to download all dependencies again once you pin Nixpkgs in a file.

• Make a separate tutorial just for hello and start from scratch for the next thing.

  But eventually we’ll have to introduce the callPackage pattern anyway. In any case, having smaller tutorials is probably better.

• Explain in more detail why we’re doing it this way.

  This is not necessarily the job for tutorials, but could be done in a lightweight way here. Splitting things up into smaller chunks would also decrease the cost of adding even more information to a single tutorial.

• Reorganise the introduction around using nix-init.

  That may get people started a lot faster, but it also introduces yet another layer of magic, which defies a lot of the purpose of skill-building with the tutorials. I think we should strive get learners operational quickly, but also equip them with an understanding of what’s actually happening on the way, as far as possible.

@gdennie how did you perceive it? What would have helped you to avoid confusion?