The X New Developer’s Guide: The X Client Ecosystem (2024)

Alan Coopersmith

On both the client and server side of X, there is a largemass of infrastructure that must be mastered to get workdone. This chapter covers the client side. Start here tolearn how to build, maintain and develop X applications.

The Structure of an X Client Application

A typical X client application is built on top of a numberof libraries, providing common functionality that manyapplications need.

Applications typically use a "toolkit" that provides commonuser interface elements, such as menus, buttons, text fieldsand other standard widgets. Modern toolkits include Qt,GTK+, and FLTK. Older toolkits, still supported for legacyapplications, include the Athena Widgets (Xaw) and Motif(Xm). Some toolkits are cross-platform, which can assist inmaking your application usable in non-X environments such asWayland, Android, MacOS X or Microsoft Windows. A list of Xtoolkits is available athttp://en.wikipedia.org/wiki/List_of_widget_toolkits.

Most X applications need to render something. The Xcommunity has great library support for efficient,convenient drawing in most environments. These librariesdeal with optimizing for specific video hardware, outputformats, etc. For 2D graphics, the Cairo libraryis commonly used today, both byapplications directly and by toolkits for their renderingneeds. For 3D graphics, the OpenGL API is the industrystandard, implemented in the free software stack by theMesa libraries.

Proper text handling is trickier than most developersrealize, especially if they have only been exposed toseven-bit ASCII text. Handling Unicode characters, loadingappropriate fonts for different languages, figuring out howto place characters in languages with complex rules forconnecting characters or overlaying diacritical marks, evenjust figuring out whether characters are displayed inleft-to-right or right-to-left order: these are all solvedproblems for existing libraries such as Pangoand HarfBuzz. Toolkits use these libraries tohandle text layout in the widgets they provide, Cairo usesthem for text in canvases it renders, and applications usethem for any text they need to place on screen directly.

Underneath all these libraries is X's Xft extension. Xftprovides for actually displaying text glyphs on screen,using fontconfig to find anappropriate font for each glyph, andFreeType to render each glyph as an image thatXft can send to the X server for display.

The actual communication with the X server is handled by oneof two sets of libraries---Xlib or XCB. Each library familyprovides programmatic access to the actual X protocolrequests, hiding the details of X11 protocol connections andencoding/decoding from the clients. Xlib and XCB are coveredin more detail in the Xlib and XCB chapter of this book.

While it is theoretically possible to write an X clientusing pure system calls, generating all the X protocolmessage encoding and decoding yourself, that would usuallybe a massive waste of time and a source of bugs. It is alsopossible to write an X client using just the X11 libraries,and to generate all the code for drawing menus, buttons,text yourself, but that also wastes much time reinventingthe wheel; multiple programmer-years of effort would berequired to get the full functionality required to supportinternationalization, accessibility, desktop integration,input handling, and many other features provided bytoolkits.

Building X client code

X.Org, along with many of the open source toolkits andlibraries mentioned above, has standardized on the use of thepkg-config systemfor determining the required set of compiler and linker flags touse when building software that uses these libraries.

For example, to find the flags needed to link against thelibxcb and libxcb-util libraries, you would run:

pkg-config --libs xcb xcb-util -lxcb-util -lxcb

You should not simply copy the results into your buildscripts. Instead, run pkg-config at build time: the resultsmay vary by platform, by install location (different "-I" or"-L" flags to find the right path), or by version asrequirements change.

If your software is built using the GNU autoconf system,pkg-config provides a simple macro you can use for findingthe required flags for your build in the configure.acscript. You can also specify minimum required versions of agiven library, as shown in this example:

PKG_CHECK_MODULES(XCBLIBS, [xcb >= 1.6] xcb-icccm xcb-shape)

If all the required libraries are found, with sufficientversions and any required dependencies they specify in theirpkg-config files, then autoconf will provide variables inthe generated Makefiles named XCBLIBS_CFLAGS andXCBLIBS_LIBS. These variables will provide the flags youneed to pass to the compiling and linking stages of yourbuild.

X libraries

The following list are the X libraries offering C languageAPI's maintained by X.Org. As described above, these API'sprovide a lower level of functionality on top of which thehigher level libraries from other providers arebuilt. Language binding layers for other languages, such asPython, Perl and Tcl, are also available from varioussources.

There are two generations of libraries at the core of the Xprotocol stack - the newer XCB and the older Xlib. TheXlib and XCB chapter in this guide explainsthe differences, and describes the interoperability between thetwo families.

