Nixpkgs: newbie help/documentation: what to do when switching to the unstable channel in nixos?

[vitiral]

This is mostly a bit of newbie confusion, hopefully this report can be used to improve the guides as well.

The NixOS manual for upgrading states that you should use nix-channel --add {channel} nixos followed by nixos-rebuild switch --upgrade, which works _great_. It later states in the next sub-section that you should use system.autoUpgrade.channel = {channel}; and system.autoUpgrade.enable = true;

Here are my problems:

• I don't want to depend on a command for specifying my channel -- I want to do it the "nix way" and specify it in my configuration.nix. It is not obvious how to do this if I don't want autoUpgrade (see below).
• I would like to use unstable but _not_ use autoUpgrade. How do I do so? Do I set system.stateVersion = "unstable"? Can I specify a "specific date" for unstable?
• using nix-channel --add did _not_ change my system.stateVersion. Even worse, that statement has warnings in the automatically generated configuration.nix telling you not to change it until you are told to do so... but I was never told to do so. When/how should I change it for this case?
• If I _were_ interested in autoUpgrade = true should I _delete_ system.stateVersion when I use autoUpgrade? What should be done? it is not clear how these configs interact.
• How do I specify my channels as unstable "the nix way"? I would really like to avoid using nix-channel --add at all if possible and set the channels in configuration.nix.

Thanks!

[jtojnar]

1. autoUpgrade is optional, you do not really need it to use unstable. See manual for what it does:
   > If enabled, a systemd timer will run nixos-rebuild switch --upgrade once a day.

2. stateVersion is again independent. And again, manual will explain:

   Every once in a while, a new NixOS release may change configuration defaults in a way incompatible with stateful data. For instance, if the default version of PostgreSQL changes, the new version will probably be unable to read your existing databases. To prevent such breakage, you can set the value of this option to the NixOS release with which you want to be compatible. The effect is that NixOS will option defaults corresponding to the specified release (such as using an older version of PostgreSQL).

   Latest released stable release is probably a good candidate, if you use unstable you will encounter changes like https://github.com/NixOS/nixpkgs/pull/25931 occasionally.

3. nix-channel simply takes care of channels, it will not update you configuration. It is release notes that would tell you to change it

4. Hopefully it is now clear what each setting does.

5. nixos channel needs to be available before evaluation (they are used for modules) for that reason, you cannot just declare them in the configuration.nix (well you can set { nix.nixPath = [ "nixpkgs=foo" ]; } but the changes are stored to nix.conf on rebuild so they will only be available on the next rebuild). If you want to manage the channel manually, usually you clone the https://github.com/NixOS/nixpkgs-channels repo and set the nixpkgs to path to the clone.

Ad 5: You can actually use use the channel declaratively inside configuration.nix but only for referring to packages, not as a base channel for modules (unless you want to run switch twice):

let
  unstable =
    let
      cloned = pkgs.fetchFromGitHub {
        owner = "NixOS";
        repo  = "nixpkgs-channels";
        rev = "5402412b97247bcc0d2b693e159d55d114d1327b";
        sha256 = "03qx3iqj58ciwhh8yj44x05558yssiyrzk6ks9cr9807b72v4srp";
      };
    in import cloned { };
in {
  environment.systemPackages = [
    unstable.firefox
  ];
}

[vitiral]

Okay, so there is no way around using nix-channel (except the rebuild-twice solution you mention) except a local git repo, which honestly sounds reasonable to me. Can that option be added to the guide to be more clear?

Thanks for the clarification on autoUpgrade and stateVersion. It is _crazy awesome_ to me that stateVersion allows you to use _unstable packages_ but simultaneously _preserve stable "configuration defaults"_. That is super cool. However, searching through the current manual I can't find your quote :frowning:

Regardless, can that information be placed more front-and-center in upgrading? Thanks a ton!

[jtojnar]

Okay, so there is no way around using nix-channel (except the rebuild-twice solution you mention) except a local git repo, which honestly sounds reasonable to me.

Well, you can also set the NIX_PATH ad-hoc, using -I flags, so you could have completely declarative system configuration with channel commit stored in a script and using that script exclusively:

#!/bin/sh

# Go to https://howoldis.herokuapp.com/ for obtaining a fresh commit in a channel
HASH="c2fbd472a4ebaae739257a3df93aef25f19dd04f"
nixos-rebuild -I nixos-config=configuration.nix -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/$HASH.tar.gz "$@"

Then you would call sudo ./nixos-rebuild switch. Updating a channel would mean changing the hash. Then you would not need nix-channel at all.

However, searching through the current manual I can't find your quote :frowning:

It is in man configuration.nix (https://nixos.org/nixos/manual/options.html).

Regardless, can that information be placed more front-and-center in upgrading?

I do not see stateVersion in the manual so I would keep the description to options chapter. Maybe add something like the following to the generated configuration.nix:

For more informations about the options listed below, see man configuration.nix or https://nixos.org/nixos/manual/options.html

[vitiral]

Maybe add something like the following to the generated configuration.nix: ...

:+1:

I like that because it also documents the discover-ability of configuration options.

[jtojnar]

Hmm, it looks like it already does:

https://github.com/NixOS/nixpkgs/blob/7d37688d66bf830767ae39724406abd78347fcfb/nixos/modules/installer/tools/nixos-generate-config.pl#L555-L556

[vitiral]

Maybe refer to Appendix A, Configuration Options specifically? "See the manpage" or "see the manual" are so broad -- those are both basically _entire books_ :smile:

[jtojnar]

Wiki actually has a nice example How to fetch Nixpkgs with an empty NIX_PATH

[FRidh]

Have you check pure evaluation mode?
https://github.com/NixOS/nix/commit/d4dcffd64349bb52ad5f1b184bee5cc7c2be73b4
I don't think it can be used yet for building a NixOS installation but work is going in that direction.