Create a new folder which will host our package. Since we're linking against a C library, we follow the guidance of the Swift Package Manager documentation and prefix our library with the letter C³. We'll name our library CX11.swift

mkdir CX11.swift

In our case, we want to link against an existing C API and we do not intend to write any Swift wrapper code. Linking against C libraries and headers is achieved via the module.modulemap file which contains the necessary directives for the Swift compiler to perform the correct linking. The documentation for the modulemap syntax can be found here. We create the module map file, and edit the contents (via an editor of your choice, in this case we're using nano):

touch CX11.swift/module.modulemap
nano CX11.swift/module.modulemap

X11 is a huge library with a lot of functionality. You can see the contents if you head over to /usr/include/X11. For our example, we don't need to include all the header files in there, instead we really only need two of them: Xlib.h and X.h. For different other libraries, you may need to include more headers. There is a convenient way to include all the headers in a directory which I'll point out below. Apart from including the headers, we also need to tell Swift which library to link against. We're using the link keyword for that. Our modulemap looks like this:

module CX11 [system] {
  module Xlib {
	  header "/usr/include/X11/Xlib.h"
  }
  module X {
	  header "/usr/include/X11/X.h"
  }
  link "X11"
}

We're naming our module CX11 and we're creating two submodules. One for the Xlib and one for X. Each submodule defines the header it needs to import. Finally, we're linking against libx11 via the link statement.

But what if we have not just one header file, but many of them. Module maps allow you to define an umbrella header or an umbrella directory.

Umbrella Header This is a header that contains just references to other headers (via #include) commands. A good example is <Cocoa/Cocoa.h> or <Foundation/Foundation.h> or <gtk/gtk.h>. Umbrella headers are defined via the umbrella keyword:

umbrella header "/usr/include/gtk/gtk.h"

Umbrella Directory Sometimes you have a directory of headers but no umbrella header. In this case you just point Swift to the directory of headers:

umbrella "/usr/include/X11/"

In addition to the modulemap, we'll also need a Package.swift file, otherwise building will fail. This file can be empty though:

touch CX11.swift/Package.swift

The Swift package manager uses Git and Git Tags in order to manage packages. So before we're done, we need to create a Git repository for our Package, add all the files, and create a version tag. This is fairly easy though:

cd CX11.swift
git init
git add .
git commit -m "Initial Import"
git tag 1.0.0
cd ..

The commands above go into the folder, create a new Git repository, add all the files to it, create a first commit, and finally add a version tag (1.0.0) for this commit.

That's it, our package is defined, but how do we use it?

In order to use a package, we need to define a Package.swift file which will tell Swift which packages we intend to import for our project. But first, we need to create a directory for our project.

mkdir swift-x11
touch swift-x11/Package.swift
touch swift-x11/main.swift

Keep in mind that (for this example to work) the swift-x11 folder has to be next to the CX11.swift folder. I.e.:

ls -l
CX11.swift
swift-x11

Before we start writing the actual Swift code to interact with X11, we need to tell our swift-x11 project how to import the CX11 package. This is done, as explained below, via the swift-x11/Package.swift:

import PackageDescription

let package = Package(
  dependencies: [
    .Package(url: "../CX11.swift", majorVersion: 1)
  ]
)

This tells Swift that the package we intend to use is located in the ../CX11.swift folder.

The url (as the name suggests) does not need to be a local one. I've uploaded my own CX11.swift to GitHub, and you could alternatively link directly to the GitHub version as follows:

import PackageDescription

let package = Package(
  dependencies: [
    .Package(url: "https://github.com/terhechte/CX11.swift.git", majorVersion: 1)
  ]
)

After this, we have to define a couple of variables.

• We need the X11 display (i.e. roughly speaking the X11 server connection). This will be the d variable
• We need a placeholder for the X11 window which we create. This will be the w variable.
• We also need to set aside a bit of memory for the X11 Server to store X11 input events. This is the e variable.
• We should also already store the text which we want to display in our window. This is the msg variable
• We need a place to store the current X11 screen (a X11 Display can have multiple screens). This will be the s variable.
• Finally, we need a pointer to the X11 root window, which houses the other windows. This is the rootWindow variable.

// The X11 Display
var d: _XPrivDisplay

// The window which we will create
var w: Window

// The events which X11 generates for us will be stored here
var e = UnsafeMutablePointer<_XEvent>.alloc(1)

// The text to display
var msg = "Hello Swift World"

// A pointer to the current X11 Screen
var s: UnsafeMutablePointer<Screen>

Now that we defined our variables, we need to open our connection to the X11 Server. However, as users can also run this app when no X server is running (i.e. in console mode) we need to make sure that the connection succeeded:

d = XOpenDisplay(nil)
if d == nil {
	fatalError("cannot open display")
}

After we opened the display, we'd like to get the current default screen as well as the current root window. The RootWindow macro is not available⁴, so we will access the memory section of the C struct directly. However, as the current screen s is a UnsafeMutablePointer, we need to add the memory property in order to access the root instance.

// Get the default screen
s = XDefaultScreenOfDisplay(d)

// And the current root window on that screen
let rootWindow = s.memory.root

Finally we have everything in place to create our own window and place it on the screen. We're using the XCreateSimpleWindow function for that. The function has the following parameters:

XCreateSimpleWindow(Display *display, Window parent, int x, int y, 
  unsigned int width, unsigned int height, unsigned int border_width, 
  unsigned long border, unsigned long background);

border and background are color values. In order to not think about color creation, we will simply pass in a reference to the default black and white colors which are defined on the current screen. We have to use the .memory property again.

// Create our window
w = XCreateSimpleWindow(d, rootWindow, 10, 10, 200, 100, 1, 
  s.memory.black_pixel, s.memory.white_pixel)

This will create a new window on the rootWindow position 10/10 of width 200 and height 100. The borders will be black, the background will be white.

Of course, we also want to receive input events from the Xserver. In our case we'd like to know when the window is being displayed so that we can draw it, and we'd like to know when the user pressed a key so that we can quit the app. The first event is the Expose event, the second one is the KeyPress event. Receiving events works by registering event masks via the XSelectInput function:

XSelectInput(d, w, ExposureMask | KeyPressMask)

Now that we created our window, we want to display it. This is done via the XMapWindow function:

XMapWindow(d, w)

Finally we do have everything in place to run our event loop while the window is being displayed. For this, we're using a while loop which continously pulls the XNextEvent function to get new X11 events. Then, we'll test the event to see whether it is a Expose or a KeyPress event⁵. We're testing the events using the swift switch statement:

loop: while true {

  // Wait for the next event
  XNextEvent(d, e)

  switch e.memory.type {
    // The window has to be drawn
    case Expose:
    // draw a small black rectangle
    XFillRectangle(d, w, s.memory.default_gc, 20, 20, 10, 10) 
    // draw the text
    XDrawString(d, w, s.memory.default_gc, 10, 70, msg, Int32(msg.characters.count)) 

    // The user did press a key
    case KeyPress:
    break loop

    // We never signed up for this event
    default: fatalError("Unknown Event")

  }
}

Our e event structure is - again - a UnsafeMutablePointer, so we have to access the actual structure via the memory property. The Expose event means that the window is visible, so we have to re-draw it. Our drawing is very simple: We're using the XFillRectangle call to draw a small black box, and the XDrawString call to draw our initial msg text in the window at position 10, 70. Please note that I don't know whether X11 expects unicode or ascii, so the Int32(msg.characters.count) is probably wrong, but it works in this example.

The other event, KeyPress allows us to break the outer while loop and quit the app once the user enters a key.