Documentation for almost all of these libraries is includedwith the libraries themselves, in the form of Unix man pagesand DocBook/XML reference docs. For those with DocBookdocs, the HTML, PDF, and plain text format documentationgenerated from those docs has been posted online athttp://www.x.org/releases/current/doc/.

XCB family of protocol and utility libraries

The newer generation of X protocol encoding & decodinglibraries are built on top of the XCB core, with theencoding & decoding functions auto-generated from XMLdescriptions of the protocol. libxcb provides both theconnection management functions, and the handling of thecore X protocol, with additional libraries provided for eachX extension:

libxcb-composite libxcb-res libxcb-damage libxcb-screensaver libxcb-dpms libxcb-shape libxcb-xineramalibxcb-dri2 libxcb-shm libxcb-xinputlibxcb-glx libxcb-sync libxcb-xprintlibxcb-randr libxcb-xevie libxcb-xtestlibxcb-record libxcb-xf86dri libxcb-xvlibxcb-render libxcb-xfixes libxcb-xvmc

Unfortunately, not all extensions are yet supported by XCBlibraries. XKB is a noticeable gap---libxcb-xkb is stillbeing worked on, due to the complex nature of the XKBprotocol definition. Two extensions, BigRequests andXC-MISC, are fundamental to the handling of other requests;these extensions are thus built directly into libxcb insteadof being provided via separate libraries.

There are also some utility libraries built on top of theXCB protocol libraries to provide common higher-levelfunctions. These libraries are still under development, andare still seeing some changes to their API between versionsthat may break compatibility.

• libxcb-icccm and libxcb-ewmh: These libraries providefunctions to get and set the properties specified in theICCCM and EWMH standards for interacting with windowmanagers and desktop environments. (See the"Properties" section in the "Concepts"chapter for more details on these.)

• libxcb-image: This library moves images (client-sidepixmaps) to and from the X server. In Xlib, XImage andXShmImage provide similar functionality.

• libxcb-render-util: This library provides conveniencefunctions for drawing images and text using the Renderextension.

• libxcb-util: This library is a grab-bag of conveniencefunctions and definitions that failed to fit into theothers. The library includes standard atom constants,atom caching, event decoding, and display structureoperations.

Xlib family of protocol and utility libraries

The older generation of X protocol handlers is built on topof libX11, a library known colloquially as Xlib. Besidesprotocol handling, libX11 also includes a large number ofutility functions. Xlib provides support for internationalinput methods and for ICCCM property handling. It alsoprovides legacy versions of other functionality (such ascolor management) now commonly provided in higher levellibraries; the modern libraries offer better integrationwith toolkits and applications. Like the XCB family, manyextensions have their own Xlib-based library for handlingthe requests for that extension. A common set of olderextensions is, however, grouped into a single libXextlibrary.

Libraries for individual extensions:

Extensions covered by libXext:

• DBE - Double Buffering Extension
• DPMS - Display Power Management Signaling
• MIT-MISC - X11R3 Bug Compatibility Mode [obsolete]
• AppGroup - Broadway Application Grouping [obsolete]
• EVI - Extended Visual Information
• Generic Event - X Generic Event extension
• LBX - Low Bandwidth X [obsolete]
• MultiBuf - Multiple Buffering Extension [obsolete]
• SECURITY - X Security model extension
• SHAPE - Non-rectangular Shaped Window Extension
• MIT-SHM - Shared Memory Images/Pixmap Extension
• SYNC - X Synchronization Extension
• TOG-CUP - Colormap Utilization Protocol extension [obsolete]
• XTestExt1 - X11 Input Synthesis Extension [obsolete]

Quite a few of those extensions are no longer in common use,or supported by the X server. However, since libXext bundledthem into the same library, they cannot be easily removedwithout breaking backwards compatibility with existingprograms.

X Toolkit Intrinsics and legacy toolkits

X.Org originally developed the X Toolkit Intrinsics (libXt)to provide common functionality to multiple toolkits. libXtallowed for configuration via a common X resource format, astandardized event loop, and other underlyingfunctionality. libXt was used in many early toolkits,including X.Org's sample Athena Widgets toolkit (libXaw),Sun's OpenLook toolkit (libXol), and the Open SoftwareFoundation's Motif toolkit (libXm). Modern toolkits howeverhave mostly eschewed libXt. These toolkits use somecombination of other common layers (glib for event loops,for instance) and their own toolkit-specificdesktop-specific library code. Thus, libXt is maintainedmainly for use by legacy applications.

