/jay

A Wayland compositor written in rust

Primary LanguageRustGNU General Public License v3.0GPL-3.0

Jay

Jay is a Wayland compositor written and configured in the rust programming language with hot-reload support. Jay offers improved flexibility, configurability, stability, and performance.

screenshot.png

Status

Jay is beta-quality software. For many people it should be possible to use Jay for most of their work. Jay has a small integration test suite but sometimes there are regressions that cause features to break. I'm currently looking for people willing to test Jay, especially on Nvidia hardware.

Working Features

The following features have been implemented and should work:

  • Tiling windows
  • Floating windows
  • Fullscreen
  • Multiple workspaces
  • Multiple monitors
  • Copy/paste including middle-click paste
  • Screenshots
  • Screencasting
  • Keyboard shortcuts
  • Theming
  • Configuration reload
  • XWayland
  • Screensaver (paused during video playback)
  • Notifications (via mako)
  • Video playback with synced audio (via presentation time)
  • Simple games that don't require cursor grabs
  • GPU reset recovery
  • Screen locking
  • Monitor hotplug
  • Fractional scaling
  • Hardware cursors
  • Pointer constraints
  • Selecting the primary device in multi-GPU systems

Missing Features

The following features are known to be missing or broken and will be implemented later:

  • Touch and tablet support
  • Damage tracking (any kind of damage causes a complete re-render currently)

Native library dependencies

Jay is written in rust and will fetch all of its rust dependencies automatically. It is however unavoidable that Jay depends on a number of native libraries:

  • libinput.so: For input event processing.
  • libEGL.so, libGLESv2.so: For OpenGL rendering.
  • libgbm.so: For graphics buffer allocation.
  • libxkbcommon.so: For keymap handling.
  • libudev.so: For device enumeration and hotplug support.
  • libpangocairo-1.0.so: For text rendering.

These libraries are usually available on any Wayland-capable system.

Runtime dependencies

At runtime, Jay depends on the following services being available on the system:

  • An up-to-date linux kernel and graphics drivers: Jay makes aggressive use of linux features and might not work on older systems.
  • XWayland: For XWayland support.
  • Pipewire: For screencasting.
  • A running X server: For the X backend. (Only required if you want to run Jay as an X client.)
  • Logind: For the metal backend. (Only required if you want to run Jay from a TTY.)

Building and Installing

Install the latest stable version of rustc and cargo. Follow the instructions on https://rustup.rs or use the packages provided by your distribution. Note that only the latest stable version is supported.

You can now build Jay using this command:

RUSTC_BOOTSTRAP=1 cargo build --release

The resulting binary will be located at ./target/release/jay.

Alternatively, cargo can also install the binary for you:

RUSTC_BOOTSTRAP=1 cargo install --path .

This will install the binary at $HOME/.cargo/bin/jay. If you have not already done so, you can add $HOME/.cargo/bin to your path.

Running

You can run Jay as a freestanding compositor or as an application under X.

To start Jay as a freestanding compositor switch to a virtual terminal by pressing CTRL-ALT-F2 (or F3, F4, ...) and run

jay run

To start Jay as an X application, execute the same command from a terminal emulator under X.

Before running Jay as a freestanding compositor, you might want to familiarize yourself with the default keyboard shortcuts. In particular, you can quit Jay by typing ALT-q.

Configuration

Jay is configured using a shared library. A good starting point for your own configuration is the default config crate.

  1. Copy this crate to a new directory.
  2. In Cargo.toml
    • Update the path dependency to point to the correct directory.
    • Change the name of the crate to my-jay-config.
  3. Make a useful change to lib.rs.
  4. Build the crate with cargo build.
  5. Move target/debug/libmy_jay_config.so to $HOME/.config/jay/config.so.

CAUTION: A common mistake is to use cp to copy the shared library to the config location. By default, cp will overwrite the file instead of replacing it with a new file. If you do this at runtime, jay will almost certainly crash. Instead use mv to move the file or first delete the old file before using cp.

When you start Jay, you will be able to make use of your useful change. At runtime you can repeat steps 3 to 5 and reload the configuration. By default, the shortcut to reload the configuration is ALT-r.

If you want to see a more elaborate configuration, take a look at my personal configuration.

Screensharing

Jay supports xdg-desktop-portal-wlr but Jay is not currently listed in xdg-desktop-portal-wlr's wlr.portal file. To get screensharing to work, you have to manually edit /usr/share/xdg-desktop-portal/portals/wlr.portal and add jay to the UseIn list.

In the future, Jay will provide a desktop portal itself.

License

Jay is free software licensed under the GNU General Public License v3.0.