A Whirlwind Introduction to git submodules

Posted on October 11, 2014 by idz

I have put off learning how to use git submodules for too long, but one of my projects has been crying out for them for so long that I finally had to act.

The project IDZAQAudioPlayer demonstrates how to use the IDZPrecompiledOgg and IDZPrecompiledVorbis frameworks to play Ogg Vorbis audio. Before using submodules, the frameworks were manually copied into the IDZAudioPlayer/Frameworks directory and checked into the repository.

Adding Submodules

Adding submodules is relatively simple. Change to the directory where you want the submodules to reside and use {bash}git submodule add{/bash} command.

git submodule add https://github.com/iosdevzone/IDZPrecompiledOgg
git submodule add https://github.com/iosdevzone/IDZPrecompiledVorbis

You can simplify the names of the directories for the submodules. For example:

git submodule add https://github.com/iosdevzone/IDZPrecompiledOgg Ogg
git submodule add https://github.com/iosdevzone/IDZPrecompiledVorbis Vorbis

Cloning a Repository with Submodules

Cloning a repository that uses submodules requires a few extra steps. After cloning the repository.

git clone https://github.com/iosdevzone/IDZAQAudioPlayer

Change into the working directory.

cd IDZAQAudioPlayer

Then initialize and update the submodules.

git submodule init
git submodule update


Posted in git | Tagged , | Leave a comment

Getting Travis CI Working with Your iOS GitHub Builds in Under 10 Minutes

Posted on October 8, 2014 by idz

I try to make sure that all my Open Source repositories on GitHub compile and run correctly, but it is easy to miss some dependency on my system or some other bug. So it’s nice to have the ability to build on a fresh virtual machine, automatically, each time I push. This is exactly what Travis Continuous Integration (CI) offers and it’s free for Open Source projects! I had dragged my heels about figuring out his to use Travis. I envisaged torturous configuration files and long hours of frustration. I was wrong. In this post I will explain how you can get a basic Travis build working for an iOS project hosted on GitHub. It should take you less that 10 minutes.

Ensure Your Code Builds Locally

The first step is to ensure that you can successfully build from the command line on your local machine. Check out a fresh copy of your repository, change directory to where your project file is and issue the following command (substituting your build scheme name for `ADZAQAudioPlayer` of course).

xcodebuild clean build -scheme IDZAQAudioPlayer -destination 'platform=iOS Simulator,name=iPhone 6,OS=8.0'

If this goes well you are ready to proceed, otherwise fix any problems.

Make Your Build Scheme Shared

By default, your build schemes are not checked into source code control, so they are not available to Travis via GitHub. To change this go to Product > Scheme > Manage Schemes… and check the Shared check box for any schemes you want to include in your build.

Check the Shared box to share you build scheme.

Check the Shared box to share you build scheme.

Write Your .travis.yml File

The Travis build file, `.travis.yml`, is very straightforward. You need to specify `language: objective-c` to ensure your build is run on a Mac; if your forget this it will be scheduled on a Linux VM. You can optionally have an `install` section where you can install any dependencies needed for you build. The most important part of the build file is the `script` section which tells Travis which commands to run to execute your build. Each command is prefaced with a `-` (this is part of the YAML format).

The most basic Xcode build file will look like this:

language: objective-c

script:
- xcodebuild build -scheme IDZAQAudioPlayer -destination 'platform=iOS Simulator,name=iPhone 6,OS=8.0'

If `IDZAQAudioPlayer` had tests, these could also be run by appending the following to the file.

- xcodebuild build -scheme IDZAQAudioPlayer -destination 'platform=iOS Simulator,name=iPhone 6,OS=8.0'

Sign On to the Travis Website and Enable Integration

To sign in to Travis go to https://travis-ci.org and click the Sign in with GitHub item in the top right corner. The first time you do this it will ask you to confirm access to GitHub and perhaps a few other questions. Once this is complete, go to the Accounts section. You can get there by choosing Accounts from the drop down menu that appears when you hover on your avatar in the top left corner of the screen.

Click the Sign in with GitHub item.

Click the Sign in with GitHub item.

