Document policy on config options

[abbradar]

I remember seeing mentions several times on policy of avoiding new config options (I can't remember where exactly), especially ones that affect only one package. Asked in https://github.com/NixOS/nixpkgs/pull/12339/files#r50638513, I couldn't remember any exact place where it's documented and couldn't find any reference in Nixpkgs manual. So -- what's our policy on adding new config options, and why?

Two main cases of those options:

1. Affecting only one package. Example of such existing option: https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix#L12666
2. Affecting multiple packages. One good example would be config.pulseaudio. Example of usage: https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix#L12691

[peti]

There has never been an explicit consensus reached on the extend to which we want config used or not.

My understanding is that config should be used for things that cannot easily be done with override, i.e. config.pulseaudio is probably fine because that setting affects many other packages in ways that would be hard to configure otherwise.

The mpv example you cited, however, is a case where use of config feels inappropriate because the exact same thing can be accomplished with overrides.

[abbradar]

FWIW my own thoughts are exactly the same, i.e. we already have various flags in packages themselves which can be set by override, and if this can be done with just that there's no need for an additional config option.

On the other hand an argument for more mass usage is pointed out by @a1russell at https://github.com/NixOS/nixpkgs/pull/12339/files#discussion_r50638513. It comes down to config options being easier to find, because of lines like withX = config.foo.withX or true. I can see advantages of that (though arguably the core problem there is lack of tooling to browse package options conveniently),

cc @edolstra as the project man-in-charge ~_^

[vcunat]

You can make standard options "discoverable" in the exactly same way by explicitly passing the default value in all-packages.nix. Personally I don't feel strongly about this. So far the options in general have interface more for nixpkgs "developers" than for nixpkgs "users".

[Profpatsch]

Using nixpkgs config is akin to introducing global variables (set by an env variable), which is very bad in my opinion, because it destroys reproducability.

The user can already override whatever he wants with packageOverrides, in a general manner. Config affecting a huge number of packages (e.g. compiling with and without pulseaudio support) might be a different matter.

[joelmo]

I have suggested this #16531 which would apply the module system to make it easier to document, discover and type check options in nixpkgs config.

[Profpatsch]

In #16531 we basically came to the conclusion that the config should go into a nixuser layer.

I propose we do add documentation, in the vein of: “Using nixpkgs config to modify package behaviour is discouraged, explicit overrides of packages should be preferred. For user configuration a yet to be written nixuser layer would be used.”

[Profpatsch]

(triage) With the new overlay methods, is this still a valid problem?