Manual Ch. 6 Package management ambiguous examples

[AMDphreak]

Issue description

Nixos declarative package management has zero explanation for why trying to install a package using nixos.packagename causes an error:

This example code in the manual:

$ nix-env -qaP '*' --description
nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
...

has this note under it, which is misleading:

(The nixos prefix allows distinguishing between different channels that you might have.)

I took this advice and applied it directly to my declarations in a separate .nix file, since I am subscribed to the nixos stable channel:

{ config, pkgs, ... }:

{
  environment.systemPackages = [
    nixos.firefox
  ];
}

however, nixos.firefox causes an error (whereas pkgs.firefox does not):

# nixos-rebuild build
building Nix...
building the system configuration...
error: attribute 'nixos' missing, at /nix/var/nix/profiles/per-user/root/channels/nixos/lib/modules.nix:163:28

1. What does nixos.packagename require in order to be valid syntax? When would I use this?

To add to the confusion, https://nixos.wiki/wiki/Cheatsheet contains examples (shown below) that are inconsistent with Ch. 6.

Cheatsheet:

systemPackages = with pkgs;
                    [ <other packages...> emacs ];

It is not apparent to the reader that the writer excluded the required environment = { line before the systemPackages line. To make this even more confusing, the systemPackages statement uses a with pkgs statement, which has zero explanation.

2. Make the required environment = block apparent and make the examples consistent for the sake of the reader.
3. What is the purpose of the with statement in this context?

Proposal: add answers for these questions to the manual.

[FRidh]

Knowledge of the Nix language is a prerequisite for being able to understand and write Nix expressions found in the NixOS manual.

[jtojnar]

As Frederik says, you really need to understand Nix syntax before trying to tackle anything using it.

Most importantly is the fact that there are no free variables – you can only access the variables that are defined using let expression inside the body after in, or function arguments inside the function body, or attributes of a record inside the body of with expression.

{ config, pkgs, ... }:

{
  environment.systemPackages = [
    nixos.firefox
  ];
}

As you can see, there is no with expression, nor is there a let binding, nor is there a nixos among the function arguments, therefore the name/attribute/variable is missing:

error: attribute 'nixos' missing, at /nix/var/nix/profiles/per-user/root/channels/nixos/lib/modules.nix:163:28

---

The nixos. prefix in the nix-env output is only relevant to nix-env (imperative package management). Personally, I would just remove the nix-env mention from declarative section and direct users to list of packages.

1. What does nixos.packagename require in order to be valid syntax? When would I use this?

It refers to the fact that packagename attribute is part of pkgs in a channel named nixos. Conveniently, the pkgs argument passed to the NixOS configuration also commonly points to the pkgs attribute in nixos channel so you can access the package through pkgs.packagename in the configuration expression. Note that the channels hide a lot of magic and this might not be true in a general case (e.g. if you change the NIX_PATH or pass -I arguments to nixos-rebuild).

It is not apparent to the reader that the writer excluded the required environment = { line before the systemPackages line. To make this even more confusing, the systemPackages statement uses a with pkgs statement, which has zero explanation.

This can be assumed from context (there is only single systemPackages attribute) but for clarity it should probably contain the environment parent. with is again part of Nix syntax and user should be familiar with it. pkgs is expected to be passed to nixos-configuration as an argument, yet another idiom.

[danbst]

@AMDphreak thanks, fixed wiki! Also made environment.systemPackages usages consistent.

[stale]

Thank you for your contributions.

This has been automatically marked as stale because it has had no activity for 180 days.

If this is still important to you, we ask that you leave a comment below. Your comment can be as simple as "still important to me". This lets people see that at least one person still cares about this. Someone will have to do this at most twice a year if there is no other activity.

Here are suggestions that might help resolve this more quickly:

1. Search for maintainers and people that previously touched the related code and @ mention them in a comment.
2. Ask on the NixOS Discourse.
3. Ask on the #nixos channel on irc.freenode.net.

[jtojnar]

Fixed in #57617