# libXCB (X C Binding library)



## sidetone (Aug 14, 2021)

XCB (X-protocol C-language binding) was intended to fully replace Xlib for X11: so far, XCB has gradually replaced some parts of it. Its purpose was to be more efficient and to be easier to program. X11 is a protocol. Xlib and XCB are both API's and library sets.

Xlib (also called libX11) is too low level for most graphical programming needs, it: has features not commonly used, had lack of compile checks, and was complicated to program with. Simple programming tasks needed excessive coding in Xlib. Its purpose was also too wide range for both applications and toolkits.

XCB is in C: it uses C header files, and it requires knowledge of C programming. XCB's library is libxcb, and its header is xcb.h. To compile programs that use XCB, they must be linked to relevant XCB's libraries. xcb-proto only installs header files.

XCB is POSIX compliant. This API library is also thread-safe, and it has better error handling than Xlib.

Parts of Xlib were replaced by parts of XCB. Xtrans (X Transport Interface), a low level part of Xlib, was replaced with XCB. Also, Xlib can receive calls to XCB through a transport layer from X11. XCL was an emulation layer from XCB (as a proof of concept, which some parts which were kept for a newer library: updated explanation below) to receive instructions from Xlib outputs. Many programs originally written for Xlib, are partially implemented in XCB, and receive mixed instructions for these two libraries. Parts of XCB have been available within replaced parts of libX11 since 1.2.0 (this became default since 1.4.0). LibX11 version 1.7.2 is currently in ports, as of this writing.


Previously XCB used M4 based protocol description language. This was replaced with XML in 2004. XCB extensions are simplified, as all each one needs is an XML description.

There is a lack of documentation for XCB, but enough information on it can be found in X11 documentation and in the programming notes.


*Ports tree applications*
In the ports tree: x11-wm/mcwm and x11-wm/bspwm are window managers that are built on XCB. x11-wm/compiz is a compositor that is built on XCB. Other ones: x11-wm/chamfer, x11-wm/i3, x11-wm/i3-gaps, x11-wm/phoc, x11-wm/spectrwm, x11-wm/sway, x11-wm/wayfire and x11-wm/awesome.

x11/thingylaunch can be compiled with XCB instead of Xlib. x11/lemonbar is in XCB. x11/polybar is another bar, but it has more dependencies and options. Other programs in the ports tree that use XCB and not Xlib  are few: x11/xtitle, x11/xlsatoms, x11/xcbautolock, x11/ly. Most other programs that use xcb, instead of xlib, rely on QT5 or Rust.


*Refs*

https://www.informit.com/articles/article.aspx?p=1395423
https://xcb.freedesktop.org/
*Tutorials*

https://www.x.org/releases/X11R7.5/doc/libxcb/tutorial/
https://www.codeproject.com/Articles/1089819/An-Introduction-to-XCB-Programming


----------



## eternal_noob (Aug 15, 2021)

Interesting. Thank you for posting this.


----------



## sidetone (Sep 2, 2021)

*MCWM *& *BSPWM*
x11-wm/mcwm is a minimalist window manager that requires a terminal emulator to be run with it, and x11-wm/bspwm is a tiling window manager with binary behavior which by default uses x11/sxhkd for keyboard inputs. Both of these window managers use bsd-like licenses.

MCWM has a low residential RAM footprint of about 2.6MB. Xterm adds about 14MB to that. BSPWM uses about 3.4MB for resident memory. SXHKD adds about 2.9MB.

Common libraries and their ports between MCWM and BSPWM:

libxcb.so.1 - x11/libxcb
libxcb-randr.so.0 - x11/libxcb
libxcb-util.so.1 - x11/xcb-util
libxcb-icccm.so.4 - x11/xcb-util-wm
libxcb-keysyms.so.1 - x11/xcb-util-keysyms
BSPWM additionally uses:

libxcb-xinerama.so.0 - x11/libxcb
libxcb-shape.so.0 - x11/libxcb
libxcb-ewmh.so.2 - x11/xcb-util-wm

Xinerama adjusts maximizing windows on multi-monitors. When it's not compiled in to other window managers, a maximized window will take up all of 2 screens.

EWMH and ICCCM are compatibility standards for window managers.

XMU and Xext aren't needed for XCB. libXRendr is traditionally a dependency of XFT for fonts on Xlib, but is now obsolete. XFT may not be relevant for XCB dependencies.

*xcb-util*
Ports that rely on x11/xcb-util:

