arcan(1)

NAME
arcan-wayland - protocol bridge for Wayland support in Arcan

SYNOPSIS
arcan-wayland [OPTIONS]

DESCRIPTION
This tool act as a protocol service that implements the Wayland protocol. It can be used to run Wayland conforming clients, and X clients if Xwayland if installed. You can run it as a persistent service managing multiple clients, or as a 'per application' chain loader.

OPTIONS

-exec binary [args]
    This argument sets the bridge to work in single client mode, and it is the execution mode with the strongest separation between clients. All argument processing after exec will be forwarded to the specified binary.

-xwl
    This enabled X- wayland mode, which spawns an X server (Xwayland) along with a window manager (arcan_xwm) that implements X specific behavior. As some applications radically change their behavior depending on if an X server is available or not, the safest and best option is to pair this with -exec.

-dir /prefix/path
    Setting this argument changes the scratch directory that is used to set up the compartments for each individual client (XDG_RUNTIME_DIR). This defaults to the /tmp directory. It is very important that the backing store for this path is a temporary (memory mapped) filesystem, as the client may use it to allocate and transfer graphics buffers.

-sandbox
    Enable syscall filtering and possibly other sandboxing mechanisms. This is not enabled by default as there is a possibility that changes to the wayland implementation libraries might require features that are blocked, and the user should be actively aware of that..

-defer-release
    This argument is used as 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 will be 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.

-shm-egl
    Normally, shared memory source buffers gets copied and forwarded to the main arcan instance as is. This costs an extra copy, but allows the bridge to 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.

-width px -height px
    Normally, the default output provided to wayland clients will get its values from the initial values presented by the display/outputhints from the server side. These two arguments can be used to force-override those values. This might help work around problems with legacy wl_shell applications that respond poorly to configure events.

-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.

PROTOCOL CONTROL
Wayland is not a single protocol as 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 that are available. 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. 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.

DEBUGGING / TROUBLESHOOTING
Wayland client support and conformance vary wildly, as does the conformance of the bridge interpretation in itself, as the options for testing and verifying protocol behaviors are very limited and the documentation fragmented and incomplete. To assist with debugging wayland client behaviors, we have a number of tools. 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. If you invoke the arcan-wayland bridge with -trace, you can tune which subprotocol implementations that gets 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. 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 as the allocation and deallocation rules and behaviors in Wayland are much too complicated. 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 that sets its output to stderr, which should be the same stderr as that of 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. 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.

EXAMPLES

This example launches a single gtk3-demo session. arcan-wayland -sandbox -shm-egl -exec gtk3-demo This example requires both Xwayland 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.

AUTHOR
Bjorn Stahl <contact at arcan-fe dot com>