Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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	proto-
       col.  It	can be used to run Wayland conforming clients, and  X  clients
       if Xwayland if installed. You can run it	as a persistent	service	manag-
       ing 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	(Xway-
	      land)  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_RUN-
	      TIME_DIR).  This	defaults to the	/tmp directory.	It is very im-
	      portant 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	mecha-
	      nisms. This is not enabled by default as there is	a  possibility
	      that  changes  to	the wayland implementation libraries might re-
	      quire 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 pro-
	      duce 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 dou-
	      ble-buffers internally, client submitted	buffers	 will  be  re-
	      leased 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 dis-
	      play/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 be-
	      havior.

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  dis-
       abled  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  ar-
       can-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 confor-
       mance of	the bridge interpretation in itself, as	the options for	 test-
       ing  and	verifying protocol behaviors are very limited and the documen-
       tation 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 environ-
       ment 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	debug-
       ging 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 vari-
       ous 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>

arcan-wayland			 January 2018			      arcan(1)

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+14.3.quarterly>

home | help