x11/xcb-util-wm
x11/xcb-util-keysyms
other ports prefixed with xcb-util-

*Screenshots *&* Configuration*





Screenshot of MCWM which uses XCB, and of xterm. bgs or xsetroot are needed to set the background. This image is from the thread: Thread screenshots-of-bsd-window-managers-for-x11.81505/. From .xsession/.xinitrc, this window manager requires a different way to start than other window managers: xterm is started last with `exec`, and the ampersand goes after mcwm:

```
mcwm &
exec xterm -bg black -fg white +sb -uc -bc
```









BSPWM screenshots by tedbell & rigoletto@ from Thread freebsd-screen-shots.8877. (The image on the left uses Polybar and dzen. Both images use Conky.)

BSPWM needs bspwmrc copied from /usr/local/share/examples/bspwm/ to ~/.config/bspwm/.
To use SXHKD, copy /usr/local/share/examples/bspwm/sxhkdrc to ~/.config/sxhkd/.

Edit .xsession or .xinitrc to:

```
sxhkd &
exec bspwm
```

*Cairo*
Cairo graphics library can be compiled with XCB turned on, and Xlib and glib turned off. It is under both LGPL and MPL licences. Cairo is nice, but it is too heavily convoluted into Gtk.


----------



## sidetone (Mar 9, 2022)

*History of XCB transition libraries*
XCL (Xlib Compatibility Layer) was a proof of concept for replacing Xlib code with XCB code while maintaining compatibility with programs that call Xlib. xcl.h is obsolete as a standalone library. A previous and obsolete instruction said to replace Xlib.h with xcl.h. Another past instruction said to use `--with-xcb` for compiling Xlib. These instructions for using the XCL library have been obsolete since 2014.

Xlib/XCB (Xlib-xcb.h) has replaced XCL, and this library contains XCB, Xlib and some XCL library code. The library X11/Xlib-xcb.h is installed with x11/libX11. The use of Xlib-xcb.h replaces xcl.h, and it can be used in place of Xlib.h and xcb.h. Using this library allows mixed calls to be made to transition porting to XCB.

Separately from mixed calls, XCB code has replaced Xtrans (X Transport Interface) for the low level transport layer in current default Xlib. Xorg or libX11 installed from ports has the directory /usr/local/include/X11/Xtrans/ installed from x11/xtrans. Xtrans appears to still be used only for parts of its header.

https://www.usenix.org XCL: An Xlib Compatibility Layer For XCB - 2002
https://xcb.freedesktop.org/XCBCompletedTasks/
https://xcb.freedesktop.org/History/
https://xcb.freedesktop.org/adoption/
https://xcb.freedesktop.org/XlibXcb/
https://xcb.freedesktop.org/MixingCalls/
*Transitioning to XCB*
Xlib-xcb.h and Xlib.h are both installed by x11/libX11. The current instruction is to replace X11/Xlib.h with X11/Xlib-xcb.h in source files written in C where transitioning to XCB will be attempted. In mixed calls, Xlib code gets priority over XCB code. Alternatively, x11/libxcb is for C code that's written purely in XCB. Additional ports related to libxcb have more features than that of Xlib/XCB.

https://xcb.freedesktop.org/MixingCalls/
https://www.codeproject.com/Articles/1089819/An-Introduction-to-XCB-Programming
https://www.x.org/releases/X11R7.5/doc/libxcb/tutorial/
https://xcb.freedesktop.org/tutorial/
https://projects.mini-dweeb.org Porting a Window Manager from Xlib to XCB (pdf) - 2008
https://www.x.org/wiki/guide/xlib-and-xcb/ - 2013


----------



## sidetone (Apr 15, 2022)

*XCB applications and additional libraries:*

https://github.com/venam/fonts-for-xcb
https://venam.nixers.net/blog/unix/2018/09/02/fonts-xcb.html

https://github.com/joshuakraemer/sft - Freetype like fonts
https://github.com/jefbed/jbxvt - xcb terminal emulator
https://github.com/mcpcpc/xbar - information bar for system metrics
https://github.com/jvvv/xsetroot-xcb - change WM background
https://github.com/kamiyaa/dwmstatus status bar for dwm and other WM's
https://github.com/omnp/floating - paint program
https://github.com/zoefiri/libXglue - event handlers and high level window manager library
https://github.com/shizy/flap - geometry tool for moving and resizing windows in monitor displays
https://github.com/Johns-Q/wmc2d - dockapp to show CPU information
https://github.com/erinacio/suggestdpi - suggest DPI based on randr
https://github.com/mike-jumper/xcb-randr-test - xcb proof of concept for randr
*XCB window managers:*

