github.com/robotn/xgb@v0.0.0-20190912153532-2cb92d044934/xgbgen/doc.go (about)

     1  /*
     2  xgbgen constructs Go source files from xproto XML description files. xgbgen
     3  accomplishes the same task as the Python code generator for XCB and xpyb.
     4  
     5  Usage:
     6  	xgbgen [flags] some-protocol.xml
     7  
     8  The flags are:
     9  	--proto-path path
    10  		The path to a directory containing xproto XML description files.
    11  		This is only necessary when 'some-protocol.xml' imports other
    12  		protocol files.
    13  	--gofmt=true
    14  		When false, the outputted Go code will not be gofmt'd. And it won't
    15  		be very pretty at all. This is typically useful if there are syntax
    16  		errors that need to be debugged in code generation. gofmt will hiccup;
    17  		this will allow you to see the raw code.
    18  
    19  How it works
    20  
    21  xgbgen works by parsing the input XML file using Go's encoding/xml package.
    22  The majority of this work is done in xml.go and xml_fields.go, where the
    23  appropriate types are declared.
    24  
    25  Due to the nature of the XML in the protocol description files, the types
    26  required to parse the XML are not well suited to reasoning about code
    27  generation. Because of this, all data parsed in the XML types is translated
    28  into more reasonable types. This translation is done in translation.go,
    29  and is mainly grunt work. (The only interesting tidbits are the translation
    30  of XML names to Go source names, and connecting fields with their
    31  appropriate types.)
    32  
    33  The organization of these types is greatly
    34  inspired by the description of the XML found here:
    35  http://cgit.freedesktop.org/xcb/proto/tree/doc/xml-xcb.txt
    36  
    37  These types come with a lot of supporting methods to make their use in
    38  code generation easier. They can be found in expression.go, field.go,
    39  protocol.go, request_reply.go and type.go. Of particular interest are
    40  expression evaluation and size calculation (in bytes).
    41  
    42  These types also come with supporting methods that convert their
    43  representation into Go source code. I've quartered such methods in
    44  go.go, go_error.go, go_event.go, go_list.go, go_request_reply.go,
    45  go_single_field.go, go_struct.go and go_union.go. The idea is to keep
    46  as much of the Go specific code generation in one area as possible. Namely,
    47  while not *all* Go related code is found in the 'go*.go' files, *most*
    48  of it is. (If there's any interest in using xgbgen for other languages,
    49  I'd be happy to try and make xgbgen a little more friendly in this regard.
    50  I did, however, design xgbgen with this in mind, so it shouldn't involve
    51  anything as serious as a re-design.)
    52  
    53  Why
    54  
    55  I wrote xgbgen because I found the existing code generator that was written in
    56  Python to be unwieldy. In particular, static and strong typing greatly helped
    57  me reason better about the code generation task.
    58  
    59  What does not work
    60  
    61  The core X protocol should be completely working. As far as I know, most
    62  extensions should work too, although I've only tested (and not much) the
    63  Xinerama and RandR extensions.
    64  
    65  XKB does not work. I don't have any real plans of working on this unless there
    66  is demand and I have some test cases to work with. (i.e., even if I could get
    67  something generated for XKB, I don't have the inclination to understand it
    68  enough to verify that it works.) XKB poses several extremely difficult
    69  problems that XCB also has trouble with. More info on that can be found at
    70  http://cgit.freedesktop.org/xcb/libxcb/tree/doc/xkb_issues and
    71  http://cgit.freedesktop.org/xcb/libxcb/tree/doc/xkb_internals.
    72  
    73  */
    74  package main