FreeBSD Manual Pages
arcan(1) User manual 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 speci- fied 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 de- pending 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_RUN- TIME_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 graph- ics 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 fea- tures 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 in- ternally, client submitted buffers will be released almost immedi- ately. 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/out- puthints 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 pro- tocols. Each client may have different sets of required protocols and may refuse to work or even change behavior based on which ones that are avail- able. To assist working around such issues, most sub- protocols can be disabled on launch. Combined with the -exec option, this allows fine-grained segmen- tation 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 ver- ifying 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 en- ables 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 sub- protocol 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 mul- tiple 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 be- haviors 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 A(C) 2018-2019 Bjorn Stahl. 3-clause BSD licensed. This is free software: you are free to change and redistribute it. There is NO WAR- RANTY, to the extent permitted by law. AUTHOR Bjorn Stahl <contact at arcan-fe dot com> arcan-wayland January 2018 arcan(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | PROTOCOL CONTROL | DEBUGGING / TROUBLESHOOTING | EXAMPLES | COPYRIGHT | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=arcan-wayland&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>