Sway

From Gentoo Wiki
Jump to: navigation, search
This article is a stub. You can help by expanding it.

Sway (contracted from SirCmpwn's Wayland compositor) is an open-source Wayland compositor that is designed to be compatible with the i3 window manager.

Installation

USE flags

USE flags for gui-wm/sway i3-compatible Wayland window manager

X Enable support for X11 applications (XWayland)
elogind Enable support for rootless session via elogind
fish-completion Enable fish completion support
man Build and install man pages
swaybar Install 'swaybar': sway's status bar component
swaybg Install 'swaybg': allows to set a desktop background image
swayidle Install 'swayidle': idle manager to run commands when user is inactive
swaylock Install 'swaylock': sway's screen locker
swaymsg Install 'swaymsg': tool for communicating with a running sway instance
swaynag Install 'swaynag': shows a message with buttons
systemd Enable use of systemd-specific libraries and features like socket activation or session tracking
tray Enable support for StatusNotifierItem tray specification
wallpapers Install sway's default wallpaper image
zsh-completion Enable zsh completion support

Emerge

root #emerge --ask gui-wm/sway

Configuration

To view all available configuration options:

user $man 5 sway

Files

Each user running sway can edit the default configuration file in order to run a customized sway session. Gentoo stores this file at its default /etc/sway/config location:

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

Terminal emulator

By default the sway configuration file uses the urxvt terminal emulator (found in the x11-terms/rxvt-unicode package). It is a good idea to emerge this terminal emulator so that a terminal will be available once sway is running:

root #emerge --ask x11-terms/rxvt-unicode

Another popular choice is x11-terms/kitty which works natively with Wayland if the KITTY_ENABLE_WAYLAND environment variable is set to 1. Users wanting more a barebone, Wayland native, terminal emulator may want to test out Alacritty. Another very lightweight alternative is st, but it isn't Wayland native.

Taking screenshots

To add screenshot support, use the grim utility (found in the gui-apps/grim package). The abbreviation grim is defined as Grab Images. This utility is tailored to the specifics of the Wayland protocol. In order to install grim, use the following command:

root #emerge --ask gui-apps/grim

To add support for determining the boundaries of the selected screen area, the slurp utility, found in the gui-apps/slurp package, is used in combination with the grim utility. To install slurp, use the command:

root #emerge --ask gui-apps/slurp

Next, edit the configuration file to add support for keyboard shortcuts to perform a screenshot operation.

FILE ~/.config/sway/configSet the keyboard shortcuts for screenshot support
#
# Screen capture
#
set $ps1 Print
set $ps2 Control+Print
set $ps3 Alt+Print
set $ps4 Alt+Control+Print
 
bindsym $ps1 exec grim - | wl-copy
bindsym $ps2 exec grim -g "$(slurp)" - | wl-copy
bindsym $ps3 exec grim $(xdg-user-dir PICTURES)/ps_$(date +"%Y%m%d%H%M%S").png
bindsym $ps4 exec grim -g "$(slurp)" $(xdg-user-dir PICTURES)/ps_$(date +"%Y%m%d%H%M%S").png

Please note that the Print or Ctrl + Print keys combination creates a screenshot in the wl-copy buffer. This allows pasting the image directly from the clipboard, without having to save to a file on disk.

For the Alt + Print or Alt + Ctrl + Print keyboard shortcuts, the method of automatically saving the image file in the Pictures user directory is used.

HiDPI

To adjust sway's rendering for HiDPI displays (4K and above), the name of the display to be adjusted must be obtained. After a sway session is running, issue the following:

user $swaymsg -t get_outputs
Note
The swaymsg USE flag must be enabled for the swaymsg command to be available on the system.

The output statement in the sway configuration file will accept a scale parameter to adjust the scaling of the high resolution display.

Executing sway

OpenRC

If using ConsoleKit (OpenRC), run Sway using:

user $exec ck-launch-session sway

systemd

When using Systemd or Elogind Sway can be launched with:

user $sway

Other

Systems that are configured with neither systemd, elogind, nor ConsoleKit, will need to create a bash script (or use some other means) to set the XDG_RUNTIME_DIR variable.

Note
The instructions below must be followed only if the environment does not define the XDG_RUNTIME_DIR variable (this is usually the case, if systemd/elogind/consolekit are not used).

The environment variable can be defined in the usual configuration files. For example, if Larry the cow (Larry) sets XDG_RUNTIME_DIR variable in his Bash shell's configuration file and he has chosen that the directory will be in /tmp.

FILE /home/larry/.bash_profileSet the XDG_RUNTIME_DIR variable
#!/bin/bash
if test -z "${XDG_RUNTIME_DIR}"; then
    export XDG_RUNTIME_DIR=/tmp/${UID}-runtime-dir
    if ! test -d "${XDG_RUNTIME_DIR}"; then
        mkdir "${XDG_RUNTIME_DIR}"
        chmod 0700 "${XDG_RUNTIME_DIR}"
    fi
fi

With the XDG_RUNTIME_DIR defined, sway can be launched as usual:

user $sway

If issues are encountered check Sway issues on GitHub before contacting the Sway community on IRC (#sway) or opening a new Gentoo bug.

Launching Sway from a script

This method uses a script to forcibly take over a virtual terminal and launch Sway in it. The typical use case is to launch Sway automatically on boot.

Note
Sway is not supposed to be launched this way, the script may need some tunning to work
FILE /usr/sbin/sway_launcherSway Launcher
#!/bin/sh

# Launch sway with a specific user, from a specific Virtual Terminal (vt)
# Two arguments are expected: a username (e.g., larry) and the id of a free vt (e.g., 7)

# prepare the tty for the user. vtX uses /dev/ttyX
chown "$1" "/dev/tty${2}"
chmod 600 "/dev/tty${2}"

# setup a clean environment for the user, take over the target vt, then launch sway
su --login --command "openvt --switch --console ${2} -- sway >\${HOME}/.sway_autolauncher.log 2>&1" "$1"
# this script returns immediately

This script has a few limitations:

  • XDG_RUNTIME_DIR is expected to be defined and valid, see the section above
  • Without the --switch option for openvt, sway will freeze when trying to switch to a different vt (Ctrl+Alt+Fn), whether this is a bug or not is unknown
  • The vt is not cleared when Sway exits, you can do it by calling deallocvt
  • Similarly the tty's owner and mode are not changed back to their default values when Sway exits


Launching this script on boot can be done with the local service

FILE /etc/local.d/sway.startLaunch Sway on boot
#!/bin/sh
sway_launcher larry 7

Usage

All key combinations will be defined in the ~/.config/sway/config configuration file.

The 'logo' key is defined as the $mod value by default. On most keyboards this will be the Windows key.

Movement

Sway has a Vi-like interface. h (left), j (down), k (up), and l (right) can be used for movement.

See man 5 sway-input for more information.

Terminal

The default key combination to open a terminal emulator is $mod+Enter.

See also