Proposed article: Nix ecosystem installation methods

[Dioprz]

Observations

Hello everyone.

For a couple of months now I've had an idea that I want to discuss and get to work on as soon as possible (in case we agree, of course).

The idea is based on the fact that one of the central ideas around our systems is the notion of installing packages. Nix (using it as a broad term that embraces its entire ecosystem) is possibly the most versatile and capable tool to perform this operation. The problem? It is extraordinarily overwhelming to be a novice and not be able to understand its diversity and complexity. I don't think it's uncommon for the flow for someone new (as it was for me), to be something like:

1. seeing that the installation manual suggests using nix-env for querying and installing packages (Wasn't Nix declarative?)

2. Find a guide on how the decalarative part of Nix works. Start configuring the default.nix through an esoteric section where apparently if you type the name of a package inside the expression

environment.systemPackages = with pkgs; [
  <your package here!!>
]

and after launching a command your computer automatically installs it. (But be careful, because if you try to install a package that you have already installed in step 1, you may have a bad time.)

3. You realize that all your programs are being installed as superuser. You wonder about that awesome feature you read on reddit about being able to install things in your profile and without sudo, until you find home-manager (...is there also a home-manager-env -p 'hello'?).

4. You go to one of the 100 unofficial (but possibly less intimidating) guides on how to install in your profile, and you notice how difficult it is to complement information between them because the commands do not correspond (will a command with the --flake flag be the same as without it? And, why they use nix-build there and nix build on the other side)?

5. ...

6. ...

7. ... I think you get my point.

Approaches

We need the documentation to be atomic, but also to connect concepts, and I think one aspect that is worth threading some of the material with is precisely the fundamental notion of installing packages.

That said, the proposal is to open a new entry:Nix ecosystem installation methods.

The structure and content of it we can discuss, but I had thought that its structure and content may contain the following:

1. Brief introduction to package management and 'classic' (i.e., imperative) package handling
2. Explain that Nix despite being an intentionally declarative package manager, has the ability to be handled imperatively.
3. List all the installation methods/commands that can be used to create a Nix installation. It could be convenient to do it in a table and assign to each one its labels/categories, something like: ephemeral/persistent, global/user/local, exclusiveNixOS/non-exclusiveNixOS etc.
4. Give an EXPLANATION for each. This will allow to better absorb the concept and through examples show their usefulness in order to understand when each one is used. At the end we could also indicate the reference documentation and related articles (if any).
5. (OPTIONAL) A brief and short digression on the related chronology (in this item I am thinking in particular of mentioning why there are hyphenated and non-hyphenated variations in some of the stated commands, but I don't know if there are any other events that would be relevant to include).
6. (OPTIONAL) If prudent, we can also indicate good practices for a beginner (preferably at the beginning of the article, not at the end).

Additional considerations

1. Explanation type documentation is abstract and complex in their bounds, but I think the ecosystem is mature enough and has enough scattered unofficial guides to extract and collect valuable information from Discourse, forums, guides and blogs.

2. Naturally the idea is to preserve the Nix.dev philosophy. No sophisticated examples will be given and no sophisticated functionality will be referenced. "The goal will be to cover in breadth, not depth."

3. The work will probably be very extensive, so if anyone wants to join, you are more than welcome!

4. (The name is horrible. It would be greatly appreciated if anyone recommends a better name!)

That will be all. I look forward to your comments, and thank you for taking the time to read.

Priorities

Add 👍 to issues you find important.

[henrik-ch]

Thank you for your contribution, @wisehh. I particularly appreciate the first point regarding a brief introduction. It can reduce the initial hurdles and provide a shared understanding before delving into the complexities of Nix.

[fricklerhandwerk]

I strongly agree with the premise, it's a well-known problem. I suggest to break this down into smaller chunks though, and start with what's easiest to do.

I think the first thing we have to address is that the Nix manual suggests nix-env as first interactions, and NixOS/nix#7769 is there to stop that. We already quite clearly agreed that nix-shell is a much better beginner use case, and that the reference manual should not be responsible to guide users at all.

The second step would be adding "mitigation" against ubiquitous third-party documentation suggesting the use of nix-env by providing an FAQ answer along the lines of the article linked here: #17 (but dispassionately since this is official documentation)

Other than that I agree on the general strategy. I suggest not to invest too much time breaking it down right now though, and finish the work started first. Would be great if you could help with that.

[Dioprz]

Thanks @henrik-ch and @fricklerhandwerk for the comments.

@henrik-ch I find your approach very interesting as I had proposed it more for thematic introduction than for creating prerequisites, but it certainly can be very useful for that purpose.

On the other hand, I was not aware of that work @fricklerhandwerk , and I find it excellent to start cleaning up the documentation. I'm already reading both sources, and will notify on each respective issue when I start working on a task so we don't waste time. (I warn that it may take me a while to get started because I have a very complicated month coming up, but I'll try to get started as soon as possible!)

Let's leave this one on the future action plan and get to work on what is already underway!