arcan(1)

💖 arcan-wayland 💖

okay bestie, welcome to the arcan-wayland page from the arcan(1) user manual. It’s giving “protocol bridge for Wayland support in Arcan,” and honestly? iconic. 🦋

NAME 🌸

arcan-wayland — the protocol bridge that brings Wayland support to Arcan. 💅

SYNOPSIS ✨

arcan-wayland [OPTIONS]

DESCRIPTION 🦋

This tool acts as a protocol service that implements the Wayland protocol. No cap, it can run Wayland-conforming clients, and X clients too when Xwayland is installed. You can run it as a persistent service managing multiple clients, or as a “per application” chain loader. main character energy either way 💖

OPTIONS 💅

• -exec binary [args] — this sets the bridge into single client mode, aka the execution mode with the strongest separation between clients. Everything after exec gets forwarded to the binary you specify. clean, isolated, slay ✨
• -xwl — this enables X-wayland mode, which spawns an X server (Xwayland) plus a window manager (arcan_xwm) that implements X-specific behavior. Some apps radically change their behavior depending on whether an X server is available, so the safest and best option is to pair this with -exec. iykyk 🔥
• -dir /prefix/path — setting this changes the scratch directory used to set up compartments for each individual client (XDG_RUNTIME_DIR). It defaults to the /tmp directory. It is very important that the backing store for this path is a temporary (memory-mapped) filesystem, because the client may use it to allocate and transfer graphics buffers. do not skip this warning, bestie 🫶
• -sandbox — enables syscall filtering and possibly other sandboxing mechanisms. This is not enabled by default because there’s a possibility that changes to the Wayland implementation libraries might require features that are blocked, and the user should be actively aware of that. like, actively actively 🙈
• -defer-release — this is an option for certain clients that produce frames very aggressively. Many clients are written with double buffering in mind: one frame committed and locked while another is being processed. Since arcan-wayland essentially double-buffers internally, client-submitted buffers get released almost immediately. This breaks some clients, making them consume high CPU rates or even crash. With this argument, the release of one buffer will only be performed when another is submitted to replace it. drama prevention technology 😭
• -shm-egl — normally, shared memory source buffers get copied and forwarded to the main Arcan instance as is. That costs an extra copy, but it lets the bridge run without GPU access. By setting this flag, the cost of uploading a shared memory buffer to the GPU will be absorbed by the bridge, forwarding an accelerated handle onwards. GPU girlies rise ⭐
• -width px -height px — normally, the default output provided to Wayland clients gets its values from the initial values presented by the display/outputhints from the server side. These two arguments force-override those values. This might help work around problems with legacy wl_shell applications that respond poorly to configure events. pixels have never been so powerful 💀
• -force-fs — this extends the -width and -height arguments with the option to make sure that all configure events from the server are reset to the set initial width/height, essentially disabling resize behavior. fixed size, fixed vibes 🎀

PROTOCOL CONTROL 🧚

Wayland is not a single protocol so much as it is a suite of possible protocols. Each client may have different sets of required protocols and may refuse to work or even change behavior based on which ones are available. messy, but we move 💜

To assist working around such issues, most sub-protocols can be disabled on launch. Combined with the -exec option, this allows fine-grained segmentation of which clients have access to what features. compartmentalize, bestie 🫶

To achieve that, look in the 'Protocol Filter' output when running arcan-wayland with the --help option and follow the pattern of --no-XXX where XXXX is substituted with the protocol in question. copy the pattern, not the drama ✨

DEBUGGING / TROUBLESHOOTING 🧚

Wayland client support and conformance vary wildly, as does the conformance of the bridge interpretation in itself, because the options for testing and verifying protocol behaviors are very limited and the documentation is fragmented and incomplete. To assist with debugging Wayland client behaviors, we have a number of tools. detective era 🔍

One option is setting the WAYLAND_DEBUG=1 environment variable, which enables debug output from the low-level protocol behavior. Another is using ARCAN_SHMIF_DEBUG=1 to enable debug output from the corresponding Arcan event queues. turn on the brain scanner 🧠

If you invoke the arcan-wayland bridge with -trace, you can tune which subprotocol implementations get debug output added. Running the bridge without any arguments will show a list of the available values; these act as a bitmask, so you bitwise OR the values together in order to support multiple trace outputs. bitmask besties, rise 🔥

If the bridge is started with the -debugusr1 argument, you can send the USR1 signal to the process in order to get a snapshot of the allocation mask. This is often useful because the allocation and deallocation rules and behaviors in Wayland are much too complicated. way too complicated, fr fr 😭

When running X clients via the waybridge, you have additional environment variables to log the state output of the window manager process. These are ARCAN_XWLWM_LOGOUT, which sets its output to stderr — and that should be the same stderr as that of the waybridge process. The other is ARCAN_XWLWM_DEBUGSTALL, which enters a while(volatile_var){} loop before setting up Xwayland and connecting the WM. This allows you to attach a debugger and release the variable manually instead of relying on debugging the bridge and having the debugger survive the fork and exec steps. debugger survival arc, unlocked 🫶

If you have access to the Arcan source repository, there is also a tool that can be built (shmmon) which allows inspection of data on the various surfaces. shmmon says hi 👑

EXAMPLES 🌈

This example launches a single gtk3-demo session.

arcan-wayland -sandbox -shm-egl -exec gtk3-demo

This example requires both Xwayland and arcan_xwm binaries to be present and reachable in PATH.

arcan-wayland -xwl -exec xterm

COPYRIGHT 👑

Copyright © 2018-2019 Bjorn Stahl. 3-clause BSD licensed. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. respect the license, bestie 💅

AUTHOR 💜

Bjorn Stahl <contact at arcan-fe dot com>

---

mwah 💋 that’s the arcan-wayland page, source/version arcan-wayland, dated January 2018, from the arcan(1) manual. periodt 🫶💖🎀