mkTarget: add config and extraConfig options

[trueNAHO]

Here are two proposals for introducing options.stylix.targets.${name}.config and options.stylix.targets.${name}.extraConfig options to mkTarget. Note that the option names are subject to change.

IMHO, I am against the options.stylix.targets.${name}.config option due to imposed complexity on end-users:

Would it be desirable to generally expose every target's configuration?

I don't think so; I can't think of a use case. These specific examples are solutions to somewhat uncommon problems, and they require a specific subset of the target's config output, rather than the whole thing.

-- @Flameopathic, #1502 (comment)

The options.stylix.targets.${name}.config proposal is mostly only included in this discussion for reference.

The options.stylix.targets.${name}.extraConfig option seems like an uncontroversial addition, since it allows extending the Stylix default declarations under the stylix namespace, while leveraging mkTarget's automatic safeguarding.

options.stylix.targets.${name}.config

Would it be desirable to generally expose every target's configuration? In that case, mkTarget would generate the option with a consistent description. Unsure whether the configuration should be declared in the option as:

options.stylix.targets.${name}.config = lib.mkOption {
  default = /* configuration */;
  readOnly = true;
};

config = config.stylix.targets.${name}.config;

or in the configuration as:

options.stylix.targets.${name}.config = lib.mkOption {
  readOnly = true;
};

config.stylix.targets.${name}.config = /* configuration */;

-- #1502 (review)

This would generally solve the inconsistency of using the Stylix default declarations as a foundation.

This also enables a complementary use case to overriding individual declarations with lib.mkForce, where the entire target can be disabled using stylix.targets."<TARGET>".enable = false; and only desired sections are included. When only a small portion of declarations is undesired, lib.mkForce is the most convenient. When the majority is undesired, disabling the target and reusing only selected parts is more effective.

Considering mkTarget's automatic safeguarding, this may lead to end-users partially re-implementing this safeguarding. To avoid encouraging complexity on end-users, I suggest abandoning this general options.stylix.targets.${name}.config option.

options.stylix.targets.${name}.extraConfig

On a side note, once the mkTarget migration is complete, we could trivially allow end-users to extend mkTarget's configElements:

options.stylix.targets.${name}.extraConfig = lib.mkOption {
  type = /* mkTarget's configElements */;
  description = /* Provide a link to mkTarget's source code documentation */;
  default = [];
};

config = lib.mkIf (config.stylix.enable && cfg.enable) (
  lib.mkMerge (
    lib.optional (generalConfig != null) (mkConfig generalConfig)
    ++ map mkConditionalConfig (
      (lib.toList configElements) ++ (lib.toList cfg.extraConfig)
    )
  )
);

This would allow grouping styling-related declarations under the stylix namespace:

stylix = {
  enable = true;

  targets."<TARGET>".extraConfig =
    { colors }:
    { programs."<TARGET>".settings.background = lib.mkForce colors.base01; };
};

-- #1502 (review)

Unlike the previous options.stylix.targets.${name}.config proposal, this would simply extend the Stylix declarations.

Context

For reference, here is some additional context:

I do question what makes these modules any different than Firefox and VSCode. For that reason, I'm not sure if I would say that this is a full formalization, as these targets need their configurations manually merged while Firefox and VSCode use an option to decide the attribute paths.

There's nothing fundamentally different - I think it's just that these modules are very old and haven't had a lot of attention since. It should be possible to make these modules work the way Firefox and VSCode do, or the other way around, to settle on a standard.

Alright. In that case, I think that this NixVim option is still necessary because its use is slightly different than the others, but all of the other targets should be set up like VSCode and Firefox.

The NixVim config is exposed to support the standalone use case:

commit 0a4755b656c28043c52063384fc68bbb30913903
Author: Matt Sturgeon [...]
Date:   2024-06-05 03:10:32 +0100

    nixvim: expose config as read-only option

    Allow standalone nixvim users to take advantage of stylix by exposing
    the generated config as `config.lib.stylix.nixvim.config`.

    This can be passed to the nixvim derivation's `extend` function or used
    directly in a nixvim configuration.

The other modules touched in this PR expose sensible theming declarations to allow end-users to build upon them to write their own configuration. This pattern is inconsistent with declaring a sensible default configuration without any real customizing capabilities (aside from simply overriding it with [lib.mkForce]), as used in /modules/plymouth/theme-script.nix and potentially other (pending?) modules.

Should these declaration expositions and default configurations be handled differently or not? The /modules/plymouth/theme-script.nix case is inherently hard to generally extend to same extent the exposed Nix attribute sets are.

-- #1502 (comment)

---

CC: @awwpotato, @danth, @Flameopathic

[Flameopathic]

options.stylix.targets.${name}.config

Considering mkTarget's automatic safeguarding, this may lead to end-users partially re-implementing this safeguarding. To avoid encouraging complexity on end-users, I suggest abandoning this general options.stylix.targets.${name}.config option.

I agree. This seems too seldomly useful and too confusing to new users.

options.stylix.targets.${name}.extraConfig

The options.stylix.targets.${name}.extraConfig option seems like an uncontroversial addition, since it allows extending the Stylix default declarations under the stylix namespace, while leveraging mkTarget's automatic safeguarding.
Unlike the previous options.stylix.targets.${name}.config proposal, this would simply extend the Stylix declarations.

I am not vehemently opposed, but I don't see a use case for this. mkTarget's guards are designed to allow targets to support a wide array of configurations, and the only way I can imagine this being useful to a single user is if they have several Stylix configurations with different options set which they switch between regularly, and they want to use them in a non-standard way.

If we do add this, we will want to document it well, but also make sure that it doesn't become more static in the documentation for the average user to filter out.