river

[mirror] A non-monolithic Wayland compositor

3,864

160

3,864

View on GitHub

Top Related Projects

Hyprland

31,959

Hyprland is an independent, highly customizable, dynamic tiling Wayland compositor that doesn't sacrifice on its looks.

labwc

2,320

A Wayland window-stacking compositor

wayfire

2,880

A modular and extensible wayland compositor

bspwm

8,132

A tiling window manager based on binary space partitioning

Quick Overview

River is a dynamic tiling Wayland compositor for Linux and FreeBSD. It aims to be simple, flexible, and visually pleasing, offering a minimalist approach to window management. River is designed for users who prefer a keyboard-driven workflow and customizable layouts.

Pros

Highly customizable through a simple configuration language
Lightweight and efficient, with minimal resource usage
Supports multiple monitors and flexible layout system
Active development and community support

Cons

Steep learning curve for users new to tiling window managers
Limited GUI configuration options, primarily configured through text files
May not be suitable for users who prefer traditional stacking window managers
Some advanced features may require additional scripting or external tools

Getting Started

To get started with River, follow these steps:

Install River on your system:

# For Arch Linux
sudo pacman -S river

# For Debian/Ubuntu
sudo apt install river

Create a basic configuration file:

mkdir -p ~/.config/river
touch ~/.config/river/init
chmod +x ~/.config/river/init

Add some basic configuration to ~/.config/river/init:

#!/bin/sh

# Set background color
riverctl background-color 0x002b36

# Set keyboard repeat rate
riverctl set-repeat 50 300

# Set mod key to Super (Windows key)
riverctl map normal Super Return spawn foot

# Exit River
riverctl map normal Super+Shift Q exit

Start River from your display manager or add exec river to your ~/.xinitrc file.

For more detailed configuration options and usage instructions, refer to the official River documentation.

Competitor Comparisons

sway

16,133

i3-compatible Wayland compositor

Pros of Sway

More mature and feature-rich project with a larger user base
Extensive documentation and community support
Compatible with i3 configuration files, making migration easier

Cons of Sway

Larger codebase, potentially more complex to contribute to
Less flexible in terms of customization compared to River
Tied to the i3 paradigm, which may not suit all users

Code Comparison

Sway (C):

struct sway_container *container_create(struct sway_view *view) {
    struct sway_container *c = calloc(1, sizeof(struct sway_container));
    if (!c) {
        return NULL;
    }
    c->view = view;
    return c;
}

River (Zig):

pub fn create(self: *Self, view: *View) !*Output {
    const output = try self.allocator.create(Output);
    errdefer self.allocator.destroy(output);
    output.* = Output{
        .view = view,
    };
    return output;
}

Both projects implement Wayland compositors, but River is written in Zig and aims for a more minimal, customizable approach. Sway, written in C, closely follows the i3 window manager's design and functionality. River's code tends to be more concise due to Zig's modern features, while Sway's C codebase is more traditional and verbose.

Hyprland

31,959

Hyprland is an independent, highly customizable, dynamic tiling Wayland compositor that doesn't sacrifice on its looks.

Pros of Hyprland

More feature-rich and customizable, with extensive configuration options
Smoother animations and better performance on high-refresh-rate displays
Active development with frequent updates and new features

Cons of Hyprland

Higher system resource usage due to its feature set
Steeper learning curve for configuration and customization
Less stable compared to River, as it's still in active development

Code Comparison

River configuration example:

map {
    normal Super+J focus-view next
    normal Super+K focus-view previous
    normal Super+Return spawn foot
}

Hyprland configuration example:

bind = SUPER, J, cyclenext
bind = SUPER, K, cyclenext, prev
bind = SUPER, Return, exec, foot

Both River and Hyprland are Wayland compositors, but they differ in their approach and feature set. River focuses on simplicity and stability, while Hyprland aims for a more feature-rich and customizable experience. River uses a more traditional configuration syntax, while Hyprland adopts a more modern and flexible approach. Ultimately, the choice between the two depends on the user's preferences and system requirements.

