[question] Documentation for writing a weston shell?

[Pekka Paalanen]

On Sun, 9 Jun 2019 16:33:28 +0200
Leon Plickat <leonhenrik.plickat at stud.uni-goettingen.de> wrote:

> I am interested in creating a wayland desktop by writing a shell for weston. I
> have however not found any documentations about this and I hope this is the
> correct place to ask a few questions.
> 
> 'notes.txt' as well as weston(1) mention weston shells consisting of two part:
> A plugin and a client. Looking at the code of the provided example shells the
> client is apparently  launched by the plugin. The plugin simply provides
> functions for the function-pointers from 'struct weston_desktop_api' in
> 'libweston-desktop.h' while the client is a mostly self-contained program. I
> believe the plugin is responsible for the window management, handling keybinds
> and launching the client, while the client draws UI elements such as panels or
> buttons and creates a background surface (and therefore also sets the wallpaper)
> which will then be handled by the plugin.
> 
> Are these assumptions correct?

Hi Leon,

you are spot on! That is how it works in Weston.

Unfortunately any docs are indeed not written. There is a recent effort
to get a doc framework into place:
https://gitlab.freedesktop.org/wayland/weston/merge_requests/182 . That
could be extended with shell docs as well.

> And what is the exact purpose of the plugin and
> the client?

Pretty much what you guessed already.

Plugin:
- window management and policy
- implementing the shell Wayland protocol extensions through
  libweston-desktop

Helper client:
- anything that needs drawing, e.g. wallpaper, panel, lock screen
- the desktop GUI, it could use a proper GUI toolkit like GTK
- providing fallback cursors (part of the GUI responsibility) in case a
  client is not responsive

This all from the top of my head, so I'm likely forgetting something.
Reading through protocol/weston-desktop-shell.xml should reveal most of
it.

This split is inherent to the shell plugin design. You could
theoretically do everything in the compositor process, but we chose not
to, because GUI things and drawing (drawing text is one of the most
complicated things there can be) often take a little bit of time. We
want to keep the compositor process as responsive as possible, hence
offloading those "long" running tasks to the helper client.

Because of this design, libweston actually lacks the interfaces to draw
things in the compositor. If you want content in a weston_surface that
is not just a single flat color, you pretty much need a client to
provide it. The whole compositing model of libweston assumes that
weston_surface provides content, that is transformed through a 4x4
matrix to the output, possibly clipped, and that's all.

Another thing is that bugs in the helper client are not fatal to the
whole desktop. If the helper crashes, the compositor can just restart
it, because all the necessary program state is really in the compositor.

So it's like heavy-weight threading with the bonus of using standard
Wayland protocol for most things and a little bit of custom protocol
for the special things, which nicely allows using proper toolkits while
keeping the compositor simpler, single-threaded, and more responsive
than otherwise.

> What should the functions for 'struct weston_desktop_api' do and can
> I omit certain things (like for example minimising a window) simply by providing
> the function-pointer with a no-op function?

That I cannot answer off-hand.

> What are the limitations of a weston
> shell? I want to create a desktop with automatic layouts, simple window
> decorations and a panel. I think the window decoration seen when using the
> provided example tools are not drawn by the shell, as I have not found any code
> for this and also some of the examples do not have window decorations at all.
> Can a shell actually provide window decoration or are they client side only?

By default, all window decorations are drawn by clients. The compositor
could produce something extra on top of that if it wants to, of course,
but making it look nice might be hard.

If you want to have all decorations drawn by the compositor (or the
helper client it delegates things to), you will have to implement the
server-side decorations Wayland protocol extension. See:
unstable/xdg-decoration/xdg-decoration-unstable-v1.xml in the
wayland-protocols repository.

> And what is the best way for the two parts of a shell to communicate with each
> other, so that one can, as an example, click on a button on the panel (handled
> by the client) and the shell changes the window layout (handled by the plugin),
> similar to the ivi-shell example? And are there any helper functions I can use,
> for example to get a list of all connected clients, or will I have to track
> something like that myself?

Weston's desktop-shell uses the private Wayland protocol extension for
that: protocol/weston-desktop-shell.xml.

You are free to use any means you want, but that is probably the
easiest, also given the existing example. You have to invent the kind
of protocol that makes sense for your GUI.

> I am used to Xlib programming, however from what I have seen of weston I doubt I
> can understand how to implement a shell only by looking at the code. Again, I
> hope this is the right place to ask these questions.

This is the place, no problem. :-)

An example of a shell project is https://github.com/raspberrypi/maynard .

It hasn't seen any development for a long time, so probably doesn't
work with the latest Weston. However, it does showcase how to leverage
the existing (at the time) desktop-shell plugin while extending the
capabilities with a plugin of its own, and the helper client uses GTK,
not the homebrewn "toytoolkit" from Weston demos. IIRC.

For the record, Weston's design represents the "tightly integrated"
design model where the end user cannot freely pick and choose which
components his DE uses. wlroots OTOH represents the more loosely
integrated design model, where the desktop GUI elements and features
can be provided by various interchangeable components that are external
processes. This is facilitated by attempting to define generic protocol
extensions for DE components, something that the Weston upstream has
traditionally avoided.

https://github.com/swaywm/wlroots


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20190610/bc2fed5d/attachment.sig>