The Athena Widgets toolkit is the toolkit used by many X.Orgsample applications, as well as some applications from othersources. The original version (libXaw) has a very simple 2-Dlook, while the enhanced fork (libXaw3d) updates the lookwith a more 3-D feel. Neither version is activelydeveloped. The Athena Widgets, like the underlying libXt,are mainly maintained for existing applications. Writing newapplications against Athena Widgets is discouraged. Thetoolkit lacks much of the functionality needed for properoperation of modern applications. For example,internationalization support is minimal, as is support foraccessibility technologies such as screen readers oralternative input devices for users with physicaldisabilities. It would also be awkward to try to use theAthena Widgets on non-traditional computing devices such ascell phones or tablets.

Both libXt and the Athena libraries are built on top of theXlib family of protocol handling libraries.

Libraries for related protocols

While the X11 protocol and it's extensions are the core ofthe X Window System, they are not the only protocols used inX, and additional libraries are provided for software thatneeds to operate over these protocols.

• libFS handles the encoding and decoding of the X FontService protocol, allowing X servers or other programsto retrieve fonts from a remote XFS font server. This ispurely legacy functionality, and should not be used inmodern client or server configurations.

• libICE supports communication between multiple clientsusing the Inter-Client Exchange protocol.

• libSM covers the X Session Management protocol, built ontop of libICE. libSM provides desktop environments amechanism to save the state of running clients beforestopping an X session, and to restore this state at nextlogin.

• libXdmcp provides the encoding and decoding for the XDisplay Manager Control Protocol. XDMCP provides apoorly-resourced local X server (typically an Xterminal) with the ability to authenticate clients on aremote computer.

Utility libraries

X.Org provides a handful of utility libraries, providingconvenient encapsulation of functions needed by multipleclients. Many of these are based on the Xlib protocollibrary stack.

• libXau manipulates .Xauthority files, used by xauth, Xservers, and display managers to store shared secretdata such as MIT-MAGIC-COOKIEs used for authenticating Xclients attempting to connect to an X server. libXau isused by both Xlib and XCB.

• libXcursor handles the alpha blended and animatedcursors provided by the Render and XFixes extensions,including file formats for storing and reading them fromdisk. libXau is used by both Xlib and XCB. [iirc --po8]

• libXfont is the implementation of the legacy coreprotocol font rendering mechanism. libXfont is used byX servers and the XFS font server to load and renderfonts in a variety of formats. The rendering code forsome of these formats is built into the library. Otherformats are passed to the FreeType library torasterize. Some of the X.Org font utilities use libXfontto manage font files and metadata files such asfonts.dir. Normal clients will not link to libXfontdirectly, but access the functionality via X protocolrequests. Modern clients avoid using X core fontsentirely, relying on fontconfig / libXft or on librariesutilizing these tools. libXfont thus represents strictlylegacy functionality.

• libfontenc handles the encoding tables used to map fontsacross character encodings such as ISO-8859 and Unicode.Like libXfont, libfontenc is legacy software used by theX.Org core font infrastructure software rather than bynormal clients.

• libXft is a font library that clients use directly. Itcooperates with fontconfig to find fonts, with FreeTypeto render them, and with either libXrender or libX11 todraw the rendered text on screen or into a pixmap. Someclients use libXft directly, but most use higher-levellibraries such as pango or API's provided by theapplication toolkit. These API's handle text shaping andlayout rules to determine proper placement andconnection of glyphs in complex languages.

• libXmu and libXmuu are a collection of miscellaneousutilities used by the X.Org sample clients. libXmuuconsists of utilities that build upon just the corelibX11 libraries. libXmu depends on the Athena Widgetstoolkit, pulling in libXaw and libXt.

• libXpm supports the XPM XPixMap image file format. XPMrepresents image data in a portable ASCII text format.This was especially important in legacy X applications,which tended to have XBM or XPM images compiled rightinto the C code. Modern applications use externallibraries or toolkit functionality to access imagefiles.

• libxtrans is the shared code implementation of thetransport layer (sockets, pipes, etc.) used forcommunications by a number of the protocolimplementations in the X Window System, such as libX11,libICE, libFS, xfs, and the X server. It is notactually a shared library like the others, but shared Ccode which is built into each library or program. TheXCB library stack has its own connection management codein libxcb and does not use xtrans. Indeed, XCB replacesone of several instantiations of libxtrans in modernXlib.