Project description

Option declarations are currently of a fairly closed form, as we can't add arbitrary metadata to them.
This could provide an avenue for both implementing features externally when they are not desirable or controversial in NixOS itself, e.g.

• Advanced options #257300

... and this could also allow currently "core" features such as internal or visible to be moved out of the hot path, improving performance. Crucially, for the performance improvement to work, config must never evaluate opt.meta, based solely on the module system itself. (Modules such as documentation.nix will evaluate them, and that's ok.)

Proposal:

1. Add a meta field to mkOption
2. Expose meta in the evaluated options
3. Add meta = throw "module evaluation must be lazy in meta"; in a number of tests
4. Migrate visible and internal (and more?) into meta`
   1. Make the mkOption parameters write to both meta and the option attrset
   2. Wait (1) is available in all supported releases
   3. Warn when legacy arguments are passed to mkOption, and warn when legacy option attrs are used
   4. Wait one release
   5. Turn the warnings into errors.
   6. Wait one release
   7. Remove the legacy attrs
   8. Performance will improve

Note that after (2), applications can already start using this for their own purposes.

Example:

lib.mkOption {
  type = ...;
  description = ...; # technically meta, but we might want to keep this here for historic consistency and convenience
  meta = {
    visible = "shallow";
    internal = true;
    # implementation-specific attrs
    advanced = true;  # possible emerging standard among some applications
    arion-docker-compose-equivalent = "entrypoint";  # something I'm making up, but is relevant to the arion application (not actually the motivation for this proposal)
  };
}

I've chosen meta in my examples, although meta in packages is closed, unlike this proposal which is open.
That might be a reason to pick labels instead? I'm undecided.

I'd be happy to implement this without moving anything, but candidates for moving are:

• description
• defaultText
• example
• relatedPackages
• internal
• visible

Add a 👍 reaction to issues you find important.