diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index e4ee42b..f4c04f9 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -8,3 +8,5 @@ * xref:troubleshooting.adoc[Troubleshooting] * xref:faq.adoc[FAQ] * xref:tips-and-tricks.adoc[Tips and Tricks] +* Configuration Guides +** xref:sway-configuration-guide.adoc[Sway Configuration Guide] diff --git a/modules/ROOT/pages/sway-configuration-guide.adoc b/modules/ROOT/pages/sway-configuration-guide.adoc new file mode 100644 index 0000000..ffb3277 --- /dev/null +++ b/modules/ROOT/pages/sway-configuration-guide.adoc @@ -0,0 +1,148 @@ +[[sway-configuration-guide]] + +:config-repo: https://gitlab.com/fedora/sigs/sway/sway-config-fedora +:config-dir: {config-repo}/-/tree/fedora +:config-file: {config-repo}/-/blob/fedora + += Sway Configuration Guide + +[NOTE] +==== +This page provides a brief overview of configuration details specific for Fedora, and is common to both the package-based Sway Spin and the Sway Atomic variant. +Important differences will be highlighted. +==== + +If you are looking for more general resources, please check: + +* man pages: https://man.archlinux.org/man/sway.5[`sway(5)`] https://man.archlinux.org/man/sway-bar.5[`sway-bar(5)`] https://man.archlinux.org/man/sway-input.5[`sway-input(5)`] https://man.archlinux.org/man/sway-output.5[`sway-output(5)`] +* https://github.com/swaywm/sway/wiki[Official Sway wiki] +* https://i3wm.org/docs/userguide.html[i3 User's Guide]—while it's written for i3, all the important concepts are the same for Sway. + +== Configuration profiles + +The Sway package in Fedora defers most of the dependencies and the config file ownership to the `sway-config-*` subpackages. +This allows us to ship different configuration profiles with different sets of runtime dependencies. + +The following profile packages are currently available in Fedora: + +* *sway-config-upstream* - the upstream configuration as it comes with the Sway sources. +The only permitted modifications to this profile's config file are adjustments for dependencies currently unavailable in Fedora. +* *sway-config-minimal* - minimal configuration with any optional dependencies excluded. +The profile was created for headless servers, containers and buildroot usage. +It is also suitable for building a very minimal installation from scratch. +* *sway-config-fedora* - customized configuration for Fedora Sway Spin. + +The packages are mutually exclusive, and one of these must be present. +The one installed by default with `dnf install sway` is *sway-config-upstream* and the one that will be installed with Sway Spin/Sway Desktop Environment group is *sway-config-fedora*. + +You can select the profile with following command: + +[source,shell] +---- +$ sudo dnf swap sway-config sway-config-upstream +$ sudo dnf swap sway-config sway-config-minimal +$ sudo dnf swap sway-config sway-config-fedora +---- + +The command will replace the default `/etc/sway/config` file and apply the new set of dependencies. +Packages unused by the new profile will be autoremoved. + +The corresponding incantation for Sway Atomic and other custom Sway images is: + +[source,shell] +---- +$ sudo rpm-ostree override remove sway-config --install sway-config-upstream +---- + +Note, however, that it does not remove the original profile dependencies from the base layer of a deployment. + +== Fedora configuration + +{config-repo}[*sway-config-fedora*] contains the default configuration for Fedora Sway Spin. +It is built on top of the default Sway config with a few quality of life improvements and opinionated changes. + +Most of the additions are implemented as a standalone configuration snippets stored at {config-dir}/sway/config.d[`/usr/share/sway/config.d/`] and automatically loaded from the main configuration file. +Environment configuration and logging interception are implemented in the {config-file}/sway/start-sway[`/usr/bin/start-sway`] wrapper script. + +=== Environment variables + +If you are using a compatible Display Manager (GDM or SDDM), you should be able to adjust the initial environment for Sway using a system-wide configuration at `/etc/sway/environment` or per-user config at `~/.config/sway/environment`. +The variables set in the user configuration overwrite matching variables set system-wide. + +Please, check the comments and examples in {config-file}/sway/environment[`/etc/sway/environment`] to learn more. + +=== Sections + +The configuration snippets we provide are grouped into the following sections: + +50-59 (`50-rules-*.conf`):: Window rules (`for_window`, `assign` and related configuration). +60-69 (`60-bindings-\*.conf`, `65-mode-*.conf`):: Key bindings and binding modes. +90-94 (`90-*.conf`):: System applications: bars, idle daemons and other components. +95-99 (`95-*.conf`):: Autostart applications. + +=== Overrides and load precedence + +Fedora configuration pass:[ab]uses the implementation details of the Sway configuration parser (https://man7.org/linux/man-pages/man3/wordexp.3p.html[`wordexp(3p)`]) to implement an overrides mechanism for the snippets. + +The priority increases from the packaged configuration to a system-wide configuration and an user configuration directories: + +* `/usr/share/sway/config.d/*.conf` +* `/etc/sway/config.d/*.conf` +* `$XDG_CONFIG_HOME/sway/config.d/*.conf` (defaults to `+~/.config/sway/config.d/*.conf+`) + +The includes are also sorted by a file name across all the directories. + +By creating a file with the same name in `/etc/sway/config.d` you'll force the config preprocessor to ignore the corresponding snippet from `/usr` and load the one from `/etc`. +Similarly, the configuration snippet from a home directory wins over the earlier locations. + +To put it even more simple: imagine the distribution configuration file `/usr/share/sway/config.d/90-bar.conf` that sets `waybar` as a status bar. +If you want to prevent `waybar` from starting, you could create an empty file in your home directory: + +[source,shell] +---- +$ mkdir -p ~/.config/sway/config.d +$ touch ~/.config/sway/config.d/90-bar.conf +---- + +If you want to use another bar, you just need to add some contents to the file. +For example, copy the default bar section from the upstream Sway config: + +[source] +---- +$ mkdir -p ~/.config/sway/config.d +$ cat >~/.config/sway/config.d/90-bar.conf <