labwc

2,320

A Wayland window-stacking compositor

Pros of labwc

Lightweight and fast Wayland compositor with Openbox-like configuration
Supports traditional stacking window management
Easier transition for users coming from X11 environments

Cons of labwc

Less flexible tiling options compared to River
Smaller community and ecosystem

Code Comparison

labwc (C):

static void
view_move(struct view *view, int x, int y)
{
    view->x = x;
    view->y = y;
    wlr_scene_node_set_position(&view->scene_tree->node, x, y);
}

River (Zig):

pub fn move(self: *View, x: i32, y: i32) void {
    self.x = x;
    self.y = y;
    self.scene_node.setPosition(x, y);
}

Both projects implement similar functionality for moving views, but River uses Zig while labwc uses C. River's code is more concise due to Zig's modern syntax, while labwc follows a more traditional C style.

wayfire

2,880

A modular and extensible wayland compositor

Pros of Wayfire

More feature-rich and customizable out of the box
Offers a plugin system for extending functionality
Provides a more traditional desktop environment experience

Cons of Wayfire

Higher resource usage due to more features and effects
Steeper learning curve for configuration and customization
Less minimalist approach compared to River

Code Comparison

River configuration (example):

map {
    modifiers = {"Super"},
    key = "Return",
    command = "foot"
}

Wayfire configuration (example):

[key-bindings]
terminal = <super> KEY_ENTER

[command]
terminal = foot

Both River and Wayfire are Wayland compositors, but they target different user preferences. River focuses on simplicity and minimalism, while Wayfire aims for a more feature-rich and customizable experience. River uses a Lua-based configuration, whereas Wayfire uses an INI-style format. Wayfire's plugin system allows for more extensive customization, but it may come at the cost of increased complexity and resource usage. River, on the other hand, provides a more streamlined and lightweight approach to window management.

i3

10,193

A tiling window manager for X11

Pros of i3

Mature and stable project with a large user base and extensive documentation
Highly customizable with a powerful configuration system
Supports both floating and tiling window management

Cons of i3

Limited to X11, no Wayland support
Less modern design compared to newer window managers
Steeper learning curve for new users

Code Comparison

i3 (C):

static void
tree_render(Con *con) {
    if (con->type == CT_ROOT)
        return;

    /* Render this container */
    render_con(con);
}

River (Zig):

pub fn renderOutput(self: *Self) void {
    const output = self.output;
    const wlr_output = output.wlr_output;

    var render = self.render_data.base.render orelse return;
    render.renderOutput(output);
}

Both projects use different programming languages and approaches to rendering. i3 uses C and focuses on rendering individual containers, while River uses Zig and handles rendering at the output level. River's code appears more modern and takes advantage of Zig's features, while i3's code is more traditional C.

bspwm

8,132

A tiling window manager based on binary space partitioning

Pros of bspwm

More mature and stable project with a larger user base
Extensive documentation and community support
Highly customizable through external scripts and tools

Cons of bspwm

Written in C, which may be less accessible for some contributors
Lacks native Wayland support, limiting its future-proofing

Code Comparison

bspwm (C):

void
monitor_focus(monitor_t *m)
{
    if (mon == m)
        return;
    mon = m;
    if (m->desk != NULL)
        desk = m->desk;
}

River (Zig):

pub fn focus(self: *Self) void {
    if (self == focused_output) return;
    focused_output = self;
    if (self.active_workspace) |workspace| {
        workspace.focus();
    }
}

Both projects are window managers, but River is designed for Wayland while bspwm is for X11. River is written in Zig, a newer language that aims to be more memory-safe and easier to use than C. bspwm has a longer history and more established ecosystem, while River represents a more modern approach to window management. The code snippets show similar functionality for focusing monitors/outputs, with River's implementation being slightly more concise due to Zig's syntax.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Overview

