103 lines
4.1 KiB
Markdown
103 lines
4.1 KiB
Markdown
# Hyprland Lua Migration Plan
|
|
|
|
## Problem Statement
|
|
|
|
The Hyprland compositor config uses Home Manager's hyprlang output.
|
|
Hyprland deprecates hyprlang for the main compositor config.
|
|
The repository needs to generate a Lua config without changing desktop behavior.
|
|
|
|
## Solution
|
|
|
|
Keep the config owned by Nix and Home Manager.
|
|
Switch the Hyprland Home Manager config output to Lua.
|
|
Convert only the settings whose shape changes under Lua.
|
|
|
|
This is not a desktop redesign.
|
|
The change preserves the current monitors, binds, window rules, environment variables, and UWSM startup.
|
|
|
|
## User Stories
|
|
|
|
1. As the operator, I want Hyprland to load `hyprland.lua`, so that startup no longer warns about hyprlang deprecation.
|
|
|
|
2. As the operator, I want existing keyboard binds to keep working, so that the desktop behavior stays unchanged.
|
|
|
|
3. As the operator, I want host monitor layout to stay unchanged, so that the physical display setup does not move.
|
|
|
|
4. As the operator, I want session environment variables to stay in the compositor config, so that Wayland and cursor behavior stays unchanged.
|
|
|
|
5. As the operator, I want auxiliary module binds to keep working, so that launcher, lock, screenshot, clipboard, notifications, and recording flows stay usable.
|
|
|
|
## Implementation Decisions
|
|
|
|
1. Use Home Manager's Lua config generator.
|
|
Set the Hyprland config type to Lua and keep package ownership unchanged.
|
|
|
|
2. Keep ordinary compositor options declarative in Nix.
|
|
Move input, general, decoration, xwayland, animation, and layout settings into the Lua config structure.
|
|
|
|
3. Remove hyprlang-only variables from generated config.
|
|
Keep modifier and terminal values as Nix locals or helper inputs.
|
|
|
|
4. Add minimal local helpers for Lua calls.
|
|
Use helpers only for repeated bind, dispatcher, command, environment, and rule shapes.
|
|
|
|
5. Convert all bind strings to Lua bind call data.
|
|
Preserve key combinations, dispatchers, commands, repeat behavior, and locked-session behavior.
|
|
|
|
6. Convert contributed binds in their owning modules.
|
|
Keep each bind near the module that owns the tool it launches.
|
|
|
|
7. Convert monitor strings to Lua monitor records.
|
|
Preserve output names, modes, positions, scale values, and rotation.
|
|
|
|
8. Convert the screenshot window rule to the Lua rule shape.
|
|
Preserve the Satty class matcher and floating behavior.
|
|
|
|
9. Convert environment strings to Lua environment calls.
|
|
Preserve the Wayland flag and cursor variables.
|
|
|
|
10. Delete or update comments that describe hyprlang syntax.
|
|
Keep comments that explain behavior or non-obvious invariants.
|
|
|
|
## Testing Decisions
|
|
|
|
1. Run the repository Nix formatting and style checks for modified Nix files.
|
|
|
|
2. Evaluate or build the affected host configuration.
|
|
This proves Home Manager accepts the Lua settings structure.
|
|
|
|
3. Confirm the generated config file uses Lua.
|
|
The expected output is `hyprland.lua`, not `hyprland.conf`.
|
|
|
|
4. Verify Hyprland accepts the generated Lua config.
|
|
Use Hyprland config verification when the installed build supports it.
|
|
Otherwise reload the compositor and inspect errors.
|
|
|
|
5. Smoke test the changed desktop surface.
|
|
Test one bind from each source area after reload.
|
|
|
|
6. Check the explicit monitor layout on the host that declares it.
|
|
Confirm resolution, position, scale, and rotation stayed unchanged.
|
|
|
|
## Out of Scope
|
|
|
|
- Do not split the config into Lua modules.
|
|
- Do not hand-write a full Lua config.
|
|
- Do not add new Hyprland behavior.
|
|
- Do not change UWSM startup.
|
|
- Do not redesign binds, monitor layout, or visual settings.
|
|
- Do not change hyprlock, hypridle, waybar, mako, or rofi settings beyond their Hyprland binds.
|
|
|
|
## Further Notes
|
|
|
|
Home Manager documents `configType = "lua"` for Hyprland.
|
|
It maps settings to `hl.*` calls.
|
|
It supports `_args` for multi-argument calls.
|
|
It supports raw Lua expressions with `lib.generators.mkLuaInline`.
|
|
|
|
The riskiest parts are binds, monitor declarations, and window rules.
|
|
Those parts changed shape more than scalar config sections.
|
|
|
|
Assumption: the pinned Home Manager input contains the documented Lua Hyprland generator.
|
|
Validate this during the configuration build.
|