Swift for Linux part 2 – Using C libraries with Swift

Swift developers coming from Apple’s iOS and OS X environments are use to using the Cocoa and Cocoa Touch frameworks however these frameworks are not available in the Linux environment.  When we develop Linux applications and utilities with Swift we need to use the system libraries provided by the Linux environment.  In this post will look at how we can use these system libraries with our Swift code to build useful applications and utilities. 

In this post we will look at the Glibc module that Apple provides for us which includes the majority of the Linux Standard Library.  We will also look at how we could create our own modules to add additional system libraries not included in the Glibc module.  To demonstrate the concepts discussed we will conclude this post by building a simple command line utility that will list the IP addresses of the device that it is run on.

Modules

A module in Swift is code that is distributed as a single unit that can then be imported into other modules using Swift’s import keyword.  Frameworks and applications are examples of modules in Swift. In this post we are going to be looking at a special kind of module that can be used to map system libraries so we can import and use them into our Swift code. 

The Linux port of Swift comes with a predefined module named Glibc that contains most of the Linux standard library however there are numerous headers that have not been imported in it.  This module is similar to the Darwin module on Apple platforms.  Lets start off by looking at tthe Glibc module and then we will look at defining our own modules to map other system libraries that we may need.

To see what headers are defined in the Glibc module view the module.map file located in the usr/lib/swift/glibc directory of your Swift installation.  Don’t worry if you do not fully understand the format of this file at this time, we will be looking at how to create module.map files later on in this post.  For right now, knowing that any header that is defined in this file will be included simply by importing the Glibc module is enough.

In my previous post, Swift for Linux part 1, we saw an example of how to use the Glibc module.  In that example we created an extension to the Array type that would randomly select an element from the array.  We used the random() function provided by the system to generate the random number in the extension.  Lets take a look at the code for this example again so we can see how it worked.  The following code shows the Array extension:

import Foundation

import Glibc

extension Array {

   

    func getRandomElement() -> Element {

           let index = Int(random() % self.count)

           return self[index]

    }

} 

In this example the code starts off with two import statements.  The first import statement imports the Foundation framework.  The Foundation framework defines the basic functionality that is needed for most applications.  Most if not all of your Swift source files will need to import the Foundation framework.

The second import statement imports the Glibc framework.  This import statement allows us to use the system libraries that are defined in the Glibc framework.  If we tried to build the code without importing the Glibc framework we would receive the following error.

/xxx/xxx/xxx/xxx/MakeFtpFile/Sources/ArrayExtension.swift:6:19: error: use of unresolved identifier 'random'                

let index = Int(random() % self.count)

                 ^~~~~~

What this error tells us is the compiler does not know anything about the random() function.  If we look at the man page for the random() function (command: man random) we see that we need to import the stdlib.h header if we want to use this function.  If we look at the headers that are imported in the Glibc framework we will see that the Glibc framework does include the stdlib.h header.  By importing the Glibc Framework we are essentially importing all of the header files defined within it therefore we are importing the stdlib.h header which defines the random() function.  This will allows us to use the random() function within our code.

If you are new to developing applications and utilities in the Linux environment you will want to get use to using the Linux man pages to retrieve information about the system libraries and the functionality they provide.  These man pages will give you a wealth of knowledge about the functions that you are using.

Earlier we mentioned that the Glibc framework contains most of the Linux standard library so what do we do if we want include libraries that are not in the Glibc framework?  These libraries could be part of the Linux standard library that are not currently defined in the Glibc framework or libraries that are not part of the Linux standard library itself.  Lets look at how to include these libraries and also how to use the functionality they provide in our code by creating a custom module.

Creating a custom module

To create a custom module we will begin by creating a directory to put the files for the module in.  This will be the module’s main directory.  Within this directory we will need two files.  The first is an empty file named Package.swift and the second is named module.modulemap. 

Within the module.modulemap file we will define the headers we want to import and the libraries that contain the functionality defined in the headers.  The example below shows the format of the module.modulemap file

module CMyModule [system] {

    header "/usr/include/mylibheader.h"

    link "mylib"

    export *

}

The first line defines the name for our module.  This name is what we will import in our Swift files.  In this sample the module’s name is CMyModule.  The next line defines the full path to the header file that we want to import.  The third line tells the compiler that the functionality defined in the header can be found in the mylib library so we will need to link it.  The last line says to export all of the functionality.

