Swift for Linux part 1 – Building Applications

At the end of last year Apple open sourced Swift and released a port for the Linux operating system.  At the time of the release I really wanted to try the Linux port of Swift however I was right in the middle of writing my new book on Protocol-Oriented programming so I was unable to really spend any time with it.  Now that I am finishing up the new book, I am able to spend some quality time with the Swift Linux port.  These next few posts will show what I have discovered.

In this first post we will look at several examples that will demonstrate how to write and build applications with the Swift port for Linux.  We will also create a shell scripts that we can use to create the directory structure and minimum files needed to use Swift’s package manager to build our applications.

We will not go over installing Swift on Linux because Apple has very good documentation on how to do this.  You can find the documentation on the Swift.org  

Using Swiftc

Once we install Swift on our system and set up the path we should be able to run the Swift compile.  To run the compiler we would use the swiftc command.  To see how we could use swiftc lets create a file named helloWorld.swift and put the following code in it.

import Foundation

print(“Hello World”)

Now run the command swiftc helloWorld.swift.  If all went well, we would have an application named helloWorld that we can run like this:  ./helloWorld.  This application will (obviously) print Hello World to the console. 

There are numerous options with the swiftc command and we can see them by using the –help option like this:  swiftc –help. 

Setting up the directory structure for an application

We could use the Swift command line compiler to compile our applications but if we had multiple files and/or dependencies, our compile command could get very complicated and hard to maintain.  Anyone that has used Make files or other similar utilities to build C projects can verify that building applications in this manner can get pretty complicated.

Apple has given us a much better approach for developing applications and modules.  This approach does require us to set up a specific directory structure and also a manifest file named Package.swift.

The following diagram shows how we would set up the directory structure and also the required files:

{project dir}

     |

     |---- Package.swift {file}

     |

     |------ Sources {directory}

                |

                |----main.swift {file}

This diagram shows that we have one subdirectory below our main project directory named Sources.  It also shows that we need two files.  The first file is the Package.swift file which is located in the main project directory and the main.swift file which is located in the Sources directory.

The Package.swift file is a manifest file that tells the compiler about our project and any dependencies that it may have.  At minimum we need to define a name for our project.  The following example shows the minimum manifest file that simply defines the name of the project which is HelloWorld.

import PackageDescription 

let package = Package(   

    name:  "HelloWorld"

)

The main.swift file is a special file that is the entry point for our application.  It is also the only file that is allowed to have top-level code in it.  Top-level code is code that is not encapsulated in a function or type.

To simplify the process of starting a project I created a shell script named createPoject.sh that will create the directory structure, manifest file and main swift file for a project.  The Package.swift and main.swift files are created with the minimum code needed for our project.  You can find this and other scripts that I use with my Swift Linux development on my Scripts for Linux development github page. The following shows the code for the createproject.sh script.

#!/bin/bash

PROJECTNAME=""

DIRNAME=""

PACKAGEFILENAME="Package.swift"

MAINFILENAME="main.swift"

SOURCESDIRNAME="Sources"

#Check to make sure at least one command

#line arg is present otherwise exit script

