[PATCH] update protocol specification to match wire protocol

[Pekka Paalanen]

On Fri, 5 Sep 2014 07:05:55 -0500
Paul Sbarra <sbarra.paul at gmail.com> wrote:

> On Thu, Sep 4, 2014 at 10:33 PM, Boyan Ding <stu_dby at 126.com> wrote:
> 
> > Hi,
> >
> > Actually it is not a hack, it is a very well-defined behavior (though
> > not clearly documented at present). We'll update the documentation to
> > reflect that. The mechanic of creating objects undergoes some change as
> > Pekka mentioned [1] and now it's been stable and won't change anymore (I
> > have to iterate again that if you change how it works now, the world
> > will break before you).
> 
> 
> Thanks for the link, that's the first place I've seen that's documented
> this behavior.  While I don't mean to be rude (just persistent) did anyone
> take a look at the patch?  It generates the exact same code aside from a
> very minor grammatical fix, so I don't uderstand how that's going to "break
> the world".

I took a look at both of them, you are making an incompatible change to
wayland.xml, and breaking the generator.

Essentially you are breaking the unwritten specification on how the XML
files are processed into wire format and language bindings.
Wayland-scanner is not the only generator, and wayland.xml is not the
only XML file in existence.

> > The tool you mentioned seems implement an older
> > version of the specification and if you want to use that tool, you
> > should change the code generation to the way wayland-scanner works now.
> 
> 
> The tool I mentioned is simply one example illustrating the current problem
> (undocumented behavior).  I see two possible options to resolve it. 1.
> update any code-generation tools to account for the to-be-documented
> behavior, or 2. Update the specification to not have "unique" caveats.  My
> position is that the second option is the better choice.
> 
> As mentioned the generated code remains the same so any applications that
> link to libwayland are unaffected.  Additionally, since this "feature" is
> still undocumented any code-generation tools relying on this behavior could
> be considered as violating the spec.  Are there any other known tools that
> would need to be updated?

If you look carefully, you see that there is absolutely no
documentation on how to generate the wire protocol or C function
signatures from the XML. It is all undocumented.

The only authoritative definition we currently have is
http://cgit.freedesktop.org/wayland/wayland/tree/src/scanner.c


Thanks,
pq