xcb/ DevelopersGuide

XCB and Xlib/XCB development efforts are coordinated using gitlab, this Wiki, and the XCB mailing list.

libX11 and XCB repositories use git for source control management (SCM). The git repository was created to integrate the XCB work in the X11 library and at the same time do real testing of alternatives to CVS. See the instructions for using freedesktop.org repositories.

To build XCB from source, you need to have installed at least:

  • git
  • pkgconfig or pkgconf
  • automake
  • autoconf 2.62 (for xcb/util-cursor), 2.60 (for libxcb), or 2.59c (for other xcb/util libraries)
  • libtool 2.2
  • Python 2.x, or Python 3 as of XCB 1.9.1
  • xorg-macros 1.18
  • gperf 3.0.1 (for some of the xcb/util libraries)

(Trivial patches to support earlier versions, or a note that earlier versions "just work", would be welcome.)

To do 'make check' or 'make dist', you also need:

Please familiarize yourself with the Modular Developer's Guide before trying to build any part of X.org. Freedesktop's main site has detailed instructions for using git for everyday development.

  • How to get a copy of a git module:
    • git clone https://gitlab.freedesktop.org/xorg/lib/libX11.git (this will create a 'libX11' directory in the working directory)
    • git will create a .git directory inside the source directory where it stores all the info

There are multiple modules. The modules you need to checkout, build, and install for XCB are, in order:

  • from X.org git:
    • xorg/util/macros (see note below)
    • xorg/lib/libXau
    • xorg/proto/x11proto and xorg/lib/libXdmcp, to optionally support XDM-AUTHORIZATION-1
    • xorg/lib/pthread-stubs
    • xorg/proto/xcbproto
    • xorg/lib/libxcb

To build Xlib with support for XCB, first build XCB as above. After that, the modules you need to checkout, build, and install for Xlib are, in order:

  • from X.org git:
    • xorg/proto/xorgproto
    • xorg/lib/libxtrans
    • xorg/lib/libX11

Note that aclocal needs to be able to find the files installed from xorg/util/macros. You may need to set ACLOCAL="aclocal -I /usr/local/share/aclocal" or similar before running autogen.sh or autoreconf.

To build the XCB demos, you need two more repositories:

  • xcb/util (also needed for the XCB backend of cairo)
  • xcb/demo

There are also two experimental XCB repositories:

  • xcb/xhsb (experimental Haskell bindings)
  • xcb/libXamine (X protocol inspection library which makes use of the XML protocol descriptions)

This is a fairly complex operation at this point. Watch out for pkgconfig problems, esp. distinguishing /usr/local, /usr, and /usr/X11R6 in the config. Note that proto/X11 and xcb-proto exist only to install header files, so typing make or make all will produce the message "Nothing to be done for 'all'". That's normal.

We have documented our procedure for ReleasingXcb.

Mailing List and other resources

The XCB mailing list is hosted by freedesktop.org.

Jeremy has set up an xcb-commit mailing list to notify users of Git commits.

Freedesktop's GitLab is used to report bugs, suggest enhancements, and submit patches.

There is also an #xcb IRC channel on oftc.net.

Implementation and Status

Both XCB and our XlibXcb efforts are works in progress; XCBToDo describes current work needed and in progress. Also available: XcbRationale and XcbApi documentation.

The protocol layer of XCB is implemented as a set of XML protocol descriptions, along with a Python-based C binding generator. The remainder of XCB consists of C code.

?JoshTriplett has documented the XML/XCB protocol description format; this documentation is included in the xcb-proto package.

The structure of XCB is designed to be as simple as possible while making common usage convenient and reasonably efficient. XCB is designed to work transparently with POSIX Thread programs or single-threaded programs: on platforms where POSIX threads are unavailable, it will be compilable without.

The X core requests have been implemented in XCB, as well as the BIG-REQUESTS, XC-Misc, SHAPE, SHM, DPMS, Render, Randr, GLX, XFIXES, Composite, DAMAGE and XEvIE extensions. A multithreaded demonstration program uses XCB for animated graphics in multiple windows. Other demos for Render, event monitoring, access to connection setup data, and DPMS also exist.

BartMassey has done some work on establishing correctness properties of the core data dispatch mechanism of XCB using a model of XCB written in the Z formal specification notation. This is good, since the mechanism is complex, and the previous version was known to have defects.

Making a release

See ReleasingXcb.