Nixpkgs: {standard, lib, doc}: What the hell is happening with `priority` properties

[Anton-Latukha]

Describe the bug

_(in the hall of opera many things placed and lay in its wast space, couple of people appear)_

• _(the scholar says)_ ... So, we have:
  https://github.com/NixOS/nix/blob/84de8210040580ce7189332b43038d52c56a9689/doc/manual/command-ref/nix-env.xml#L337-L344

_(scholar continues)_ ... so default priority for things is 0, and values of priorities are inverse to the level of priority. So we use reverse logic and for us 0 > 100, I got accustomed to seeing such things, especially in medieval period.

• _(the knowledgeable person)_ But also remember that:

https://github.com/NixOS/nixpkgs/blob/a7bf8161fa834a602278c15fcbdd955656b3aed8/lib/modules.nix#L519

for less default settings, they have priority 1000. Ok?

• But, wait _(says Deus ex machina from the cloud appeared from the nowhere in the middle of the room near them)_:

https://github.com/NixOS/nixpkgs/blob/a7bf8161fa834a602278c15fcbdd955656b3aed8/lib/modules.nix#L535-L536

_(and Deus ex machina quickly changes all things to have the default priority of 100)._

• But, wait. _(says scholar to disappearing Deus ex machina)_:
  https://github.com/NixOS/nixpkgs/blob/a7bf8161fa834a602278c15fcbdd955656b3aed8/doc/meta.xml#L203
  ... 10 is said to be a low priority, while it is higher priority to 100, (since 10 > 100 - please remember that). What should we do!?

• Do nothing!, I only appeared to change all things, and not to do documentations in manual _(says Deus ex machina disappearing)_

• _(scolar & the knowledgeable people)_ Well, anyway. What we do now?

_... (silence is being silent in the air)_

_(sudden roar & rushing from the darkness of the balcony of the 2nd tier)_

• Nobody expects the Spanish Inquisition! All priorities now are always ignored by decree https://github.com/NixOS/nixpkgs/issues/7425 & and at the same time by the buildEnv all your default priorities are long ago should be 5 - deal with that: https://github.com/NixOS/nixpkgs/blob/a7bf8161fa834a602278c15fcbdd955656b3aed8/pkgs/build-support/buildenv/default.nix#L53-L71

[Anton-Latukha]

_(Now! Somebody!, - please save the people from the Spanish Inquisition!)_

[Anton-Latukha]

... also the scholar does not know if initial default is 0 - are priorities are positive integers or not? He does not know - he says everyone should try them-selfves, is that is true.

But some lonely knowledgeable person by the candle somewhere knows that they can be negative, because there is only 4 rare packages in NixPkgs that:

pkgs> rg 'priority = -'

pkgs/tools/security/gnupg/1compat.nix
28:    priority = -1;

pkgs/os-specific/linux/rtlwifi_new/default.nix
38:    priority = -1;

pkgs/os-specific/linux/tbs/default.nix
60:    priority = -1;

pkgs/development/interpreters/python/cpython/2.7/default.nix
291:      priority = -100;

[Anton-Latukha]

The continuation would be:

Separate priority defaults for options, that are for some reason not higher, but lower then the all other defaults. And mkVMOverride that is higher priority then mkForce, but still not high enough then nix-env default or the negative priority values.

https://github.com/NixOS/nixpkgs/blob/6d2e24e80e8a0cc5318bc93d5c6b565008aea245/lib/modules.nix#L518-L521

Since all these are different values - they obviously overlap somewhere in sets.

And since there is not much explanation.
I imagine and seems - things are going like this: nix-env introduced the 0, and for possibility to some override through nix-env - it is kept as such, and all other priories are lower. Then buildEnv was introduced, with 5 (remember - possibility nix-env override). Then for the reason for build-vm, probably a build server, others (mostly used in QEMU), goes in mkVMOverride 10, that is probably also why mkForce lower, so VM overrides would work. I remember such discussion years ago.

Why mkOptionDefault is smaller priority then normal defaults or mkDefault?
Probably https://github.com/NixOS/nixpkgs/commit/0e333688cea468a28516bf6935648c03ed62a7bb
by deductive reasoning deriving that mkOptionDefault played the role in the laziness of undeclared options - the main usage is in the modules also:
https://github.com/NixOS/nixpkgs/blob/6d2e24e80e8a0cc5318bc93d5c6b565008aea245/lib/modules.nix#L310-L317
It was 1001 at first but was lowered to 1500 by https://github.com/NixOS/nixpkgs/pull/42138 to squeeze in hardware overrides between mkDefault and mkOptionDefault.

So - mkOptionDefault 1500 is sort of - the rock bottom - for default values in options. When person sets value - it becomes ... well wait - we will see... mkOptionDefault is used automatically (everywhere implicitly) and explicitly almost nowhere explicitly - & because of the name users&contributors can confuse it with the default priority for all option values, as I just confused before drilling hard.

Also person that lowered mkOptionDefault the meaning of the other option/priority - mkDefault. mkDefault also is not the admin domain, it is used to set default distro env values.

The admin-set option, as everything written by admin without overrides in configuration, becomes defaultPriority - 100.
This is first introduction of defaultPriority
https://github.com/NixOS/nixpkgs/blob/b81b3ad1b052aeb2edcf493167df7348b7bfb293/lib/modules.nix#L430-L454
From that time - everything user sets moved from priority 5 to 100.

The good news is - the system, despite our efforts, still holds water. What we need to do - is to document things better - at first.

[stale[bot]]

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.