kossLAN/wry
1
0
Fork 0
forked from wry/wry
Code Pull requests Activity

docs: re-organize documentation

Browse source
This commit is contained in:
Julian Orth 2024-04-05 19:05:43 +02:00
parent 1a9b7146fd
commit b03cdaa4b7
6 changed files with 717 additions and 160 deletions
Download patch file Download diff file Expand all files Collapse all files

455
docs/config.md Normal file
View file

@ -0,0 +1,455 @@
# Configuration
Jay can be configured via
- a declarative TOML file or
- a shared library that gets injected into the compositor.
## Shared Library Configuration
This is described in the [rustdoc](https://docs.rs/jay-config) of the configuration crate.
## TOML Configuration
The configuration file is stored under `$HOME/.config/jay/config.toml`.
If you don't have such a file, the default configuration will be used.
The full format of this file is described in the auto-generated file [spec.generated.md](../toml-spec/spec/spec.generated.md).
You can also get auto completion with the auto-generated JSON Schema linked from that document.
The following code block contains the annotated default configuration.
Below that we will describe individual usecases.
```toml
# The keymap that is used for shortcuts and also sent to clients.
keymap = """
xkb_keymap {
xkb_keycodes { include "evdev+aliases(qwerty)" };
xkb_types { include "complete" };
xkb_compat { include "complete" };
xkb_symbols { include "pc+us+inet(evdev)" };
};
"""
# An action that will be executed when the GPU has been initialized.
on-graphics-initialized = { type = "exec", exec = { prog = "mako", privileged = true } }
# Shortcuts that are processed by the compositor.
# The left hand side should be a key, possibly prefixed with modifiers.
# The right hand side should be an action.
[shortcuts]
# The focus-X actions move the keyboard focus to next window on the X.
alt-h = "focus-left"
alt-j = "focus-down"
alt-k = "focus-up"
alt-l = "focus-right"
# The move-X actions move window that has the keyboard focus to the X.
alt-shift-h = "move-left"
alt-shift-j = "move-down"
alt-shift-k = "move-up"
alt-shift-l = "move-right"
# The split-X action places the currently focused window in a container
# and sets the split direction of the container to X.
alt-d = "split-horizontal"
alt-v = "split-vertical"
# The toggle-split action changes the split direction of the current
# container.
alt-t = "toggle-split"
# The toggle-mono action changes whether the current container shows
# a single window or all windows next to each other.
alt-m = "toggle-mono"
# The toggle-fullscreen action toggles the current window between
# windowed and fullscreen.
alt-u = "toggle-fullscreen"
# The focus-parent action moves the keyboard focus to the parrent of
# the currently focused window.
alt-f = "focus-parent"
# The close action requests the currently focused window to close.
alt-shift-c = "close"
# The toggle-floating action changes the currently focused window between
# floating and tiled.
alt-shift-f = "toggle-floating"
# All actions above are so-called simple actions that are identified by
# a string. More complex actions take parameters and are written as a table.
# For example, the exec action spawns an application and has the exec field
# that describes how to spawn the application.
Super_L = { type = "exec", exec = "alacritty" }
alt-p = { type = "exec", exec = "bemenu-run" }
# The quit action terminates the compositor.
alt-q = "quit"
# The reload-config-toml action reloads the TOML configuration file.
alt-shift-r = "reload-config-toml"
# The switch-to-vt action switches to a different virtual terminal.
ctrl-alt-F1 = { type = "switch-to-vt", num = 1 }
ctrl-alt-F2 = { type = "switch-to-vt", num = 2 }
ctrl-alt-F3 = { type = "switch-to-vt", num = 3 }
ctrl-alt-F4 = { type = "switch-to-vt", num = 4 }
ctrl-alt-F5 = { type = "switch-to-vt", num = 5 }
ctrl-alt-F6 = { type = "switch-to-vt", num = 6 }
ctrl-alt-F7 = { type = "switch-to-vt", num = 7 }
ctrl-alt-F8 = { type = "switch-to-vt", num = 8 }
ctrl-alt-F9 = { type = "switch-to-vt", num = 9 }
ctrl-alt-F10 = { type = "switch-to-vt", num = 10 }
ctrl-alt-F11 = { type = "switch-to-vt", num = 11 }
ctrl-alt-F12 = { type = "switch-to-vt", num = 12 }
# The show-workspace action switches to a workspace. If the workspace is not
# currently being used, it is created on the output that contains the pointer.
alt-F1 = { type = "show-workspace", name = "1" }
alt-F2 = { type = "show-workspace", name = "2" }
alt-F3 = { type = "show-workspace", name = "3" }
alt-F4 = { type = "show-workspace", name = "4" }
alt-F5 = { type = "show-workspace", name = "5" }
alt-F6 = { type = "show-workspace", name = "6" }
alt-F7 = { type = "show-workspace", name = "7" }
alt-F8 = { type = "show-workspace", name = "8" }
alt-F9 = { type = "show-workspace", name = "9" }
alt-F10 = { type = "show-workspace", name = "10" }
alt-F11 = { type = "show-workspace", name = "11" }
alt-F12 = { type = "show-workspace", name = "12" }
# The move-to-workspace action moves the currently focused window to a workspace.
alt-shift-F1 = { type = "move-to-workspace", name = "1" }
alt-shift-F2 = { type = "move-to-workspace", name = "2" }
alt-shift-F3 = { type = "move-to-workspace", name = "3" }
alt-shift-F4 = { type = "move-to-workspace", name = "4" }
alt-shift-F5 = { type = "move-to-workspace", name = "5" }
alt-shift-F6 = { type = "move-to-workspace", name = "6" }
alt-shift-F7 = { type = "move-to-workspace", name = "7" }
alt-shift-F8 = { type = "move-to-workspace", name = "8" }
alt-shift-F9 = { type = "move-to-workspace", name = "9" }
alt-shift-F10 = { type = "move-to-workspace", name = "10" }
alt-shift-F11 = { type = "move-to-workspace", name = "11" }
alt-shift-F12 = { type = "move-to-workspace", name = "12" }
```
### Configuring Keymaps and Repeat Rates
The keymap can be configured via the top-level `keymap` field.
```toml
keymap = """
xkb_keymap {
xkb_keycodes { include "evdev+aliases(qwerty)" };
xkb_types { include "complete" };
xkb_compat { include "complete" };
xkb_symbols { include "pc+us+inet(evdev)" };
};
"""
```
The format is described in the ArchWiki: https://wiki.archlinux.org/title/X_keyboard_extension
If you want to use multiple keymaps, you can assign names to them:
```toml
keymap.name = "laptop"
[[keymaps]]
name = "laptop"
path = "./laptop-keymap.xkb"
[[keymaps]]
name = "external"
path = "./external-keymap.xkb"
```
Such paths are relative to the configuration file.
You can also write the map inline in this format:
```toml
[[keymaps]]
name = "external"
map = "..."
```
If you want to switch the keymap with a shortcut, use the `set-keymap` action:
```toml
[shortcuts]
alt-j = { type = "set-keymap", keymap.name = "laptop" }
alt-k = { type = "set-keymap", keymap.name = "external" }
```
The keyboard repeat rate is configured via the top-level `repeat-rate` field.
```toml
repeat-rate = { rate = 25, delay = 250 }
```
You can change this at runtime with the `set-repeat-rate` action:
```toml
[shortcuts]
alt-x = { type = "set-repeat-rate", rate = { rate = 25, delay = 250 } }
```
Note that you can change all of this from the command line with the `jay input` command.
### Configuring Shortcuts
Shortcuts are configured in the top-level `shortcuts` table.
```toml
[shortcuts]
alt-h = "focus-left"
```
The left-hand side should be a key that can optionally be prefixed with modifiers.
The right-hand side should be an action.
See [spec.generated.md](../toml-spec/spec/spec.generated.md) for a full list of actions.
### Running Multiple Actions
In every place that accepts an action, you can also run multiple actions by wrapping them
in an array:
```toml
[shortcuts]
alt-h = ["focus-left", "focus-up"]
```
### Spawning Applications
You can spawn applications by using the `exec` action:
```toml
Super_L = { type = "exec", exec = "alacritty" }
```
The `exec` field can be either a string, an array of strings, or a table.
When a string is used, it should be the name of the application.
When an array is used, it should be the name of the application followed by arguments.
```toml
Super_L = { type = "exec", exec = ["alacritty", "-e", "date"] }
```
When a table is used, you can additionally specify
- environment variables to pass to the application,
- whether the application should have access to privileged protocols.
See the specification for more details.
### Running an Action at Startup
If you want to run an action at startup, you can use the top-level `on-graphics-initialized`
field:
```toml
on-graphics-initialized = { type = "exec", exec = { prog = "mako", privileged = true } }
```
### Setting Environment Variables
You can set environment variables with the the top level `env` table.
```toml
[env]
GTK_THEME = "Adwaita:dark"
```
These environment variables are passed to all applications started afterwards.
You can also use the `set-env` action to modify these variables:
```toml
[shortcuts]
alt-l = { type = "set-env", env.GTK_THEME = "Adwaita:dark" }
```
The `unset-env` action is similar.
See the specification for more details.
### Using a Status Program
You can configure a status program with the top-level `status` table.
```toml
[status]
format = "i3bar"
exec = "i3status"
```
The `format` field specifies the format used by the status program.
Possible values are `plain`, `pango`, and `i3bar`.
The `exec` field specifies how to start the status program.
Note that i3status will not automatically use i3bar format when started this way.
You have to explicitly opt into i3bar format in your i3status configuration.
See the specification for more details.
### Configuring Idle Timeout and Actions
You can configure the idle timeout with the top-level `idle` table.
```toml
idle.minutes = 10
```
If you want to lock the screen when this timeout happens, you can use the `on-idle` table.
```toml
on-idle = { type = "exec", exec = { prog = "swaylock", privileged = "true" } }
```
See the specification for more details.
### Configuring GPUs
You can configure GPUs with the top-level `drm-devices` array.
```toml
[[drm-devices]]
name = "dedicated"
match = { pci-vendor = 0x1002, pci-model = 0x73ff }
[[drm-devices]]
name = "integrated"
match = { pci-vendor = 0x1002, pci-model = 0x164e }
gfx-api = "OpenGl"
```
For each device, you can configure the following properties:
- Whether direct scanout is enabled on monitors connected to this device.
- Which API to use for this device (OpenGL or Vulkan).
You can assign names to these device to refer to them elsewhere.
The `match` field is used to identify the device.
Unless you have two identical graphics cards installed, using the pci-vendor and model
fields is usually the best choice.
You can get these values by running `jay randr`.
You can select the device used for rendering the desktop with the top-level `render-device` field.
```toml
render-device.name = "dedicated"
```
You can modify the render device and configure GPUs at runtime with the `set-render-device`
and `configure-drm-device` actions.
You can use the top-level `gfx-api` field to set the default API used (unless overwritten for specific device).
```toml
gfx-api = "Vulkan"
```
See the specification for more details.
### Configuring Monitors
You can configure monitors with the top-level `outputs` field.
```toml
[[outputs]]
name = "left"
match.serial-number = "33K03894SL0"
x = 0
y = 0
[[outputs]]
name = "right"
match.serial-number = "ETW1M02062SL0"
x = 1920
y = 0
```
For each output, you can configure the following properties:
- The x, y coordinates in global compositor space.
- The scale to use for the monitor.
- The transformation to apply to the content (rotation, mirroring).
- The mode to use for the monitor.
You can query the available modes and modify these properties from the command line with
the `jay randr` command.
The `match` field selects the monitors the configuration applies to.
The serial number is usually a good unique identifier.
You can assign a name to monitors to refer to them in other places.
You can use the `configure-output` action to change this configuration at runtime.
See the specification for more details.
### Configuring Connectors
Connectors are the physical ports at the back of your GPU.
You can configure them with the top-level `connectors` array.
```toml
[[connectors]]
name = "eDP-1"
enabled = false
```
Currently you can only use this to disable or enable connectors.
This is useful to disable the internal monitor of a laptop when the laptop is closed.
You can use the `configure-connector` action to change this configuration at runtime.
See the specification for more details.
### Configuring Input Devices
You can configure input devices with the top-level `inputs` array.
```toml
[[inputs]]
tag = "mice"
match.is-pointer = true
left-handed = true
transform-matrix = [[0.35, 0], [0, 0.35]]
tap-enabled = true
```
For each input device you can configure the following properties:
- The libinput acceleration profile.
- The libinput acceleration speed.
- The libinput tap setting.
- The libinput tap-drag setting.
- The libinput tap-drag-lock setting.
- The libinput left-handed setting.
- The libinput natural-scrolling setting.
- The number of pixels to scroll per scroll-wheel dedent.
- A transformation matrix to apply to relative movements.
You can inspect and modify these settings from the command line with the `jay input` command.
The `match` field selects the input devices to operate on.
You can assign a `tag` to input devices to refer to them elsewhere.
You can use the `configure-input` action to change these settings at runtime.
See the specification for more details.
# Theming
You can configure the colors, sizes, and fonts used by the compositor with the top-level `theme` table.
```toml
[theme]
bg-color = "#ff000"
```
See the specification for more details.

161
docs/features.md Normal file
View file

@ -0,0 +1,161 @@
# Features
## Configuration
Jay can be configured via
- a declarative TOML file or
- a shared library that gets injected into the compositor.
See [config.md](config.md) for more details.
## i3 Look and Feel
Jay's appearance is based on the default i3 look and feel.
Colors, sizes, and fonts can be customized.
## Stability
Jay has been stable for a long time.
Crashes and incorrect behavior in released versions are very rare.
Jay also aims to be forward and backward compatible for existing setups, allowing you to
upgrade or downgrade the compositor without having to adjust your configuration.
There is a small but growing integration test suite that is used to ensure this.
## CLI
Jay has a CLI that can be used to configure the compositor at runtime.
```
~$ jay
A wayland compositor
Usage: jay [OPTIONS] <COMMAND>
Commands:
run Run the compositor
generate-completion Generate shell completion scripts for jay
log Open the log file
set-log-level Sets the log level
quit Stop the compositor
unlock Unlocks the compositor
screenshot Take a screenshot
idle Inspect/modify the idle (screensaver) settings
run-privileged Run a privileged program
seat-test Tests the events produced by a seat
portal Run the desktop portal
randr Inspect/modify graphics card and connector settings
input Inspect/modify input settings
help Print this message or the help of the given subcommand(s)
Options:
--log-level <LOG_LEVEL> The log level [default: info] [possible values: trace, debug, info, warn, error]
-h, --help Print help
```
## Multi-Monitor Support
Jay can be used with multiple monitors with hot-plug and hot-unplug support.
When a monitor is unplugged, all workspaces are automatically moved one of the remaining
monitors.
When the monitor is plugged in again, these workspaces are restored.
## Multi-GPU Support
Jay can be used with multiple GPUs and monitors connected to different GPUs.
One GPU is always used for rendering the desktop.
You can change this GPU at runtime.
## Screen Sharing
Jay supports screen sharing via xdg-desktop-portal.
## Screen Locking
Jay can automatically lock your screen and disable outputs after inactivity.
## Notifications
Jay supports the zwlr_layer_shell_v1 protocol used by notification daemons.
## Fractional Scaling
Jay supports per-monitor fractional scaling.
## OpenGL and Vulkan
Jay can use either OpenGL or Vulkan for rendering.
Vulkan offers better performance and memory usage but OpenGL is still provided for
older hardware.
You can change the API at runtime without restarting the compositor.
## Explicit Sync
Jay supports explicit sync for compatibility with Nvidia hardware.
## Clipboard Managers
Jay supports clipboard managers via `zwlr_data_control_manager_v1`.
## Privilege Separation
Jay splits protocols into unprivileged and privileged protocols.
By default, applications only have access to unprivileged protocols.
You can explicitly opt into giving applications access to privileged protocols via the Jay CLI or shortcuts.
## Protocol Support
Jay supports the following wayland protocols:
| Global | Version | Privileged |
|-----------------------------------------|:-----------------|------------|
| ext_foreign_toplevel_list_v1 | 1 | Yes |
| ext_idle_notifier_v1 | 1 | Yes |
| ext_session_lock_manager_v1 | 1 | Yes |
| org_kde_kwin_server_decoration_manager | 1 | |
| wl_compositor | 6[^no_touch] | |
| wl_data_device_manager | 3 | |
| wl_drm | 2 | |
| wl_output | 4 | |
| wl_seat | 9 | |
| wl_shm | 2 | |
| wl_subcompositor | 1 | |
| wp_content_type_manager_v1 | 1 | |
| wp_cursor_shape_manager_v1 | 1 | |
| wp_fractional_scale_manager_v1 | 1 | |
| wp_linux_drm_syncobj_manager_v1 | 1 | |
| wp_presentation | 1 | |
| wp_single_pixel_buffer_manager_v1 | 1 | |
| wp_tearing_control_manager_v1 | 1[^no_tearing] | |
| wp_viewporter | 1 | |
| xdg_activation_v1 | 1 | |
| xdg_toplevel_drag_manager_v1 | 1 | |
| xdg_wm_base | 6 | |
| zwlr_data_control_manager_v1 | 2 | Yes |
| zwlr_layer_shell_v1 | 4[^no_exclusive] | Yes |
| zwlr_screencopy_manager_v1 | 3 | Yes |
| zwp_idle_inhibit_manager_v1 | 1 | |
| zwp_linux_dmabuf_v1 | 5 | |
| zwp_pointer_constraints_v1 | 1 | |
| zwp_primary_selection_device_manager_v1 | 1 | |
| zwp_relative_pointer_manager_v1 | 1 | |
| zxdg_decoration_manager_v1 | 1 | |
| zxdg_output_manager_v1 | 3 | |
[^no_touch]: Touch input is not supported.
[^no_tearing]: Tearing screen updates are not supported.
[^no_exclusive]: Exclusive zones are not supported.
## Missing Features
The following features are currently not supported but might get implemented in the future:
- Fine-grained damage tracking.
- Touch support.
- Tablet support.
- Tearing updates of fullscreen games.

76
docs/setup.md Normal file
View file

@ -0,0 +1,76 @@
# Building
## Compile-time Dependencies
The following libraries must be installed before compiling Jay:
- libinput.so
- libgbm.so
- libxkbcommon.so
- libudev.so
- libpangocairo-1.0.so
You must also have a C compiler (GCC or Clang) and the latest version of rust installed.
You can install rust with [rustup](https://rustup.rs/).
## Runtime Dependencies
Most of these dependencies are optional and will enable additional features.
- Linux 6.7: Required for explicit sync.
- Xwayland: Required for running X applications.
- Pipewire: Required for screen sharing.
- logind (part of systemd): Required when running Jay from a virtual terminal.
- libEGL.so and libGLESv2.so: Required for the OpenGL renderer.
- libvulkan.so: Required for the Vulkan renderer.
Note that Jay will not work if neither the OpenGL nor the Vulkan renderer are available.
## Compiling
To compile the latest stable version of Jay, run
```
cargo install --locked jay-compositor
```
This will install Jay under `$HOME/.cargo/bin/jay`.
If you want to use the latest version from git, run
```
cargo install --locked --git https://github.com/mahkoh/jay.git jay
```
If you only want to build Jay without installing it, run the following command from within this repository:
```
cargo build --release
```
The binary is then available under `./target/release/jay`.
# Setup
## Configuration
See [config.md](./config.md).
## Screen Sharing
This step is only required to enable screen sharing.
1. Copy `../etc/jay.portal` to `/usr/share/xdg-desktop-portal/portals/jay.portal`.
2. Copy `../etc/jay-portals.conf` to `/usr/share/xdg-desktop-portal/jay-portals.conf`.
Then restart `xdg-deskop-portal`.
# Running
1. Switch to a virtual terminal by pressing `ctrl-alt-F2` (or F3, F4, ...).
2. Run `jay run`.
If you have not yet changed the default configuration, you can
- quit Jay by pressing `alt-q`,
- start Alacritty by pressing the left Windows key.