Sway: Difference between revisions

From Alpine Linux
(Added a section for novice questions and detailed a few more troubleshooting steps)
Tag: Reverted
m (added sway wiki)
 
(112 intermediate revisions by 14 users not shown)
Line 1: Line 1:
[http://swaywm.org Sway] is a tiling [[Wayland]] compositor. It's a drop-in replacement for the i3 window manager.
[https://swaywm.org Sway] is a tiling [[Wayland]] compositor and a drop-in replacement for the [[i3wm |i3 window manager]]. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.


== Setup ==
{{:Include:Setup-desktop}}
Install appropriate [[#Install Graphics Drivers|video]] drivers for your hardware before you can [[#Starting sway|launch sway]]. Without  graphics drivers [[#Video Driver Issues|errors]] may occur.


Don't forget, you will need to add the community repository.
== Manual Installation ==


<pre>
The below installation step allows you to pick and choose various componenents for your Sway Desktop.
$ whoami
user
$ su
<snippet>
# whoami
root
# echo $USER # just so that we know we retained the same environment variables
user
# # if the output is 'root' then we know we must have logged in using 'su -'
# cat /etc/apk/repositories
<snippet>
# # You can edit the files in vi and remove the comment '#' from the line that has <version>/community
</pre>


Once you have updated the file manually you can continue to the [[Installation|installation]] step.
=== Add a normal user ===


{{Tip| Or you can run something <strong>ridiculous</strong> like this:
Use <code>setup-user</code> to add a non-system normal user for running Sway.
<pre>
{{cmd|# setup-user}}
# tFILE='/etc/apk/repositories'
# line="$(cat $tFILE | grep -E "^#.*alpine/v.*/community" | cut -f1 -d:)" # add the comments so that it doesn't run everytime
# awk -v line=$line 'FNR == line { sub("#",""); print } FNR != line { print }' $tFILE > $tFILE.upd
# cat $tFILE.upd # if everything is correct after inspection then we can move it over
<snippet>
# cp $tFILE $tFILE.bak # just in case the hairbrained idea doesn't work
# cat $tFILE.upd > $tFILE; rm $tFILE.upd # we want to keep the file permissions so don't use cp
</pre>
}}


== Installation ==
=== Set up eudev ===


eudev:
[[eudev]] is recommended and required for Sway. Without it, sway cannot connect to input devices.


<pre>
{{cmd|# setup-devd udev}}
# whoami
root
# rc-update # let's look at the services that are configured for each run-level
<snippet>
# apk add eudev
# setup-devd udev
# rc-update # we can now see the services that have been added by the setup script
<snippet>
</pre>
 
Graphics drivers:


* [[Intel Video]]
=== Install Graphics Drivers ===
* [[Radeon Video]]
{{:Graphics_driver}}
* [[Nvidia Video]]
=== Setting up a seat manager ===
Add user to the input and video groups:


<pre>
Wayland compositors need raw access to input and output devices. This is mediated by a [[seat manager]]. Using either [[seatd]] or [[elogind]] is supported. Using both may lead to conflicts.
# whoami
root
# echo $USER
user
# adduser $USER input
# adduser $USER video
</pre>


==== Install seatd ====


Install some TTF fonts:
See [[Seatd]] for the mandatory steps needed for sway to work with seatd.


<pre>
==== Install elogind ====
# apk add ttf-dejavu
<snippet>
</pre>


seatd daemon:
See [[Elogind]].


<pre>
=== Install fonts ===
# # if we like we can look at the services again using rc-update
# apk add seatd
<snippet>
# rc-update add seatd
# # and then look again to compare
# rc-service seatd start
# adduser $tempUSER seat
</pre>


Install sway:
Install DejaVu fonts, which has good Unicode coverage:
{{cmd|# apk add font-dejavu}} 
=== Install Sway ===


<pre>
{{cmd|# apk add sway \
# apk add sway sway-doc
     xwayland            \ # if you need xserver
<snippet>
# apk add                \ # Install optional dependencies:
     xwayland            \ # recommended for compatibility reasons
     foot                \ # default terminal emulator. Modify $term in config for a different one.
     foot                \ # default terminal emulator. Modify $term in config for a different one.
     bemenu              \ # wayland menu
     wmenu                \ # default wayland native menu for choosing program and screensharing monitor
     swaylock swaylockd  \ # lockscreen tool
     swaylock swaylockd  \ # lockscreen tool
     swaybg              \ # wallpaper daemon
     swaybg              \ # display wallpaper
    grim                \ # screenshot tool
    wl-clipboard        \ # clipboard management
    i3status            \ # simple status bar
     swayidle              # idle management (DPMS) daemon
     swayidle              # idle management (DPMS) daemon
</pre>
}}
For complimentary software alternatives, see [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the relevant page from sway's wiki] or [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland this list at Gentoo Wiki.]
 
== Configuration ==
 
Copy default sway configuration to <code>~/.config</code>:
{{cmd|$ mkdir -p ~/.config/sway
$ cp /etc/sway/config ~/.config/sway/}}
Read through it to learn the default keybindings.
Sway configuration is mostly backwards-compatible with that of [[I3wm|i3]] and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.
 
For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].
 
=== Starting sway ===
 
One can launch sway by issuing the command sway from TTY.
 
{{Cmd|$ sway}}
 
You can also sway with a greeter like [[greetd]]. In this case, to start sway session for the user, you might want to start a [[D-Bus#D-Bus_session|D-Bus session]] when the greetd session is started.
 
{{Cat|/etc/greetd/environments|<nowiki># Launch Sway with a D-Bus server available, use:
dbus-run-session -- sway
</nowiki>}}
 
D-Bus is required for PipeWire and screensharing in Firefox and Chromium. Running with <code>dbus-run-session</code> is a convenience wrapper that will explicitly export the path of the session bus.
 
=== PipeWire and Screensharing ===
 
For audio playback, install [[PipeWire#Installation|PipeWire]]. The sway compositor has no involvement in audio playback.


Configure [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].
For screen sharing, applications are split into two categories:


== Usage ==
* Those which use the native wayland protocol, </code>wlr-screencopy</code>
* Those which use the API from Flatpak's <code>xdg-desktop-portal</code> (this portal is also used by native non-Flatpak applications).


For inter-program communication and functionality such as screensharing, install and enable dbus and PipeWire, see [[PipeWire]] and set <code>SWAYSOCK</code> environmental variable to the value exported by <code>sway</code>. In order to ensure that Pipewire and related services inherit the right environment variables, it is recommended to start these services via a process that is a direct descendant of sway itself.
Applications in the first group require no additional setup. Applications in the second group (which includes Firefox and Chromium) require setting up xdg portals in addition to [[PipeWire#Installation|PipeWire]].


Launch Sway with a D-Bus server available, use:
{{Cmd|#  apk add xdg-desktop-portal xdg-desktop-portal-wlr}}


Launch PipeWire with Sway. Use your service manager of choice, or add the following to sway config:
<pre>
<pre>
dbus-run-session -- sway #prepend with exec in your login shell init script
exec /usr/libexec/pipewire-launcher
</pre>
</pre>


== Configuration ==
If your are using automatic [[D-Bus]] activation, you also need to set DBus variables for the portal and screensharing features to work:
 
exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway
 
=== Greetd ===
 
See [[greetd]] for an optional login manager.
 
=== Screen lock and suspend-to-RAM ===
 
If [[Elogind]] is not used, consider using {{Pkg|powerctl}}.
 
Putting the system to sleep with elogind requires elevated privileges or additional configuration.
 
For details on configuring <code>doas</code> with <code>elogind</code>, see [[Elogind#Doas]]
 
To put the system to sleep after 600 seconds, use:
 
exec swayidle -w timeout 600 'doas /bin/loginctl suspend'
 
loginctl suspend command will trigger the screenlock, as mentioned in the section [[#Install elogind (optional)|Install elogind (optional)]] above.
 
Do not lock the screen if program is running in full screen:
 
for_window [app_id="^.*"] inhibit_idle fullscreen
 
=== Elogind and swayidle ===
 
<code>swayidle</code> has integration with <code>elogind</code> and can handle <code>before-sleep</code> events.
 
If using <code>swayidle before-sleep</code>, there will be a race condition, so that when you resume the computer from suspend, the screen shows the contents of the unlocked screen for a second before showing the actual lock screen.  This can be a privacy concern.


An example config is provided at <code>/etc/sway/config</code>. Copy it to <code>~/.config/sway/config</code> and read through it to learn the default keybindings.
To solve this issue, do the following:
Sway configuration is mostly backwards-compatible with that of [[I3wm|i3]] and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.


For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].
Create this file <code>/etc/elogind/system-sleep/10-swaylock.sh</code>, then add the following script to this file:


=== Firefox screensharing ===
#!/bin/sh
if [ "${1}" == "pre" ]; then
  touch /tmp/swaylock-sleep
  sleep 1
fi


For some programs, additional configuration is needed to launch them natively under Wayland and to support special features such as screen sharing.
Then set it to executable.


To launch Firefox natively under Wayland and to enable support for screensharing, you need:
Later, once sway is installed, add the following line to sway config:


* Install and configure [[PipeWire]]
exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep
* Install xdg-desktop-portal and xdg-desktop-portal-wlr package
* Install wofi for screen selection
* Launch support programs on sway startup:
<pre>
exec /usr/libexec/pipewire-launcher #pipewire must be launched first
exec /usr/libexec/xdg-desktop-portal-wlr
</pre>
* Export the following variables:


<pre>
With this line, the screen will be promptly locked before suspend-to-RAM starts.
export MOZ_ENABLE_WAYLAND="1"
export XDG_CURRENT_DESKTOP=sway
export QT_QPA_PLATFORM="wayland-egl"
</pre>


=== Flatpaks ===
=== Brightness control ===


Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.
Controlling display backlight requires either the proper udev rules, or using some form of privilege escalation.


After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:
{{Pkg|brightnessctl}} is a reliable alternative, although its default udev rules require too wide permissions (see {{Issue|15409}}). You may need your own rules, or configure doas to allow running it as an unprivileged user.
<pre>
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome
</pre>


This is only needed if they are not started automatically via other means.
Optionally enable brightnessctl service to restore brightness settings on reboot:


=== Scaling for high resolution screens ===
rc-update add brightnessctl


Without further configuration, program interfaces might be too small to use on high resolution screens.
=== Output scaling for high resolution displays ===


==== Via sway ====
Without further configuration, program interfaces might be too small to use on high resolution displays.


Sway supports the per-display configuration of
Sway supports the per-display configuration of
Line 166: Line 166:
However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended.  See below.
However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended.  See below.


To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package.  Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2.  To make changes permanent, add
To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package.  Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2.  To make changes permanent, add below to ~/.config/sway/config.
 
[[#output|output <name> scale <factor>]] to ~/.config/sway/config
 
==== Via GTK/Qt ====


<pre>
<pre>
# for GTK-based programs such as firefox and emacs:
output <name> scale <factor>
export GDK_DPI_SCALE=2
 
# for QT-based programs
export QT_WAYLAND_FORCE_DPI="physical"
# or if still too small, use a custom DPI
export QT_WAYLAND_FORCE_DPI=192 # 2x scaling
export QT_QPA_PLATFORM="wayland-egl"
</pre>
</pre>


=== Make clipboard content persistent ===
To use toolkit scaling, use
By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.
{{Cmd|# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE{{=}}2


Install clipman from test repo and add the following to sway config:
<nowiki>#</nowiki> for QT-based programs
export QT_WAYLAND_FORCE_DPI{{=}}"physical"
<nowiki>#</nowiki> or if still too small, use a custom DPI
export QT_WAYLAND_FORCE_DPI{{=}}192 # 2x scaling
export QT_QPA_PLATFORM{{=}}"wayland-egl"
}}


<pre>
exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"
</pre>


=== Firefox picture-in-picture mode/floating windows ===
=== Screenshots ===
Add this to your sway config file (modify the numeric values to suit your needs and your display):
<pre>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
</pre>


=== Screenshots ===
A simple tool that works well under Wayland is Grimshot. Example keybindings:
A simple tool that works well under Wayland is Grimshot. Example keybindings:
<pre>
<pre>
Line 210: Line 196:
See [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the sway wiki's article] for a list of screenshot tools.
See [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the sway wiki's article] for a list of screenshot tools.


=== Start with NumLock enabled ===
=== Make clipboard content persistent ===
Add this to your sway config file:
 
<code>input type:keyboard xkb_numlock enabled</code>
By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.


=== Change cursor theme and size ===
Install {{Pkg|clipman}} from testing repo and add the following to sway config:
Add to your sway config:
<pre>
seat seat0 xcursor_theme my_cursor_theme my_cursor_size
</pre>
You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.
{{Note|Wayland uses client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}


=== Start as a service ===
Although this is not necessary, you may write an init script like the following:
<pre>
<pre>
{{/etc/init.d/sway|
exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
#!/sbin/openrc-run
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"
 
description="Sway Compositor"
 
command="/usr/bin/sway"
command_args=""
 
pidfile="/run/sway.pid"
 
start_stop_daemon_args="--background --pidfile ${pidfile}"
 
depend() {
  need localmount
  after elogind
  use seatd dbus
}
</pre>
</pre>
Then as a root run <code>chmod +x /etc/init.d/seat</code> and <code>rc-update add sway default</code>. Make sure you have elogind installed or specify another service, like your display/login manager after which the sway service will run.


=== Custom keyboard layout ===
=== Firefox picture-in-picture mode/floating windows ===


Since wayland does not support setxkbmap, you will also need to add similar content to your ''/usr/share/X11/xkb/rules/evdev.xml'', after <code></modelList></code> and after <code><layoutList></code>:
Add this to your sway config file (modify the numeric values to suit your needs and your display):
<pre>
<pre>
<layout>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
      <configItem>
        <name>[the name of your layout, same as the name of the file in /usr/share/X11/xkb/symbols]</name>
        <shortDescription>[usually just two letters]</shortDescription>
        <description>[description of your layout]</description>
        <countryList>
          <iso3166Id>US</iso3166Id>
          <iso3166Id>NO</iso3166Id>
        </countryList>
        <languageList>
          <iso639Id>eng</iso639Id>
        </languageList>
      </configItem>
    </layout>
<!--[other layouts]-->
</pre>
</pre>
Then, to enable for all keyboards, navigate to the input section of ''~/.config/sway/config'' and modify it to
<pre>
input * {
  xkb_layout "my_layout"
}
</pre>
If you have enabled <code>xkb_numlock</code>, include this setting inside those braces as well.


== Troubleshooting ==
=== Start with NumLock enabled ===


If you encounter any issues, try running <code>sway -Vc /etc/sway/config</code>. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).
Add this to your sway config file:
 
=== Firefox (Flatpak) and/or GTK apps ===
==== Disappearing cursor ====
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.


==== Missing file picker/cannot download ====
input type:keyboard xkb_numlock enabled


Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.
=== Change mouse cursor theme and size ===


=== Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start ===
Add to your sway config:
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').


=== Sway socket not detected ===
seat seat0 xcursor_theme my_cursor_theme my_cursor_size


See [[Sway#Installation|Installation]] for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as [[Tmux terminal multiplexer|tmux]]
For example, set a mouse cursor, using GNOME Adwaita theme:


=== Sway freezes after loading and no iput works ===
seat seat0 xcursor_theme Adwaita 16
You can move to a new <code>tty</code> [<code>CTRL</code> + <code>ALT</code> + <code>F<n></code>; where <code><n></code> is a number Fkey on your keyboard], login as root, and kill all the processes that are linked to the problem <code>tty</code>.
{{Tip|Something like this
<pre>
# for i in $(ps | awk '{ if($2==<user>) { print $1 } }'); do
> kill -9 $i
> done # don't forget to replace <user> with the user of the frozen tty
</pre>
}}


=== Steam games launched via Proton crash before creating a window ===
You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.


Instead of just using the in-Steam menu to install and select a Proton version, try installing the flatpak community build for Proton onto your system. There are several versions, depending on your desired stability, and the experimental version available in Flathub is called "com.valvesoftware.Steam.CompatibilityTool.Proton-Exp". After you install your chosen version, go into Steam to specify compatibility tool for a game as usual. The installed community build will now be an option. Select that and try launching the game again.
{{Note|Wayland allows for client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}
[[Category:Desktop]]


== Novice Questions ==
=== Custom keyboard layout ===


=== What if the services <var>hwdrivers</var> or <var>mdev</var> are not in the <var>sysinit</var> run-level? ===
To use custom keyboard layout, just use
<blockquote>
"udev performs its own hwdrivers module detection, it does not need the additional service. We delete the hwdrivers service when enabling udev, and add it when enabling mdev and mdevd."
<hr/>
<strong>Source: </strong>[https://gitlab-test.alpinelinux.org/alpine/alpine-conf/-/merge_requests/100 alpine-conf]
</blockquote>
 
=== What does <var>seatd</var> do? ===
<blockquote>
"Seat management takes care of mediating access to shared devices (graphics, input), without requiring the applications needing access to be root."
<hr/>
<strong>Source: </strong>[https://sr.ht/~kennylevinsen/seatd/ sourcehut]
</blockquote>
 
=== What if I run into a problem with sway? ===
You can always check the version that you are running. But problems like the following error can occur:
<pre>
<pre>
# sway --version
input type:keyboard {
Error loading shared library libjson-c.so.5: I/O error (needed by /usr/bin/sway)
  xkb_file /path/to/my/custom/layout
<snippet>
}
</pre>
</pre>


When this error occurred I was experiencing trouble with the filesystem. The filesystem had *booped* itself into <var>read-only mode</var>. A reboot fixed this error.
=== Changing default application fonts ===
<pre>
# sway --version
sway version 1.7
</pre>
=== Where is good Alpine documentation? ===
Try here for reading.
[[gitlab.alpinelinux.org/alpine/aports/-/issues|gitlab.alpinelinux.org/alpine/aports/-/issues]]


=== How do I debug the launch of Sway? ===
See [[Fontconfig]]
I ran <code>sway -Vc /home/<user>/.config/sway/config</code> as root so that I would experience an error and not complete.


=== What happens if <var>SWAYSOCK</var> is empty? ===
== Troubleshooting ==


If you encounter any issues, try running <code>sway -Vc /etc/sway/config</code>. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).


[[Swaylock|https://github.com/swaywm/swaylock/blob/master/README.md]]
To capture the sway error log in a file for troubleshooting, replace <code>sway</code> in your startup file by
<code>sway -d 2> ~/sway_error.log</code>.  


=== What happens if <var>LD_LIBRARY_PATH</var> is empty? ===
Alternately, you can also issue the below command from TTY.
<blockquote>
{{cmd|$ sway -d 2> ~/sway_error.log}}  
"LD_PRELOAD (not LD_PRELOAD_PATH) is a list of specific libraries (files) to be loaded before any other libraries, whether the program wants it or not. LD_LIBRARY_PATH is a list of directories to search when loading libraries that would have been loaded anyway. On linux you can read man ld.so for more information about these and other environment variables that affect the dynamic linker."
<hr>
{{Define|Source|[https://stackoverflow.com/questions/14715175/what-is-the-difference-between-ld-preload-path-and-ld-library-path]}}
</blockquote>
<blockquote>
"When should I set LD_LIBRARY_PATH?
The short answer is never.


Why?
=== Video Driver Issues ===
Some users seem to set this environment variable because of bad advice from other users or badly linked code that they do not know how to fix."
<hr>
{{Define|Source|[http://linuxmafia.com/faq/Admin/ld-lib-path.html]}}
</blockquote>
{{Define|Source|[http://linuxmafia.com/faq/Admin/ld-lib-path.html]}}
</blockquote>


{{Note|ENVIRONMENT
After installing sway, while launching it for the first time, lack of proper [[#Install Graphics Drivers|video drivers]] causes various error messages such as:
The following environment variables have an effect on sway:
* "unable to create backend"
* "Failed to create renderer"


SWAYSOCK
Do install necessary drivers for your [[#Install Graphics Drivers|graphics card]] for sway to work.


Specifies the path to the sway IPC socket.
=== Flatpaks ===
XKB_DEFAULT_RULES, XKB_DEFAULT_MODEL, XKB_DEFAULT_LAYOUT, XKB_DEFAULT_VARIANT, XKB_DEFAULT_OPTIONS


Configures the xkb keyboard settings. See xkeyboard-config(7). The preferred way to configure the keyboard is via the configuration file, see sway-input(5).
{{main|Flatpak}}
The following environment variables are set by sway:
Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-portal-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.


DISPLAY
After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:
<pre>
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome
</pre>


If compiled with Xwayland support and Xwayland is not disabled by the config, this will be set to the name of the X display used for Xwayland.
This is only needed if they are not started automatically via other means.
I3SOCK


For compatibility with i3, specifies the path to the sway IPC socket.
=== Firefox (Flatpak) and/or GTK apps ===


SWAYSOCK
==== Disappearing cursor ====


Specifies the path to the sway IPC socket.[https://itcomprehension.com/ipc-ports-services-and-connections-explained]
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme      for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.


WAYLAND_DISPLAY
==== Missing file picker/cannot download ====


Specifies the name of the Wayland display that sway is running on.
Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.
XCURSOR_SIZE]


Specifies the configured cursor size.
=== Nvidia Issues ===
XCURSOR_THEME
{{Main|NVIDIA}}
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').


Specifies the configured cursor theme.
== See Also ==
<hr/>
* [https://github.com/swaywm/sway/wiki/ Sway Wiki]
{{Define|Source|[https://man.archlinux.org/man/sway.1]}}
* [https://wiki.archlinux.org/title/Sway Archwiki]
}}
* [https://wiki.gentoo.org/wiki/Sway Gentoo Wiki]
* [https://wiki.postmarketos.org/wiki/Sway PostmarketOS Wiki]


<pre>
[[Category:Compositor]]
# swaymsg -t get_seats
[[Category:Desktop]]
<timestamp> [swaymsg/main.c:419] Unable to retrieve socket path
[[Category:Window Managers]]
</pre>
[[Category:Wayland]]
 
=== What if <var>/etc/sway/config.d/*</var> is empty? ===

Latest revision as of 09:47, 22 October 2024

Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.

Note: Before installing any desktop,

Installation using setup-desktop

The Alpine Linux script for setting up a desktop quickly is setup-desktop.

# setup-desktop

On running the above command, you will be prompted to select a desktop environment.

Which desktop environment? ('gnome', 'plasma', 'xfce', 'mate', 'sway' or 'none') [none]

Once you have chosen a desktop environment, this script installs the chosen desktop along with all the necessary packages, firefox browser and adds the necessary services to run on startup. You can reboot when complete and the system will boot into a graphical login screen with the desktop environment. Depending on the desktop chosen, the script also activates the necessary services like dbus, elogind, login manager etc..

To view all the packages that are installed by the script for the chosen desktop you can issue the below command:

# cat /sbin/setup-desktop

Install appropriate video drivers for your hardware before you can launch sway. Without graphics drivers errors may occur.

Manual Installation

The below installation step allows you to pick and choose various componenents for your Sway Desktop.

Add a normal user

Use setup-user to add a non-system normal user for running Sway.

# setup-user

Set up eudev

eudev is recommended and required for Sway. Without it, sway cannot connect to input devices.

# setup-devd udev

Install Graphics Drivers

Many desktop environments need a graphics driver to work properly. Graphics cards of recent vintage need a driver to work. So one needs to install one of the below graphics drivers before installing a desktop:

Information about the video cards that are installed in the computer may be found using lspci command, which is not available by default. Refer the instructions to install pciutils package.

To identify the graphics card (the Subsystem output shows the specific model), issue the below command:

lspci -v | grep -A1 -e VGA -e 3D

Then, install an appropriate driver.

For details on legacy Xorg drivers refer Xorg page.

Setting up a seat manager

Wayland compositors need raw access to input and output devices. This is mediated by a seat manager. Using either seatd or elogind is supported. Using both may lead to conflicts.

Install seatd

See Seatd for the mandatory steps needed for sway to work with seatd.

Install elogind

See Elogind.

Install fonts

Install DejaVu fonts, which has good Unicode coverage:

# apk add font-dejavu

Install Sway

# apk add sway \ xwayland \ # if you need xserver foot \ # default terminal emulator. Modify $term in config for a different one. wmenu \ # default wayland native menu for choosing program and screensharing monitor swaylock swaylockd \ # lockscreen tool swaybg \ # display wallpaper grim \ # screenshot tool wl-clipboard \ # clipboard management i3status \ # simple status bar swayidle # idle management (DPMS) daemon

For complimentary software alternatives, see the relevant page from sway's wiki or this list at Gentoo Wiki.

Configuration

Copy default sway configuration to ~/.config:

$ mkdir -p ~/.config/sway $ cp /etc/sway/config ~/.config/sway/

Read through it to learn the default keybindings. Sway configuration is mostly backwards-compatible with that of i3 and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.

For additional information, start at man 5 sway and read the upstream wiki.

Starting sway

One can launch sway by issuing the command sway from TTY.

$ sway

You can also sway with a greeter like greetd. In this case, to start sway session for the user, you might want to start a D-Bus session when the greetd session is started.

Contents of /etc/greetd/environments

# Launch Sway with a D-Bus server available, use: dbus-run-session -- sway

D-Bus is required for PipeWire and screensharing in Firefox and Chromium. Running with dbus-run-session is a convenience wrapper that will explicitly export the path of the session bus.

PipeWire and Screensharing

For audio playback, install PipeWire. The sway compositor has no involvement in audio playback.

For screen sharing, applications are split into two categories:

  • Those which use the native wayland protocol, wlr-screencopy
  • Those which use the API from Flatpak's xdg-desktop-portal (this portal is also used by native non-Flatpak applications).

Applications in the first group require no additional setup. Applications in the second group (which includes Firefox and Chromium) require setting up xdg portals in addition to PipeWire.

# apk add xdg-desktop-portal xdg-desktop-portal-wlr

Launch PipeWire with Sway. Use your service manager of choice, or add the following to sway config: 

 exec /usr/libexec/pipewire-launcher

If your are using automatic D-Bus activation, you also need to set DBus variables for the portal and screensharing features to work: 

exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway

Greetd

See greetd for an optional login manager.

Screen lock and suspend-to-RAM

If Elogind is not used, consider using powerctl.

Putting the system to sleep with elogind requires elevated privileges or additional configuration.

For details on configuring doas with elogind, see Elogind#Doas

To put the system to sleep after 600 seconds, use: 

exec swayidle -w timeout 600 'doas /bin/loginctl suspend'

loginctl suspend command will trigger the screenlock, as mentioned in the section Install elogind (optional) above.

Do not lock the screen if program is running in full screen: 

for_window [app_id="^.*"] inhibit_idle fullscreen

Elogind and swayidle

swayidle has integration with elogind and can handle before-sleep events.

If using swayidle before-sleep, there will be a race condition, so that when you resume the computer from suspend, the screen shows the contents of the unlocked screen for a second before showing the actual lock screen. This can be a privacy concern.

To solve this issue, do the following:

Create this file /etc/elogind/system-sleep/10-swaylock.sh, then add the following script to this file: 

#!/bin/sh
if [ "${1}" == "pre" ]; then
  touch /tmp/swaylock-sleep
  sleep 1
fi

Then set it to executable.

Later, once sway is installed, add the following line to sway config: 

exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep

With this line, the screen will be promptly locked before suspend-to-RAM starts.

Brightness control

Controlling display backlight requires either the proper udev rules, or using some form of privilege escalation.

brightnessctl is a reliable alternative, although its default udev rules require too wide permissions (see #15409). You may need your own rules, or configure doas to allow running it as an unprivileged user.

Optionally enable brightnessctl service to restore brightness settings on reboot: 

rc-update add brightnessctl

Output scaling for high resolution displays

Without further configuration, program interfaces might be too small to use on high resolution displays.

Sway supports the per-display configuration of

  • fractional (e.g., 1.5x), and
  • integer scaling (e.g., 2x)

However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended. See below.

To enable Sway scaling, the user can first preview different scaling factors with wdisplays package. Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2. To make changes permanent, add below to ~/.config/sway/config. 

output <name> scale <factor>

To use toolkit scaling, use

# for GTK-based programs such as firefox and emacs: export GDK_DPI_SCALE=2 # for QT-based programs export QT_WAYLAND_FORCE_DPI="physical" # or if still too small, use a custom DPI export QT_WAYLAND_FORCE_DPI=192 # 2x scaling export QT_QPA_PLATFORM="wayland-egl"


Screenshots

A simple tool that works well under Wayland is Grimshot. Example keybindings: 

bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png

See the sway wiki's article for a list of screenshot tools.

Make clipboard content persistent

By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.

Install clipman from testing repo and add the following to sway config: 

exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"

Firefox picture-in-picture mode/floating windows

Add this to your sway config file (modify the numeric values to suit your needs and your display): 

for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none

Start with NumLock enabled

Add this to your sway config file: 

input type:keyboard xkb_numlock enabled

Change mouse cursor theme and size

Add to your sway config: 

seat seat0 xcursor_theme my_cursor_theme my_cursor_size

For example, set a mouse cursor, using GNOME Adwaita theme: 

seat seat0 xcursor_theme Adwaita 16

You can inspect their values with echo $XCURSOR_SIZE and echo $XCURSOR_THEME. If reloading your config does not result in change, try logging out and in.

Note: Wayland allows for client-side cursors. It is possible that applications do not evaluate the values of $XCURSOR_SIZE and $XCURSOR_THEME.

Custom keyboard layout

To use custom keyboard layout, just use 

input type:keyboard {
  xkb_file /path/to/my/custom/layout
}

Changing default application fonts

See Fontconfig

Troubleshooting

If you encounter any issues, try running sway -Vc /etc/sway/config. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).

To capture the sway error log in a file for troubleshooting, replace sway in your startup file by sway -d 2> ~/sway_error.log.

Alternately, you can also issue the below command from TTY.

$ sway -d 2> ~/sway_error.log

Video Driver Issues

After installing sway, while launching it for the first time, lack of proper video drivers causes various error messages such as:

  • "unable to create backend"
  • "Failed to create renderer"

Do install necessary drivers for your graphics card for sway to work.

Flatpaks

Main article: Flatpak

Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-portal-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see flatpak's page on the subject. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.

After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include: 

exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome

This is only needed if they are not started automatically via other means.

Firefox (Flatpak) and/or GTK apps

Disappearing cursor

You may need to get an icon pack and possibly a theme from Pling store and set GTK_THEME environmental variable. Alternatively you can install a theme for all users (search Alpine Linux Packages for *-icon-theme) using apk add.

Missing file picker/cannot download

Go to about:config and set widget.use-xdg-desktop-portal.file-picker to 0.

Nvidia Issues

Main article: NVIDIA

As of Dec 31 2022, Nvidia still doesn't fully support Wayland. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to drm,libinput or x11 (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards (make sure to install libinput first).

See Also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Sway&oldid=27619"