Protocol (scanner) proposals

[Pekka Paalanen]

On Sat, 2 Aug 2014 15:07:19 +0200
Auke Booij <auke at tulcod.com> wrote:

> On 30 July 2014 20:27, Pekka Paalanen <ppaalanen at gmail.com> wrote:
> > Actually no. Binding writers are expected to write their own code
> > generator for their language, like wayland-scanner is for C. You
> > are expected to not use the static inline generated C functions.
> 
> Okay, that makes some amount of sense. But in that case, that should
> be documented.

It was, hidden in a small paragraph in the documentation...

> > Instead the functions actually exported by the library are the ABI.
> 
> I guess that this is convention in C?

Maybe, but mostly for practical reasons.

Static inlines are API, but they get compiled into the application
using the library, so changing the library later cannot change what
static inlines are. In that sense, the static inlines are not ABI.

If you make an incompatible change in a static inline's call
signature, all existing binaries will keep on working, which means
that the library ABI did not change. But, you cannot recompile the
applications without fixing them, which means the library API did
change.

Doing things with static inlines like done in libwayland-client
means, that you can compile an application against a new
libwayland-client, but still run it against an old
libwayland-client, even if the old libwayland-client does not have
all the protocol bits added to the new version. When e.g. bumping
the version of a protocol interface when adding a request, the
libwayland-client ABI does not change, but the API gets a new
wrapper static inline function.

That's pretty nice, because it allows to run application binaries
even on older systems as long as the application can deal with
older interface versions properly. It just means that there won't
be any runtime linker issues with unresolved symbols.

Note, that the above applies only to additions to the protocol XML
specification. And even then, I'm not sure if it works for whole
new interfaces, but it should work for extending existing
interfaces.

> > I would love to see documentation patches!
> 
> Speaking of which, is there a reason the code samples don't show up
> correctly in the online documentation?

Which code samples exactly?

It is quite possible that the doc generator just messes something
up. Not many developers have Publican installed, so fixing them is
hard. Moving away from Publican would be nice, IMHO...


Thanks,
pq