Enums, bitfields and wl_arrays in the .xml file

[Nils Chr. Brause]

Hi

These are all  very interesting points.

I understand that some language bindings might break existing code, if
they want to use the 'enum' and 'bitfield' attributes. But they could
simply bump the major version of their bindings, in that case. In my
opinion this is a low price to pay for higher qualitiy bindings.

In the case of my C++ bindings, things are fortunately a bit easier:

- Since I am already using the 'enum' and 'bitfield' attributes,
nothing needs to be changed here.
- Adding entries to enumerations or bitfields doesn't break existing code.
- Being an incomplete enumeration is only a problem, if the user
wishes to use a value that is not part of the protocol XML used to
generate the bindings. (One could still forcefully convert an integer
to an enum  class and vice-versa through static_cast<>(), though.)
- Adding a content type to an array might need a bit of thought.
Currently there seems to be only one use of the array type in the
official Wayland protocol XML, which is wl_keyboard::enter. I define
its wl_array as a std::vector<char>. If it turns out to be something
else, this would indeed break existing code. But since I have not yet
declared my bindings as stable, this isn't a problem for me.

Cheers,
Nils


On Thu, Sep 24, 2015 at 1:00 PM, Victor Berger
<victor.berger at polytechnique.org> wrote:
> Hi,
>
> After some discussions on IRC, it appears this raises several concerns about
> back-compatibility.
>
> The main points being:
>
> - if a protocol file previously did not use these extra attributes, and
> choses to add them, depending on the language using them it can be a
> breaking change (as it would change the prototype of the requests from
> u(int) to the enum type for example)
> - if a variant is added to an already existing enum, it can be a breaking
> change for some languages (Rust is one of them, as the compiler enforces you
> to cover all possible variants when matching on an enum).
> - some enums, like xdg_shell::xdg_surface::states are by definition not
> complete.
> - and most likely other similar issues with "array" types or so
>
> These questions need to be resolved, and a proper specification of what
> should contain the .xml files will certainly need to be written to properly
> handle all this.
>
> To other bindings writers: what are you opinions and constraints on these
> back-compatibility hazards ?
>
> In my case (Rust):
> - the question adding the an "enum" attribute to a field that didn't use it
> is a breaking change that needs thought.
> - adding a variant to a bitfield is not a problem
> - adding a variant to a classic enum is not trivial a priori, but I have
> possibilities to future-proof this with small overhead, and it would handle
> incomplete enums as well. (it involves using a wrapping struct that
> optionnaly tries to convert the raw value to the enum)
> - as well, adding the specification of the type contained in an array to an
> arg that didn't have it would be a breaking change, and as such needs
> thought.
>
> ----
> Victor
>
> Le 2015-09-18 20:55, Bill Spitzak a écrit :
>>
>> On Fri, Sep 18, 2015 at 5:37 AM, Nils Chr. Brause
>> <nilschrbrause at gmail.com> wrote:
>>
>>> Hi,
>>>
>>> There are even earlier discussions about including 'bitfield' and
>>> 'enum' fields into the XML protocol file, e.g:
>>>
>>
>> http://lists.freedesktop.org/archives/wayland-devel/2014-September/017071.html
>>>
>>> [1]
>>> But none of them led to any actual changes.
>>>
>>> I still would very much like to see the 'bitfield' and 'enum'
>>> fields
>>> to be included in the XML protocol file. This would greatly
>>> simplify
>>> the creation of Wayland bindings for most high level programming
>>> languages and thus increase the popularity of Wayland amongst
>>> programmers who don't wish to use toolkits.
>>> Without these information about bitfields and enumerations,
>>> language
>>> bindings would have to maintain their own version of the XML
>>> protocol
>>> file, like I am doing with my C++ bindings here:
>>> https://github.com/NilsBrause/waylandpp [2]
>>
>>
>> Yes please get this in. I really expected this to be merged long ago.
>>
>> This is almost a requirement for bindings for any language other than
>> C. And it greatly improves the automatically generated documentation
>> of the C api, too!
>>
>> And it is absolutely 100% compatible with everything that exists right
>> now (except code reading the xml files, which might have to be
>> modified to ignore the new tags). It does not change the size or bit
>> layout of any data in the stream protocol and does not change the C
>> api, and does not prevent the sending or construction of any message
>> or event that can be sent right now. In particular it does not prevent
>> bit patterns that are not in the enumeration from being sent by the C
>> api.
>>
>>
>>
>> Links:
>> ------
>> [1]
>>
>> http://lists.freedesktop.org/archives/wayland-devel/2014-September/017071.html
>> [2] https://github.com/NilsBrause/waylandpp
>>
>> _______________________________________________
>> wayland-devel mailing list
>> wayland-devel at lists.freedesktop.org
>> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel