xcb-shim: easier native X11 protocol implementation

This program produces an intermediate form of the XCB protocol specification data structures, to make it easier to build native bindings rather than wrapping libxcb.

The XML files in the xcbproto repository specify most of the necessary data types and (de)serialization procedures for working with X11, but they require a reasonable amount of interpretation before they can be used. The xcbgen Python library performs a big chunk of this interpretation.

Reimplementing this complex (and not documented outside of the python code?) logic in other programming languages is a big obstacle to writing X11 bindings using the XCB specifications. Therefore, I wrote xcb-shim.py to reduce the burden on programmers trying to do this. The program uses xcbgen to do all the complex stuff and emits a JSON structure containing more the information needed to compute data type definitions and (de)serialization code than you’d get from reading the XCB XML files alone.

A Preserves Schema describing the output of xcb-shim.py is available in xcb.prs.


The program and its output are versioned together in two parts: a semver part, covering xcb-shim.py and the schema of the data structure it produces, and a part repeating the version of xcbproto that it got the input XML files and the xcbgen library from.

For example, version 1.2.3+1.15 means that xcb-shim (and the schema governing xcb.json) is at version 1.2.3 and the XML files and xcbgen library used to produce xcb.json were from xcbproto version 1.15.

Open questions

union types. The method for deciding which union member is active is not specified, and varies from use to use. Fortunately, there are only a few unions in the current protocol suite. A future improvement could be to come up with some way to specify the connection between the discriminator and the union.

Current uses:

  • randr:NotifyData: member is selected by subCode member of the containing Notify event, whose values are specified to be drawn from enum Notify.

  • xkb:Behavior: member is selected by type field of each member, carefully positioned to be in the same place in each, with an unspecified, implicit connection to an enum BehaviorType which connects CARD8 values to the active member of xkb:Behavior.

  • xkb:Action: like xkb:Behavior, but the connection to the enum SAType is specified by an enum attribute on the type fields in each member.

  • ClientMessageData: member is selected by format field, able to take on values as documented in the XML comments but not specified in the actual structures.


See COPYING for licencing information for all the files in this repository with the exception of the build product, xcb.json. The xcb.json file is essentially a derived work of the input XML files, so presumably falls under the licence(s) of the input files themselves. I’m no lawyer, and I’m not sure how the licencing works for compilers like xcb-shim.py.


View Github