README.md
1# xcffib [](https://github.com/tych0/xcffib/actions)
2
3`xcffib` is intended to be a (mostly) drop-in replacement for `xpyb`. `xpyb`
4has an inactive upstream, several memory leaks, is python2 only and doesn't
5have pypy support. `xcffib` is a binding which uses
6[cffi](https://cffi.readthedocs.org/), which mitigates some of the issues
7described above. `xcffib` also builds bindings for 27 of the 29 (xprint and xkb
8are missing) X extensions in 1.10.
9
10## Installation
11
12For most end users of software that depends on xcffib or developers writing
13code against xcffib, you can use the version of xcffib on pypi. To install it,
14you'll need libxcb's headers and libxcb-render's headers (these are available
15via `sudo apt-get install libxcb-render0-dev` on Ubuntu). Once you have the C
16headers installed, you can just `pip install xcffib`.
17
18If you're interested in doing development, read on...
19
20## Development dependencies
21
22You should be able to install all the language deps from hackage or pip.
23[.github/workflows/ci.yaml](https://github.com/tych0/xcffib/blob/master/.github/workflows/ci.yaml)
24has an example of how to install the dependencies on Ubuntu flavors.
25
26## Hacking
27
28See the [Makefile](https://github.com/tych0/xcffib/blob/master/Makefile) for
29examples on how to run the tests. Your contribution should at pass `make check`
30before it can be merged. The `newtests` make target can be used to regenerate
31expected haskell test data if the tests are failing because you made a change
32to the generated python code.
33
34## Hacking on new xcb-proto versions
35
36Sometimes (more often recently), xcb-proto makes some updates that we need to
37do some work for. These often require some updates to `xcb-types` as well.
38First, hack your changes into `xcb-types` and `cabal install` them, then git
39clone the version of xcb-proto you want to somewhere, e.g. `~/packages`:
40
41 ~/packages $ git clone http://anongit.freedesktop.org/git/xcb/proto.git xcb-proto`
42
43Finally, you can build/test xcffib against this custom version of
44`xcb-{proto|types}` with:
45
46 make XCBDIR=~/packages/xcb-proto/src check
47
48## Differences
49
50In general, you should `s/xcb/xcffib/g`. Explicit differences are listed below,
51however I don't think these will prevent any porting, because these were either
52not public APIs, or not actually generated (in the case of the exceptions) by
53`xpyb`. I think most porting should Just Work via the regex above.
54
55* `xcb.Exception` is spelled `xcffib.XcffibException` and is also a parent of
56 all exceptions generated by xcffib.
57* `xcb.ConnectException` is gone, it was unused
58* `xcffib.ConnectionException` is raised on connection errors
59* `xcb.Iterator` is gone; similar functionality is implemented by
60 `xcffib.pack_list`.
61* `xcb.Request` is gone. It was an entirely internal and unnecessary interface.
62* `xcffib.Connection.send_request` takes slightly different (but more sensible)
63 arguments.
64* Everywhere `xcb-proto` says `char`, `xcffib` uses a char. That means on input
65 for a `<list type="char"/>`, you can use a python string literal. `xcffib`
66 also gives you a string of length 1 out for each element in such a list,
67 instead of an `int`. Finally, there is a helper method called `to_string` on
68 `xcffib.List`, to convert these string-like things into native strings. This
69 means that for things like `xproto.STR`, you can just do
70 `the_str.name.to_string()` instead of `''.join(map(chr, the_str.name))`.
71* As above, `void` is also packed/unpacked as `char`s, since the convention is
72 to use it as string data, e.g. in `xproto.ChangeProperty`.
73* The submodule `xcb` is gone. The top module re-exported all these constants
74 anyway, so they live there now. i.e. `xcb.xcb.CurrentTime` is now just
75 `xcffib.CurrentTime`.
76
77## Enhancements
78
79* When sending requests with nested structs you no longer have to pack the
80 contents yourself. For example, when calling `xproto.FillPoly`, you used to
81 have to convert the `POINT`s you were passing in to some sort of buffer which
82 had them `struct.pack`'d. Now, you can just pass an iterable (or
83 `xcffib.List`) of `POINT`s and it will be automatically packed for you.
84* Most of the lower level XCB connection primitives that were previously not
85 exposed are now available via `xcffib.{ffi,C}`, assuming you want to go out
86 of band of the binding.
87* Checked vs. Unchecked requests are still supported (via Checked and Unchecked
88 function calls). However, there is also an additional optional parameter
89 `is_checked` to each request function, to allow you to set the checked status
90 that way. Additionally, requests that are (un)checked by default, e.g.
91 `QueryTree` (`CreateWindow`), have a `QueryTreeChecked`
92 (`CreateWindowUnchecked`) version which just has the same default behavior.
93* The `FooError` `BadFoo` duality is gone; it was difficult to understand what
94 to actually catch if you wanted to handle an error. Instead, `FooError` and
95 `BadFoo` are aliases, and both implement the X error object description and
96 python Exception (via inheriting from `XcffibException`).
97* You can now create synthetic events. This makes it much easier to work with
98 `ClientMessageEvent`s. For example:
99
100 ```python
101 e = xcffib.xproto.ClientMessageEvent.synthetic(format=..., window=..., ...)
102 conn.core.SendEvent(..., e.pack())
103 ```
104
105## Why haskell?
106
107Why is the binding generator written in haskell? Because haskell is awesome.
108
109## TODO
110
111* XGE support? (xpyb doesn't implement this either)
112* xprint and xkb support. These will require some non-trivial work in
113 xcb-types, since it won't parse them correctly.
114
){kind=link}