Adoption by the Hyprland + Nix community

This issue was originally a comment on hyprwm/hyprland-wiki#273. The text is unedited, except to fix the links. If the context seems off, that's because it is.

Greetings to all who come across this issue. I'm writing this to open a discussion about proceeding with migration of users to one of the new Hyprland Home-Manager modules.

To bring any readers up to speed, there are currently three HM modules for Hyprland:

The official flake's nix/hm-module.nix (by @fufexan)
The one in HM added recently via #3837 (by @fufexan)
And my own (by @spikespaz)

A tale of fragmentation

To summarize the differences between the three:

The one in the official flake does little more than basic configuration. It handles the package to use (Git master by default), systemd integration, package options (xwayland, patches, and HiDPI), and plugin dynamically-linked libraries. It has no mechanism for generation of the config file ($XDG_CONFIG_HOME/hypr/hyprland.conf) and that file must either be manually created or linked in via the HM option xdg.configFile."hypr/hyprland.conf".source.
The module by @fufexan in Home Manager uses the package in nixpkgs-unstable by default unless overridden in the HM input's follows or with the package option. It expands upon (and changes some) features of the original Flake's module. Specifically, it add a the options settings and extraConfig to allow you to declaratively define your Hyprland config; this uses a simple function to stringify the Nix config as hyprland.conf. The Nix config might look something like this and the generated hyprland.conf looks like this. This module started out with significant issues, especially with ordering. Some things like variables and beziers must be defined before they are used (fixed in #4263). There are more caveats that are handled in the following module.
My module, ~~which is currently a subtree of my dotfiles~~. This is by far the most complete of the three modules, and provides (in my opinion) a very nice API for users to declare their Hyprland config entirely in Nix syntax without excessive interpolation and merging. The goal is to allow everything to be defined in Nix in a way that feels natural. More on this later.

Module `#3`'s adoption as official

In the past, @fufexan reached out to me to ask if my module could be adopted into the Hyprland flake to publicize it as official. I responded that I did not yet consider it to be ready for public adoption, as I acknowledged it is incomplete. I would consider it to be a prototype, albeit a fully functional one. After describing these issues, @fufexan concluded that it was "quite complex", and implied that a project of this intricacy is out of scope for the purposes of a sanctioned, official, module (I expect to be corrected). For this reason, I encouraged him to wait, and to instead test the module and provide feedback. Regardless of these issues, my module is by far the most feature-complete of the three. Because the scope of my project is wide, and I am ready and willing to accept the responsibility of maintainership, it would be a worthwhile effort to seek compromise.

My project is designed to be robust, extensible, and therefore future-proof as long as the current config format exists.

Problems with my module:

Lacking documentation, only a few examples (config.nix, monitors.nix keybinds.nix, and windowrules.nix).
- I say this, but I did a good job with most of the the option docs. If only the task below were easy--
No statically generated module option documentation (potentially use rycee/nmd).
Missing type definitions, specifically for option keyBinds (uses attrsOf anything, should be a recursive submodule instead).
Unreasonable error reporting (if you get something wrong, you get a nonsensical Nix trace) for anything that isn't strictly defined (would be mitigated by solving the above issue).
Some internal functions could be simpler/optimized/eliminated.
- However: the problem is inherently complicated. Details later.
The internal intermediate representation (essentially a node tree) is ill-defined. Currently it feels like a prototype (which it is).
- Perhaps nodes should contain certain tokens, instead of every noun being a node.
Lackluster formatting options (related to #3), currently requires understanding the internals to configure (especially sorting, which is delicate and necessary).
Superfluous options (this is a point of contention, I want to keep--but possibly hide--the formatting options since otherwise they would just need to be hidden variables).
Opinionated. The file configRenames.nix is entirely pedantic; it serves little purpose other than to make some of the variable names (such as col.-prefixed ones) more compatible with the intended semantics to be expressed in the Nix config. Without this, some things would need to be quoted as attribute names, and this bothered me.
Config-reloading is buggy. Changes to keybinds defined with the custom syntax are not reloaded despite reloadConfig being true. This has to do with a limitation in HM's DAG, but I do have a nearly-complete work-in-progress solution in a Git stash.
A significant amount of time has passed since I originally drafted this module, and some important changes (namely plugins option) have been made to the current official module and the one in Home-Manager. This module needs to be updated for parity.
Biggest blocker: This maybe a point of contention, but I want to keep ownership and be the BDFL (coined by Linus). This entails that:
- I approve the PRs (or Vaxry merges with mine or @fufexan's go-ahead).
- The license is CC-BY which is chosen to allow derivative works, even under a different license, but require that attribution is given to me and @fufexan (who I presume will be a core contributor).
- I would be amenable to adjustments as long as attribution is preserved.
- This module is not to be merged into Home-Manager in any official capacity. This would still be technically allowed, but unsanctioned.

Considering #5 and #8: I disagree with the opinion that this module ought to be simple. The problem is fundamentally complex. The problem-objective is this: to convert a structured Nix expression--consisting of attribute sets and weak dynamic types--into a node-based document language that has no specification, a weak schema, and ambiguous literal syntax. This is inherently a complicated problem that requires a complicated solution. For those who are familiar with Serde, that project is complicated for similar reasons. In fact, this project was inspired by that one (also see xml-rs, knuffel, and kdl). Lastly, because Nix is lazy, the features that you don't use will incur no cost; if you decide to omit the windowRules options or the eventListener options, you can do the equivalent in your own style using extraConfig text directly.

Why so much code? To expand upon the above paragraph:

My Hyprland module for Home Manager consists of a library for serializing and formatting an attribute set into Vaxry's config language. This functionality is contained within configFormat.nix.
This design is heavily modeled after pkgs.formats (doc) and I believe is the most correct way of implementing a language serializer in Nix. Currently the formatter is not exposed as any lib attributes, though I wish to change that to allow greater extensibility (including custom-generated files as sources).
I do take come creative liberties to make the whole process conceptually simpler, otherwise it would reminiscent of a bowl of noodles. Because Vaxry's config language is essentially a node document with some additional semantics, I have chosen to model it as such. Currently (and temporarily) every section, indent, value, and variable assignment is a node of sorts, with formatting options for each type of node.
The target language is full of edge-cases: for example, key binds have submaps, and submaps are not a {}-encapsulated block, whereas in Nix they are. This decision was made to both make the code you write prettier, and to preserve variable/section ordering. This is because features were added to the config language ad-hoc, and (presumably) not entirely planned (no shade, Vaxry has more important things to do, like #2415).

Thoughts on this PR

Now, for my review of this PR and to summarize my position. I do not think that this should be merged without further significant revision. I admit to being biased, I think that my module is best.

I do not think it wise to encourage users to migrate their configs to the technically inferior format exposed by the Home-Manager module at present, it would be premature. Proceeding would would mean that, once a consensus is reached regarding integration of my module, users would need to migrate a second time; users would be less inclined to do so.

As it stands, it is fairly easy to migrate a Hyprland config to a Nix config using my module. This can be done with a few replacements using regular expressions, whereas if someone were to first move to the current HM-module, and then some time later to my format, they may have written some complicated intermediate functions that conflict with the design of my module. Rectifying this would entail reversing those changes--which are probably complicated Nix expressions--and then reformatting to meet the specifications defined by my module.

This would decrease users' willingness to change their own configs, which means less people using my module, which means less feedback, which means less improvement for those who do decide to migrate. As my module is specifically designed to be extensible, I think that patching features and fixes into an inferior module would be a mistake, as over time it would become convoluted and unmaintainable.

Instead, I think it would be best to discuss all of the issues illustrated above and proceed with moving users over once the entire adoption process has been wholly officiated.

I look forward to further discussion and am excited at the prospect of developing this more, thank you for your patience and tolerance.

hyprland-community / hyprnix