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