Basic API usage

[Pekka Paalanen]

On Mon, 7 Sep 2020 16:47:42 +0200
Jan Bruns <code at abnuto.de> wrote:

> Hallo!
> 
>  From the perspective of someone with a non-gcc-supported programming 
> language preference, I have problems identifying an outline of steps 
> required to support wayland from within an application.
> 
> For example, from the human readable documentation at 
> wayland.freedesktop.org, I've learned that wayland communication is 
> based on some unix domain socket protocol (similar to X), which would 
> probably allow for process separation (with the benefit of avoiding 
> problems about things like floating point precision settings, exception 
> handling, and so on). However, the xml frequently referenced in the 
> documentation doesn't appear to completely define a protocol.
> 
> Two Hello-world C examples found on the web both reference the files 
> wayland-client-core.h and wayland-client-protocol.h
> 
> wayland-client-core.h makes use of very C-specific language constructs 
> like "..." in parameter lists. I'm very unsure if the other programming 
> language compiler of choice could generate ABI-conformant calls to 
> those, in addition to the fact I cannot yet (after just a few hours of 
> trying) even name the lib the ABI-tools should link to.

Hi,

yes, the application used headers are generated by a bindings-specific
tool from the XML, like wayland-scanner for the traditional C bindings.

wayland.xml is actually the exception that ships with pre-generated
headers. All other protocol XML files (e.g. from wayland-protocols
repository) do not ship headers, but expect projects using the
protocol to use the appropriate language binding generator tools
themselves.

> wayland-client-protocol.h was a bit difficult to find. It probably gets 
> auto-generated on installing wayland, a step that I didn't try, since 
> wayland already was installed here. But I found it in /usr/include.
> 
> Could someone please outline how to use the API for the non-gcc case?

I suppose you mean a non-C/C++ case.

You can write a whole protocol implementation from scratch without
depending on libwayland, if you have no need to use ready-made
libraries that already use libwayland. One of the most notable
ready-made libraries that use libwayland is Mesa EGL, so if you want to
be able to use EGL, you have no choice but to wrap libwayland.

Rust bindings for libwayland exist, and I think also a pure Rust
implementation of Wayland. Java as well, and undoubtedly many more in
various different forms.

libwayland is split into client and server parts, but you can also see
it being split into core and language bindings. The bindings for the C
language come built-in, but they are not the only bindings in
existence. The thing that may confuse you is that there are actually
two different APIs for writing language bindings: one very specific to
C (the one you found), and another better suited to other languages.

There is an old blog post about the alternate bindings API that should
help you find the right bits or at least the right mindset:
http://www.jlekstrand.net/jason/projects/wayland/language-bindings-guide/

Unfortunately there are many details that have not yet been written
down in a specification document, which means you need to compare with
how the C bindings actually work, e.g. what does wayland-scanner do
with the XML. The common catch is that a new_id argument without an
interface defined in the XML will expand into three arguments, not one.
Event and request opcodes are assigned independently and implicitly in
the order they appear inside an interface definition in the XML.

The wayland-*-core.h headers exist (as an afterthought, which explains
all this duplicity in the APIs as well) exactly so that programs using
non-C bindings would not need to pull in the C bindings.

If I remember the right, the core of the alternate bindings API for
client side is formed from:
- wl_proxy_marshal_array
- wl_proxy_marshal_array_constructor
- wl_proxy_marshal_array_constructor_versioned
- wl_proxy_add_dispatcher

which are the things you can use instead of the very C language
centric:
- wl_proxy_marshal
- wl_proxy_marshal_constructor
- wl_proxy_marshal_constructor_versioned
- wl_proxy_add_listener

The main idea is that you wrap the "core" API of libwayland into your
preferred language, and then write a code generator tool similar to
wayland-scanner that generates the bindings from XML to your language,
using your wrapped libwayland calls. You have the freedom to design the
API produced by your code generator any way you want as long as it maps
correctly to the libwayland ABI.


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/20200908/c62fcc7b/attachment.sig>