if [ $# -le 0 ]; then

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

    exit 1

fi

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

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

#the directory name otheerwise use the project name

PROJECTNAME=$1

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

    DIRNAME=$1

else

    DIRNAME=$PROJECTNAME

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 structure

mkdir -p $DIRNAME/$SOURCESDIRNAME

#Change to the project's directory and create the Package.swift file

cd $DIRNAME

touch $PACKAGEFILENAME

echo "import PackageDescription" >> $PACKAGEFILENAME

echo "" >> $PACKAGEFILENAME

echo "let package = Package(" >> $PACKAGEFILENAME

echo "    name:  \"$PROJECTNAME\"" >> $PACKAGEFILENAME

echo ")" >> $PACKAGEFILENAME

#Change to the Sources directory and create the main.swift file

cd $SOURCESDIRNAME

touch $MAINFILENAME

echo "import Foundation" >> $MAINFILENAME

echo ""  >> $MAINFILENAME

echo "print(\"Hello from Swift\")" >> $MAINFILENAME

#Done

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

./createproject Hello

The previous command would create a directory named Hello and also the Sources subdirectory.  It would also create the Package.swift and main.swift files.  The following code shows what the newly created Package.swift file would look like.

import PackageDescription 

let package = Package(    

     name:  "Hello"

)

We used the project name (first command line argument) to define the package name in this 

Package.swift file.  The newly created main.swift file would look like this.

import Foundation 

print("Hello from Swift")

As we mentioned earlier, the main.swift file is the entry point for our application therefore the code that is in this file is run when our application starts.

If we wanted the main project directory to have a different name from our project name then we would use the second command line argument. This next example shows how we would create a project named Hello in a directory named HelloDirectory.

./createproject Hello HelloDirectory

The createPoject.sh script actually creates a full project that can be built as is.  Lets see how we would build this new project.

Building a project

To build our project we would use the following command; swift build.  To see the options with this command we would use the --help option like this:  swift build --help.  Notice the two dashes, all of the other help options for the other swift commands (IE:  swiftc and swift commands) use the single dash.

Let build our project that we created in the last section.  Change to the project directory that was created by the createPoject.sh script and then run swift build.  If all went well you should see output similar to this:

Compiling Swift Module 'hello' (1 sources)

Linking Executable:  .build/debug/hello

If we see this output, we will have an executable named hello in the .build/debug directory.  You can execute it like this:  .build/debug/hello

Creating a project with multiple files

Recently I had the need to create a number of files that were of a specific size (I was testing sftp transfer speeds over different connection types).  I decided that this would be a good project to do in Swift.  The requirements that I had for this project was to create a number of files that contained random characters and were of specific sizes.

What I decided to do was to create an array that contained each character of the alphabet and then randomly select a character from the array until the file was the size I needed.  I also decided that I would create an extension to the array type which would randomly select an element from the array.  I created a file name ArrayExtension.swift in the Sources directory that contained the following code:

import Foundation

import Glibc

extension Array {

    func getRandomElement() -> Element {

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

return self[index]
  

}

}

Don’t worry too much about how this code works at this time.  My next post will be about using C libraries with Swift and will explain more about modules and using C functions.  You can however see that generating a random number with the Swift port for Linux is a little different than with Swift for OS X or iOS.

Now in our main.swift file we can put the following code:

import Foundation

import Glibc

let num = 1024

var str = ""

let alpha = ["a","b","c","d","e","f","g","h","i","j","k",

"l","m","n","o","p","q","r","s","t","u","v","w","x","y","z"]

srandom(UInt32(NSDate().timeIntervalSince1970))

for i in 0..<num {   

str += alpha.getRandomElement()

}

print(str)

var filename = "test\(num)file.txt"

do {
   

try str.writeToFile(filename, atomically: true,encoding:

NSUTF8StringEncoding)

} catch let e {
   

print("Error: \(e)")

}

Once again, we are not worried about how this code works.  We are mainly focused on creating and building a project with multiple files.  Now we should have two files in our Sources directory named main.swift and ArrayExtension.swift.  Now if we go back to the main project directory (the one with the Package.swift file) we can run the swift build command and our project should compile to an executable. 

What we just saw is the swift build command will compile all of the files in the Sources directory and include them in our project.  This is a lot easier than creating complex Make files with C.  I would recommend that unless there is a specific requirement to use the swiftc command that you use the swift build command as we saw in this post.

Developers that are use to using Swift to build iOS and/or OS X applications are also use to using the Cocoa and Cocoa Touch frameworks however these frameworks are not present in the Linux environment.  Instead we need to use the C libraries that are provided with Linux.  In my next post I will show how to create modules that will expose those libraries so we can use them with our Swift applications.

RSStockFighter Framework

In this post I will talk about the StockFighter framework that I crated for the Swift language named RSStockFighter.  If you have not heard about StockFighter, it is a really nice (and free) online coding challenge where you need to solve a series of problems by using your coding skills.   You can read about StockFigher here.  The GitHub repository for RSStockFighter is here.  I am currently finishing up my third book on the Swift programming language so I have not had a lot of time to play the StockFighter game (yet) but I have used RSStockFighter to make it though level 4. 

I first read about StockFighter on DZone.  The idea behind StockFighter is you are a developer that has been tasked to create an automated trading system designed to automate stock trading for your firm.  The game has several levels that progressively get harder.  The first few levels are designed to get you familiar with the API while later levels require you to incorporate logic to determine when to buy and when to sell your stocks.  Don’t worry if you do not have any stock market experience, the game teaches you everything you need to know to complete each level. 

All of the APIs are REST based which means you can use any language you want to complete the levels.  I obviously chose to use the Swift language.  Why?  Because I really like programming with the Swift language.  RSStockFighter is designed to make it very easy to interact with the StockFighter API so you can focus on solving the levels rather than the backend network code. 

When I started looking at the StockFighter API, my first thought was I needed to create a framework for the API so I would not need to keep creating or cutting/pasting the code to perform the network requests in each challenge.  In this post I will explain how I designed RSStockFighter and how you can use it in your code.

At the time I am writing this document, StockFighter has ten documented API calls (I have currently implemented seven of the calls in RSStockFighter). One of my biggest concerns is the StockFighter challenge has not been around very long therefore I suspect they will be changing and/or adding to the API.  This means that it needs to be easy to add new API calls to RSStockFighter.  When I have a design problem like this I usually start off by pulling out one of my design pattern books and look through it to see if any of the patterns may solve my problem.  In this case the command pattern was perfectly suited for my needs.

The command pattern falls under the behavioral patter group.  In this pattern we encapsulate the logic of our actions into types that conforms to a command protocol.  We can then provide instances of the command types for use by an invoker.  The invoker will use the interface provided by the protocol to invoke the actions on the types that conform to that protocol.  What this means is we will create a separate command type for each one of our API calls.   We will then submit instances of these types to our invoker which will make the call to the StockFighter API.

The class structure to make our API calls will look like this:

The StockFighter request types will encapsulate the information needed to make the individual requests.  The RSStockFighterTransaction type will contain an instance of a StockFighter request type and also the information to make the network request.  Finally the RSStockFighterTransactionRequest will contain methods to make the actual network request to the StockFighter API.

I created a type named StockFighterHelper which implements the Façade pattern to hide the underlying RSStockFighterTransaction and RSStockFighterTransactionRequest types.  I did this for two reasons.  The first is to hide the complexity of the types and the second is to make it easy to change the interfaces of these types if needed.

In addition to the seven StockFighter request types we also have seven StockFighter response types.  These response types will encapsulate the logic needed to parse the response.  This will make it easy to pull the information from the response, as we need it. 

Enough about the design of RSStockFighter, lets see how we would use it.  We will start off by seeing if the StockFighter API is up.  The following code will make a request to check the status of the stockFighter API.

func apiStatus() {

       

    let request = StockFighterAPIStatus()

       

    StockFighterHelper.sendStockFighterTransaction(request, success: {

       (dict:NSDictionary!) -> Void in

        self.checkStatusResponse(dict)

        }, failure: {

            (str: String) -> Void in

            print("Error:  \(str)")

        })
}

In this function we begin by creating an instance of the StockFighterAPIStatus type.  We then call the static sendStockFighterTransaction() method from the StockFighterHelper protocol.  The sendStockFighterTransaction() method takes three parameters which are:

• transType:  An instance of a type that conforms to the StockFigherRequestType type which contains the information for our request. 
• success:   A completion handler that will be called if the StockFighter API call was successful
• failure:  A completion handler that will be called if the StockFigher API call failed.

In this example we set the transType parameter to an instance of the StockFighterAPIStatus type.  In the success completion handler we call a method named checkStatusResponse() and in the failure completion handler we print the error message to the console.

The checkStatusResponse() method called if the API call was successful looks like this:

func checkStatusResponse(dict: NSDictionary) {

    let response = StockFighterAPIStatusResponse(dict: dict)

    print("StockFighter is up:  \(response.ok)")
}

In this method we use the StockfighterAPIStatusResponse type to parse the response.  We then print a message to the console letting us know if the Stock Fighter API is up or not.

That was pretty easy but lets look at a more difficult API call like placing a new order.  The following code demonstrates how to do this:

let order = StockFighterOrder(symbol:SF_STOCK_SYMBOL, price:95.00,qty: 100,direction:SF_OrderDirection.Buy,orderType:SF_OrderTypes.Limit.rawValue)

       

StockFighterHelper.sendStockFighterTransaction(order, success: {

    (dict:NSDictionary!) -> Void in

        self.checkOrderResponse(dict)

}, failure: {(str: String) -> Void in

        print(str)
})

 

In this example we create an instance of the StockFighterOrder type.  The initializer for this type takes five parameters which are:

• symbol:  The stock symbol for the stock to place the order for
• price:  The maximum price to buy or minimum price to sell the stock at
• qty:  The quantity to buy or sell
• direction:  Specifies if this is a buy or a sell order
• orderType:  The order type

We then pass the instance of the StockFighterOrder type to the static sendStockFighterTransaction() method, just like we did with the API status example, to make the request to the StockFighter API.

If the API call was successful we would parse the response using the StockFighterOrderResponse type like this:

let response = StockFighterOrderResponse(dict: order)

Pretty easy, don’t you think?  The seven StockFighter request types that I have implemented in RSStockFighter are:

• StockFighterAPIStatus
• StockFighterVenueStatus
• StockFighterStocksOnVenue
• StockFighterOrder
• StockFighterOrderBook
• StockFighterQueryOrder
• StockFighterCancelOrder

For each of these request types I also implemented a response parser type which are:

• StockFighterAPIStatusResponse
• StockFighterVenueStatusResponse
• StockFighterStocksOnVenueResponse
• StockFighterOrderResponse
• StockFighterOrderBookResponse
• StockFighterQueryOrderResponse
• StockFighterCancelOrderResponse

There are two enumerations defined in this framework that you will be working with.  These are the SF_OrderTypes and SF_OrderDirection enumerations.  The SF_OrderTypes enumeration defines the type of order we are placing (You can read more about order types in the StockFighter help pages) and has the following values:

• Limit - Immediately matches any order on the books that has an offer price as good or better than the one listed on the order.  This order type is good until cancelled
• Market - Immediately matches any order.  Do not use this type.
• FOK - Fill or Kill:  Immediately fills the whole order.  If it cannot fill the whole order immediately then the whole order is killed
• IOC - Immediate or Cancel:  Immediately fills or partially fills the whole order and then cancels any shares that remains.

The SF_OrderDirection is used to define if the order is a buy or sell order and have the following values:

• Buy - The order is a purchase shares
• Sell - The order is to sell shares

Before you can use the API, you do need to make changes to a couple global constants.  These constants are in the StockFighterInfo.swift file.

• SF_API_KEY – Your API ley
• SF_VENUE – The venue you are using for this challenge
• SF_ACCOUNT – The account you are using for this challenge
• SF_STOCK_SYMBOL – The symbol of the stock you are using for this challenge

Overall the framework consists of six files that you will need to download and include in your project.  These files are:

• StockFighterInfo
• StockFighterKeys
• StockFighterRequestTypes
• StockFighterResponseTypes
• RSStockFighterTransactionRequest
• RSStockFighterTransaction

The GitHub repository for RSStockFighter is located here: 

So why am I releasing this framework?  I would like to see how many Swift Developers can complete this challenge.  As you go though the levels using RSStockFighter, post a comment to this blog posting telling us how far you have advanced (please no hints on how to complete a level).

Is using RSStockFighter cheating at the challenge?  Personally I do not think so.  I see using RSStockFighter like using any other third party framework (like the Alamofire framework) in our applications.  We use third party frameworks in our day to day development work to make our lives easier so we can focus on the business logic, why not use them to make challenges like this easier so we can focus on the business logic.

Good luck and happy coding.