The Swift package manager uses git and git tags to manage packages and modules therefore once we create both files we will want to create a git repository for our module.  To do this we run the following commands in the main directory for the module.

git init

git add .

git commit -m "Initial Import"

git tag 0.1.0

Before we show how to use a module, lets go ahead and create the module needed for our example.

Creating the Cifaddrs module

In this post we will be creating a utility that will list the network addresses of the device it is running on.  For this utility we will use the getifaddrs() function.  The man page for the getiffaddrs() function shows that we will need to import sys/types.h and ifaddrs.h header files.  In addition to these two headers we will also need to import the netdb.h, sys/socket.h and arpa/inet.h headers for other functions that we will be using in our code.  

Since some of the headers that we need for our project are not defined in the Glibc framework we will create our own module so we can import them.  Lets begin by creating a directory name Cifaddrs and the two files that we need:

mkdir  Cifaddrs

cd Cifaddrs

touch Package.swift

touch module.modulemap

Now we will need to define the five headers in the module.modulemap file.  To do this we would put the following code into module.modulemap file.

module Cifaddrs [system] {

    module types {

        header "/usr/include/x86_64-linux-gnu/sys/types.h"

        export *

    }

    module ifaddrs {

        header "/usr/include/ifaddrs.h"

        export *

    }

    module Socket {

        header "/usr/include/x86_64-linux-gnu/sys/socket.h"

        export *

    }

   

    module inet {

        header "/usr/include/arpa/inet.h"

        export *

    }

    module netdb {

        header "/usr/include/netdb.h"

        export *

    }

}

Now we need to create our git repository by running the following commands in the module’s main directory.

git init

git add .

git commit -m "Initial Import"

git tag 0.1.0

Since the swift package manager uses the tag for versioning, you will want to update the tag whenever you update code.  To make it easier to create the initial structure for the module, I created a shell scripted named createmodule.sh.  This script is very similar to the createproject.sh that I created in my last post to create the structure for a project.  The following is the code for the createmodule.sh script.

#!/bin/bash

#title:        createmodule.sh

#author:       Jon Hoffman

#description:  Creates the directories and files need for a Swift module

#date:         012816

#version:      1.0

#usage:        createmodule.sh {module name} {optional: dir name}

MODULENAME=""

DIRNAME=""

PACKAGEFILENAME="Package.swift"

MODULEFILENAME="module.modulemap"

#Check to make sure at least one command

#line arg is present otherwise exit script

