75 lines
3.2 KiB
Go
75 lines
3.2 KiB
Go
|
/*
|
||
|
|
xgbgen constructs Go source files from xproto XML description files. xgbgen
|
||
|
|
accomplishes the same task as the Python code generator for XCB and xpyb.
|
||
|
|
|
||
|
|
Usage:
|
||
|
|
xgbgen [flags] some-protocol.xml
|
||
|
|
|
||
|
|
The flags are:
|
||
|
|
--proto-path path
|
||
|
|
The path to a directory containing xproto XML description files.
|
||
|
|
This is only necessary when 'some-protocol.xml' imports other
|
||
|
|
protocol files.
|
||
|
|
--gofmt=true
|
||
|
|
When false, the outputted Go code will not be gofmt'd. And it won't
|
||
|
|
be very pretty at all. This is typically useful if there are syntax
|
||
|
|
errors that need to be debugged in code generation. gofmt will hiccup;
|
||
|
|
this will allow you to see the raw code.
|
||
|
|
|
||
|
|
How it works
|
||
|
|
|
||
|
|
xgbgen works by parsing the input XML file using Go's encoding/xml package.
|
||
|
|
The majority of this work is done in xml.go and xml_fields.go, where the
|
||
|
|
appropriate types are declared.
|
||
|
|
|
||
|
|
Due to the nature of the XML in the protocol description files, the types
|
||
|
|
required to parse the XML are not well suited to reasoning about code
|
||
|
|
generation. Because of this, all data parsed in the XML types is translated
|
||
|
|
into more reasonable types. This translation is done in translation.go,
|
||
|
|
and is mainly grunt work. (The only interesting tidbits are the translation
|
||
|
|
of XML names to Go source names, and connecting fields with their
|
||
|
|
appropriate types.)
|
||
|
|
|
||
|
|
The organization of these types is greatly
|
||
|
|
inspired by the description of the XML found here:
|
||
|
|
http://cgit.freedesktop.org/xcb/proto/tree/doc/xml-xcb.txt
|
||
|
|
|
||
|
|
These types come with a lot of supporting methods to make their use in
|
||
|
|
code generation easier. They can be found in expression.go, field.go,
|
||
|
|
protocol.go, request_reply.go and type.go. Of particular interest are
|
||
|
|
expression evaluation and size calculation (in bytes).
|
||
|
|
|
||
|
|
These types also come with supporting methods that convert their
|
||
|
|
representation into Go source code. I've quartered such methods in
|
||
|
|
go.go, go_error.go, go_event.go, go_list.go, go_request_reply.go,
|
||
|
|
go_single_field.go, go_struct.go and go_union.go. The idea is to keep
|
||
|
|
as much of the Go specific code generation in one area as possible. Namely,
|
||
|
|
while not *all* Go related code is found in the 'go*.go' files, *most*
|
||
|
|
of it is. (If there's any interest in using xgbgen for other languages,
|
||
|
|
I'd be happy to try and make xgbgen a little more friendly in this regard.
|
||
|
|
I did, however, design xgbgen with this in mind, so it shouldn't involve
|
||
|
|
anything as serious as a re-design.)
|
||
|
|
|
||
|
|
Why
|
||
|
|
|
||
|
|
I wrote xgbgen because I found the existing code generator that was written in
|
||
|
|
Python to be unwieldy. In particular, static and strong typing greatly helped
|
||
|
|
me reason better about the code generation task.
|
||
|
|
|
||
|
|
What does not work
|
||
|
|
|
||
|
|
The core X protocol should be completely working. As far as I know, most
|
||
|
|
extensions should work too, although I've only tested (and not much) the
|
||
|
|
Xinerama and RandR extensions.
|
||
|
|
|
||
|
|
XKB does not work. I don't have any real plans of working on this unless there
|
||
|
|
is demand and I have some test cases to work with. (i.e., even if I could get
|
||
|
|
something generated for XKB, I don't have the inclination to understand it
|
||
|
|
enough to verify that it works.) XKB poses several extremely difficult
|
||
|
|
problems that XCB also has trouble with. More info on that can be found at
|
||
|
|
http://cgit.freedesktop.org/xcb/libxcb/tree/doc/xkb_issues and
|
||
|
|
http://cgit.freedesktop.org/xcb/libxcb/tree/doc/xkb_internals.
|
||
|
|
|
||
|
|
*/
|
||
|
|
package main
|