River is a non-monolithic Wayland compositor. Unlike other Wayland compositors, river does not combine the compositor and window manager into one program. Instead, users can choose any window manager implementing the river-window-management-v1 protocol.

There is a list of window managers implementing the river-window-management-v1 protocol on our wiki.

If you are looking for the old dynamic tiling version of river, see river-classic.

Features

River defers all window management policy to a separate window manager implementing the river-window-management-v1 protocol. This includes window position/size, pointer/keyboard bindings, focus management, window decorations, desktop shell graphics, and more.

River itself provides frame perfect rendering, good performance, support for many Wayland protocol extensions, robust Xwayland support, the ability to hot-swap window managers, and more.

Motivation

Why split the window manager to a separate process? I aim to:

Significantly lower the barrier to entry for writing a Wayland window manager.
Allow implementing Wayland window managers in high-level garbage collected languages without impacting compositor performance and latency.
Allow hot-swapping between window managers without restarting the compositor and all Wayland programs.
Promote diversity and experimentation in window manager design.

Current Status

The first release supporting the river-window-management-v1 protocol will be 0.4.0. The protocol is implemented on river's main branch and is already robust/feature complete enough for me to use as my daily driver. There are however missing features that need to be implemented before the 0.4.0 release, for example keyboard layout configuration.

Currently the only documentation for the river-window-management-v1 protocol is the protocol specification itself. While this is all developers comfortable with writing Wayland clients should need, I'd like to add some more beginner-friendly documentation including a well-commented example window manager before the 0.4.0 release.

I would also like to get more feedback on the river-window-management-v1 protocol before the 0.4.0 release. If you are working on a window manager and have questions/feedback I'd love to hear from you!

With regards to protocol stability, my goal is to never make a backwards incompatible change and stay at v1 forever. I've been iterating on this protocol since April 2023 and am quite confident in the design and extensibility of the current protocol.

If everything goes well with the 0.4.0 release, I expect the following non-bugfix release to be river 1.0.0. After river 1.0.0, all backwards incompatible changes will be strictly avoided.

Building

Note: If you are packaging river for distribution, see PACKAGING.md.

To compile river first ensure that you have the following dependencies installed. The "development" versions are required if applicable to your distribution.

zig 0.15
wayland
wayland-protocols
wlroots 0.19
xkbcommon
libevdev
pixman
pkg-config
scdoc (optional, but required for man page generation)

Then run, for example:

zig build -Doptimize=ReleaseSafe --prefix ~/.local install

To enable Xwayland support pass the -Dxwayland option as well. Run zig build -h to see a list of all options.

Usage

River can either be run nested in an X11/Wayland session or directly from a tty using KMS/DRM. Simply run the river command.

On startup river will run an executable file at $XDG_CONFIG_HOME/river/init if such an executable exists. If $XDG_CONFIG_HOME is not set, ~/.config/river/init will be used instead.

Usually this executable is a shell script which starts the user's window manager and any other long-running programs.

For complete documentation see the river(1) man page.

Donate

If my work on river adds value to your life and you'd like to support me financially you can find donation information here.

Licensing

This project follows the REUSE Specification, all files have SPDX copyright and license information.

In overview:

River's source code is released under the GPL-3.0-only license.
River's Wayland protocols are released under the MIT license.
River's logo and documentation are released under the CC-BY-SA-4.0 license.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Getting Started

Competitor Comparisons

Pros of Sway

Cons of Sway

Code Comparison

Pros of Hyprland

Cons of Hyprland

Code Comparison

Pros of labwc

Cons of labwc

Code Comparison

Pros of Wayfire

Cons of Wayfire

Code Comparison

Pros of i3

Cons of i3

Code Comparison

Pros of bspwm

Cons of bspwm

Code Comparison

Convert designs to code with AI

README

Overview

Links

Features

Motivation

Current Status

Building

Usage

Donate

Licensing

Top Related Projects

Convert designs to code with AI