https://github.com/venam/2bwm - based on mcwm with more features; tiling WM
https://github.com/Cloudef/monsterwm-xcb - Monster xcb fork; tiling WM
https://github.com/sulami/FrankenWM - Monster xcb fork; based on 2bwm; dynamic WM
https://github.com/kaugm/mmwm - based on FrankenWM; dynamic WM
https://github.com/mcpcpc/xwm - small xcb WM (not original defunct xwm)
https://news.ycombinator.com/item?id=25033613

x11-wm/i3-gaps
https://github.com/julian-goldsmith/dwm-xcb - dwm xcb fork
https://github.com/marshallmason/ittywm - tinywm xcb fork
https://github.com/jvvv/9wm-xcb - 9wm xcb fork
https://github.com/blobject/goose  - tcl xcb WM for Wayland
https://github.com/esno/xcwm - cwm xcb fork?
*XCB directory of base libraries*

https://gitlab.freedesktop.org/xorg/lib/libxcb - contains file equivalents of commands for libx11
https://gitlab.freedesktop.org/xorg/lib - contains additional subdirectories of extended xcb libraries
libxcb-cursor
libxcb-errors
libxcb-image
libxcb-keysyms
libxcb-render-util
libxcb-util
libxcb-wm

xcb-util - are extended libraries of xcb for higher functions. https://xcb.freedesktop.org/XcbUtil/
render-util
aux
atom
property
icccm
keysyms
event
image

*Latest on XCB*

https://xcb.freedesktop.org/
https://lists.freedesktop.org/archives/xcb/


----------



## sidetone (Apr 17, 2022)

*XCB on XWayland*
Weston (https://gitlab.freedesktop.org/wayland/weston) is a sample/showcase compositor and libweston is its related application library for building applications and compositors. These are both maintained by X.org. libweston is compatible with libxcb through XWayland. Unclear if this application library has builtin libx11 functionality.

wlroots (Wayland Roots), maintained by FreeDesktop.org (https://gitlab.freedesktop.org/wlroots/wlroots), when used with XWayland has a dependency on libxcb, so doesn't have direct support for the older libx11 API. A  handful of compositors are built on top of wlroots' library.

wlc is a defunct compositor and application library that has been replaced by wlroots, wlc had support for libx11 and libxcb.

XWayland in FreeBSD's portstree depends on libX11 and not directly on libxcb, though libx11 depends on libxcb. It appears as if compositors on wlroots are intended to be in xcb. From XWayland, applications are intended to be compatible from both x11 and xcb.

libXCB makes sense as a common library to be used on XWayland across varying Wayland compositors and their libraries for applications. It may make more sense for window managers to be ported to a Wayland compositor library.

*Further reading*

https://venam.nixers.net/blog/unix/2016/10/25/x11-blah-blah.html - Xcb, X11, Xlib, Wayland?
https://bettereconomics.blogspot.com/2018/11/wayland-and-xcb.html
https://www.phoronix.com/scan.php?page=search&q=libweston
https://xeechou.net/posts/weston-vs-wlroots/
https://julien.danjou.info/thoughts-and-rambling-on-the-x-protocol/


----------



## sidetone (Aug 16, 2022)

x11-wm/ittywm fork of tinywm in libxcb
x11/jbxvt clone of xvt terminal in libxcb

ittywm and jbxvt running together:

```
THR PRI NICE   SIZE    RES STATE    C   TIME    WCPU COMMAND
  1  20    0    13M  2740K select   3   0:00   0.00% jbxvt
  1  33    0    13M  2308K select   2   0:00   0.00% ittywm
```
x11-wm/mcwm and jbxvt running together:

```
THR PRI NICE   SIZE    RES STATE    C   TIME    WCPU COMMAND
  1  20    0    13M  2564K select   1   0:00   0.00% jbxvt
  1  23    0    13M  2528K select   3   0:00   0.00% mcwm
```

Comparison to tinywm and xvt running together:

```
THR PRI NICE   SIZE    RES STATE    C   TIME    WCPU COMMAND
  1  20    0    18M  5708K select   3   0:00   0.20% xvt
  1  34    0    14M  3376K select   1   0:00   0.00% tinywm
```

jbxvt still calls for libx11 and relies on it for compiling. The headers call for it, even if the other sourcecode doesn't need it.


----------