The accounts section should list all your repositories at GitHub; if it does not you may need to press the Sync Now button. Then flip the switch beside the project you want Travis to monitor.

Flip the switch to turn on Travis integration.

Flip the switch to turn on Travis integration.

Push to GitHub

To test your build, commit the `.travis.yml` file you created earlier and push to GitHub. You build should appear on the Travis site momentarily and begin executing. You can monitor the build’s progress on the Travis site by clicking the spanner/wrench icon beside the switch for the project and choosing the tab.

Monitoring a Travis Build

Monitoring a Travis Build

Adding Build Status Icon to README.md

Clicking on the build status indicator (it looks something like this Travis build status indicator) brings up a dialog that allows to copy code to paste into web sites, mark down documents or blogs. Choose the Markdown option and paste it close to the top of your repository `README.md`. You can also use it to create a page displaying the status of all your builds. I do this for my repositories on the Open Source page.

Obviously this post only scratches the surface of what you can do with Travis, be sure to explore the documentation on their site. I hope I saved you some time with this quick introduction. If I did please consider visiting one of our sponsors’ sites or contributing directly to this site on Gratipay .


Posted in Tutorial | Leave a comment

Swift Standard Library: transcode

Posted on October 7, 2014 by idz

Swift Standard Library: transcode

The {swift}transcode{/swift} function lets to convert strings from one Unicode encoding to another, for example {swift}UTF16{/swift} to {swift}UTF8{/swift}.

The definition you get when you command-click on the function is quite intimidating:

/*
func transcode<         Input : GeneratorType,
                       Output : SinkType,
                InputEncoding : UnicodeCodecType,
               OutputEncoding : UnicodeCodecType
    where 

       InputEncoding.CodeUnit == InputEncoding.CodeUnit,
      OutputEncoding.CodeUnit == OutputEncoding.CodeUnit>

                (inputEncoding: InputEncoding.Type,
                outputEncoding: OutputEncoding.Type, 
                         input: Input, 
                        output: Output, 
                  #stopOnError: Bool) -> (Bool)
*/

It is also incorrect; a type constraint with the same type expression on both sides of the {swift}=={/swift} sign is not much of a constraint.

/*
func transcode<         Input : GeneratorType,
                       Output : SinkType,
                InputEncoding : UnicodeCodecType,
               OutputEncoding : UnicodeCodecType
    where

       InputEncoding.CodeUnit == GeneratorType.Element
      OutputEncoding.CodeUnit == SinkType.Element>

                (inputEncoding: InputEncoding.Type,
                outputEncoding: OutputEncoding.Type,
                         input: Input,
                        output: Output,
                  #stopOnError: Bool) -> (Bool)
*/

In plain English, what these constraints are saying is that we need an input
source (a {swift}GeneratorType{/swift}) that generates elements that are compatible with
our input {swift}UnicodeCodecType{/swift} and an output {swift}SinkType{/swift} that can consume the output of our output encoder.

The following code takes the UTF32 codepoint for the “Grinning Face with Smiling Eyes”
emoji (I’m not kidding that is its official name!) and converts it to UTF8.

import UIKit
/*
GRINNING FACE WITH SMILING EYES
U+1f601
UTF8: 0xF0 0x9F 0x98 0x81
*/
let grin = UnicodeScalar(0x1f601)
String(Character(grin))

let inputArray : [UInt32] = [ grin.value ]
let input = inputArray.generate()
var outputArray : [UInt8] = []
var output = SinkOf<UInt8>({ outputArray.append($0) })

let error = transcode(UTF32.self, UTF8.self,
inputArray.generate(), output, stopOnError: true)

let utf8HexArray = outputArray.map { String(format: "%02x", $0) }
utf8HexArray

The values obtained seem to agree with the values I found on the ‘net, but we can verify using Cocoa to construct a string from the UTF8 values

let utf8String = NSString(bytes: outputArray, length: countElements(outputArray), encoding: NSUTF8StringEncoding)
utf8String

In the playground for this tutorial the above code will print the emoji.

Download the Playground

The source for this and all other playgrounds in this series can be found on Github in the SwiftStandardLibraryPlaygrounds repository.


Posted in Swift, Swift Standard Library | Tagged , , , , , , | 1 Comment