sway: add initial configuration guide
This commit is contained in:
Aleksei Bavshin
parent
46c46d09af
commit
642fdebf8c
1 changed files with 159 additions and 0 deletions
159
doc/configuration.adoc
Normal file
159
doc/configuration.adoc
Normal file
|
|
@ -0,0 +1,159 @@
|
||||||
|
= Configuration guide
|
||||||
|
Fedora Sway SIG <sway@lists.fedoraproject.org>
|
||||||
|
:source-highlighter: rouge
|
||||||
|
:sway-package: https://packages.fedoraproject.org/pkgs/sway/
|
||||||
|
:config-package: https://packages.fedoraproject.org/pkgs/sway-config-fedora/
|
||||||
|
:toc:
|
||||||
|
|
||||||
|
An overview of the custom Sway configuration shipped in Fedora.
|
||||||
|
|
||||||
|
== 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.
|
||||||
|
This also allows anyone to create a package with their preferred system-wide
|
||||||
|
configuration defaults and use it instead of the default Fedora profiles.
|
||||||
|
|
||||||
|
The following profiles are currently defined in the {sway-package}[`sway`]
|
||||||
|
source package:
|
||||||
|
|
||||||
|
* **sway-config-minimal** - minimal configuration with any optional
|
||||||
|
dependencies omitted.
|
||||||
|
Suitable for headless servers, containers and buildroot usage.
|
||||||
|
Also suitable for building a very minimal installation from scratch.
|
||||||
|
|
||||||
|
* **sway-config-upstream** - the upstream configuration.
|
||||||
|
The only permitted modifications to the config file are adjustments for
|
||||||
|
dependencies currently unavailable in Fedora.
|
||||||
|
|
||||||
|
The profiles defined in the {config-package}[`sway-config-fedora`] source
|
||||||
|
package:
|
||||||
|
|
||||||
|
* **sway-config-fedora** - customized configuration for Fedora Sway Spin.
|
||||||
|
|
||||||
|
The config packages are mutually exclusive, and one of these will always be
|
||||||
|
installed.
|
||||||
|
The one selected by default is **sway-config-upstream** and the one that will
|
||||||
|
be installed with Sway Spin/Sway Desktop Environment group is
|
||||||
|
**sway-config-fedora**.
|
||||||
|
|
||||||
|
At any moment, you can switch the installed configuration with one of the
|
||||||
|
following commands:
|
||||||
|
|
||||||
|
[source,shell]
|
||||||
|
----
|
||||||
|
dnf swap sway-config sway-config-upstream
|
||||||
|
dnf swap sway-config sway-config-minimal
|
||||||
|
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.
|
||||||
|
|
||||||
|
NOTE: The command will be different for OSTree-based installations, such as Sericea.
|
||||||
|
|
||||||
|
== Fedora configuration
|
||||||
|
|
||||||
|
**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 `+/usr/share/sway/config.d/+` and automatically loaded from the main
|
||||||
|
configuration file.
|
||||||
|
|
||||||
|
=== 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 uses the implementation details of the Sway config loading
|
||||||
|
(https://man7.org/linux/man-pages/man3/wordexp.3p.html[`wordexp(3p)`]) to
|
||||||
|
implement a configuration 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:-$HOME/.config}/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
|
||||||
|
Sway 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 set 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,shell]
|
||||||
|
----
|
||||||
|
mkdir -p ~/.config/sway/config.d
|
||||||
|
cat >~/.config/sway/config.d/90-bar.conf <<EOF
|
||||||
|
# Read `man 5 sway-bar` for more information about this section.
|
||||||
|
bar {
|
||||||
|
position top
|
||||||
|
|
||||||
|
# When the status_command prints a new line to stdout, swaybar updates.
|
||||||
|
# The default just shows the current date and time.
|
||||||
|
status_command while date +'%Y-%m-%d %I:%M:%S %p'; do sleep 1; done
|
||||||
|
|
||||||
|
colors {
|
||||||
|
statusline #ffffff
|
||||||
|
background #323232
|
||||||
|
inactive_workspace #32323200 #32323200 #5c5c5c
|
||||||
|
}
|
||||||
|
}
|
||||||
|
EOF
|
||||||
|
----
|
||||||
|
|
||||||
|
=== Debugging the configuration
|
||||||
|
|
||||||
|
Sometimes it's useful to know how the configuration loaded by Sway actually looks.
|
||||||
|
There are two ways to debug that:
|
||||||
|
|
||||||
|
* Run sway config validation:
|
||||||
|
[source,shell]
|
||||||
|
----
|
||||||
|
sway --debug --validate [--config /path/to/config]
|
||||||
|
----
|
||||||
|
|
||||||
|
* Check intermediate files generated by the layered include script
|
||||||
|
|
||||||
|
[source,shell]
|
||||||
|
----
|
||||||
|
less $XDG_RUNTIME_DIR/sway/layered-include-*.conf
|
||||||
|
----
|
||||||
|
|
||||||
|
TIP: The command referenced may display more than one file. Use `+:n+`/`+:p+` to switch between files in `+less+`
|
||||||
Loading…
Add table
Add a link
Reference in a new issue