River

This page contains changes which are not marked for translation.

This article is a stub. Please help out by expanding it - how to get started.

Resources

River is a dynamic tiling wlroots-based Wayland compositor written in Zig with flexible runtime configuration, inspired by dwm and bspwm.

Installation

USE flags

The following USE flags are available:

~amd64, test

Emerge

River is currently only available in the wayland-desktop ebuild repository.

If the overlay is not activated, run:

root #

eselect repository enable wayland-desktop

root #

emaint sync -r wayland-desktop

After activating the overlay, install by:

root #emerge --ask gui-wm/river

Configuration

River is mainly configured through the riverctl function. To see documentation for river and configuration options:

user $man river

user $man riverctl

Layouts are managed by an external program. The simple rivertile is installed along with river. To see configuration options:

user $man rivertile

A list of alternative layout managers, implementing interesting other layouts, is available at [1].

Files

River starts by executing the init file. By default, river will look for the init file at $XDG_CONFIG_HOME/river/init. If $XDG_CONFIG_HOME is not set, river will search for the init file at ~/.config/river/init. Make sure to create an init file before running river. A default is provided by the authors at [2].

Per the authors, the init file can be any executable script, not just shell scripts. See an example written in lua5.4 [3].

Terminal emulator

River does not have a recommended terminal emulator. The default configuration uses foot:

gui-apps/foot

Other Wayland-native terminal emulators include Alacritty x11-terms/alacritty, and Kitty x11-terms/kitty which work natively with Wayland if the KITTY_ENABLE_WAYLAND environment variable is set to 1.

Status bar

River does not have a built-in status bar. Waybar has modules for showing river mode, tags, windows, and layout [4]:

root #emerge --ask gui-apps/waybar

The authors also recommended the following status bars:

yambar: gui-apps/waybar

levee: [5]

i3bar-river: [6]

Brightness

dev-libs/light can be used to adjust backlight and brightness. Here is an example config:

FILE ~/.config/river/initSet the keyboard shortcuts for screen brightness support

riverctl map $mode None XF86MonBrightnessUp   spawn 'light -A 5'
riverctl map $mode None XF86MonBrightnessDown spawn 'light -U 5'

Warning
The light project was orphaned as of March 8th 2023 [7] and the repository no longer exists. As an alternative, app-misc/brightnessctl::guru could be used to adjust the brightness.

Sound volume

The following configuration can be used for changing sound volume with amixer:

FILE ~/.config/river/initSet the keyboard shortcuts to change sound volume

riverctl map $mode None XF86AudioRaiseVolume  spawn 'amixer set "Master" 10%+'
riverctl map $mode None XF86AudioLowerVolume  spawn 'amixer set "Master" 10%-'
riverctl map $mode None XF86AudioMute         spawn 'amixer set "Master" toggle'

Alternatively, if pulseaudio is being used, the following configuration should also work:

FILE ~/.config/river/initSet the keyboard shortcuts to change sound volume

riverctl map $mode None XF86AudioRaiseVolume  spawn 'pactl set-sink-volume @DEFAULT_SINK@ +5%'
riverctl map $mode None XF86AudioLowerVolume  spawn 'pactl set-sink-volume @DEFAULT_SINK@ -5%'

Taking screenshots

See the Sway article for more information.

Setting a wallpaper

The wallpaper can be set with gui-apps/swaybg with a command like this:

FILE ~/.config/river/initSetting the wallpaper

swaybg -m fill -i /home/larry/wallpapers/Awesome_Gentoo_Wallpaper.png &

Executing river

River can be started from a tty or a terminal with:

user $dbus-run-session river

Usage

Configurations and key bindings

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

Note that river does not currently support reloading the configuration. Instead, configurations can be changed on-the-fly by typing the corresponding riverctl command in a terminal, while permanent configurations can be changed via the init file.

Tags

River uses a dwm-inspired tags system for ordering and grouping windows to outputs. This system is superficially similar to the workspace system in most other WMs/Wayland compositors but are quite different.

Rather than assigning each window to a workspace, each window is assigned one or more tags as one of its properties. Every window and every output has 32 tags, which can either be on or off.

The following is heavily copy-pasted from [8]:

To determine which windows should be currently displayed on an output, river loops through all windows and checks if any of its active tags match an active tag of the output. If there is a match, the window will be displayed. This system allows both windows and outputs to have multiple active tags simultaneously, which is what makes tags vastly more powerful than the workspaces of other compositors.

River allows both setting and toggling the tags of windows and outputs. Setting tags provides "on or off" information for each tag as a 32-bit unsigned integer to overwrite the previous value; toggling also provides river with the same 32-big unsigned integer, but instead of overwriting, river will toggle the matching tag of the window or output.

For example: Imagine you have a text editor on tag 1, a terminal where you are compiling the code on tag 2 and documentation on tag 3. While you are writing the codebase, you are on tag 1. If you want to reference the documentation, you can toggle tag 3 to have both the editor and the docs side-by-side. Now you want to compile, so you switch to tag 2; now only the terminal is on your screen. You compile but notice you have an error. You toggle tag 1 and now have your editor and your terminal with your compiler error side-by-side, allowing you to quickly find the bug. Compiling succeeds, so you toggle tag 2 and only your editor remains on the screen.

Recommended software

Besides the recommended terminal emulators and status bars as mentioned above, the authors also summarized various other recommended softwares here [9].

Troubleshooting

Please review the river wiki for FAQs and other issues [10].

Additional comments from editor(s)

Make sure any autostart programs/scripts are defined at the beginning of the init file. Commands defined at the very end of the init file may not be run upon startup.