if [ $# -le 0 ]; then

    echo "Usage: creatproject {Name for Module} {Optional directory name}"

    exit 1

fi

#Assign the value of the first command line arg to the module name

#if a second command line arg is present assign that value to the

#the directory name otheerwise use the module name

MODULENAME=$1

if [ "$1" != "" ]; then

    DIRNAME=$1

else

    DIRNAME=$MODULENAME

fi

#Check to see if the directory exists and if so display an error

#and exit

if [ -d "$DIRNAME" ]; then

    echo "Directory already exists, please choose another name"

    exit 1

fi

#Make the directory structue and create the neccessary files

mkdir -p $DIRNAME

cd $DIRNAME

touch $PACKAGEFILENAME

touch $MODULEFILENAME

echo "module $MODULENAME [system] {" >> $MODULEFILENAME

echo "" >> $MODULEFILENAME

echo "}" >> $MODULEFILENAME

git init

git add .

git commit -m "Initial Import"

git tag 0.0.1

The createmodule.sh script takes one required and one optional command line argument.  The first (required) command line argument is the name of the module and is used to create the module.modulemap file.    The second (optional) command line argument is the name for the module directory.  If the second command line argument is not present then we use the name of the module (first command line argument) for the directory name.  The following examples show how we would use the createmodule.sh script to create a module named Clib in a directory named Clib.

./createmodule.sh Clib

The previous command would create a directory named Clib.  It would also create the Package.swift and module.modulemap files.  The following code shows what the newly created module.modulemap file would look like.

import PackageDescription 

module Clib [system] {

}

We used the module name (first command line argument) to define the module name in this module.modulemap file.  You can find the code for the createmodule.sh file on my Scripts for Swift Linux development github page.

Now that we have created our module, lets see how to use it in a project.

Using the Cifaddrs module

Now that we have our module created, lets look at how we would use it in a project.  The first thing we will want to do is to create the project.  For this I will use my createproject.sh script like this:

./createproject.sh getifaddrs

This will create the directory structure and files needed to start the project with.  To tell the compiler to use our newly created module we will need to add a dependency to the Package.swift file.  We would add this dependency as shown with the following code:

import PackageDescription

let package = Package(

    name:  "getifaddrs",

    dependencies: [.Package(url: "../Cifaddrs", majorVersion: 0, minor: 1)]

)

The url defines the path to the module.  This can be the full file system path as shown in our example or an Internet path to a github repository.  We can also define multiple dependencies by separating the packages by a comma as shown here:

let package = Package(

    name:  "getifaddrs",

    dependencies: [.Package(url: "../modOne", majorVersion: 0, minor: 1),

 dependencies: [.Package(url: "../modTwo", majorVersion: 0, minor: 1)]

)

We are now ready to use the libraries defined in the module within our application.  The following code shows the main.swift file that will retrieve the list of IP addresses and print them out.

import Foundation

import Cifaddrs

// Get list of all interfaces

var ifaddr : UnsafeMutablePointer<ifaddrs> = nil

if getifaddrs(&ifaddr) == 0 {

    // Loop through all interfaces

    var ptr = ifaddr

    while (ptr != nil) {

       

        // Get address and interface name

       var addr = ptr.memory.ifa_addr.memory

        var ifname = String.fromCString(ptr.memory.ifa_name)

        // If addr is IPv4 or IPv6

        if addr.sa_family == UInt16(AF_INET)

|| addr.sa_family == UInt16(AF_INET6) {

            // Convert interface address to a string and print it

            var ad = [CChar](count: Int(NI_MAXHOST),

repeatedValue: 0)      

            if (getnameinfo(&addr, socklen_t(32), &ad,

socklen_t(ad.count), nil, socklen_t(0), NI_NUMERICHOST) == 0) {

                   

                if let address = String.fromCString(ad) {

                      print("\(ifname):  \(address)")

                }

            }

        }

        ptr = ptr.memory.ifa_next

    }

    freeifaddrs(ifaddr)

}

Notice that in the second line we import the Cifaddrs module using the import keyword.   This essentially imports all of the headers that are defined in the Cifaddrs modeul.modulemap file.

The code is commented so you can see what is going on but I do want to point out a couple of items that will help you when it comes to use Linux system libraries with swift.  The first item is how to use C pointers.  The following code show how we would use the getifaddrs() function in normal C code:

struct ifaddrs *ifap;

getifaddrs (&ifap);

In this code we create a pointer to an ifaddrs structure.   In Swift we would write this same code like this:

var ifap : UnsafeMutablePointer<ifaddrs> = nil

if getifaddrs(&ifap)

Notice in Swift we use the UnsafeMutablePointer structure to declare a pointer to an object type in memory.  In this case the object type is the ifaddrs structure. 

The other item that I want to point is how we are accessing the information within the ifaddrs structure using pointers.  In C we would access the information like this:

ifa->ifa_addr

In Swift we access the information like this:

var addr = ifa.memory.ifa_addr.memory

It took me a little bit of time to wrap my brain around this.  Having a pretty good C background this line of code seemed just wrong to me but once I really wrapped my brain around the basic concepts here it really made since.  Basically in Swift we want to avoid using pointers if we can so there isn’t a simple interface to use them.  Notice in our Swift line of code we have ifa.memory.ifa_addr.memory.  The ifa.memory part of this line gets the value in memory that the ifa pointer is pointing too.  Then the second part of this line ifa_addr.memory gets the value in memory that the ifa_addr pointer is pointing too.

If we wanted to get the pointer rather than the actual value, we would use this line instead:

var addr = ifa.memory.ifa_addr

In this line the addr variable would contain an UnsafeMutablePointer.

It does take a little bit of work to include the Linux system libraries in our Swift code but overall I think Apple did a great job making it as easy as possible while avoid a lot of the complexity of C.  I will hopefully writing more posts on how to use the Swift port for Linux.