To solve this challenge I have introduced a Continuous Integration (CI) server to my workflow. My goals were to have unit and application tests automatically executed when an commit is made to a specific branch in a (local) git repository, and if both of these phases are successful, have the application packaged up, ready for distribution. I also wanted this successful build to be deployed on a daily basis to TestFlight so my client (and any other human testers in the future) could pick it up on their devices. I also wanted code coverage reporting, for both the unit and application tests, so I can see what parts of the application logic and screen flows are actually being tested to give me a level of confidence that the right stuff is getting the attention. The application tests also needed to be executed in a headless manner - I don’t have a physically separate machine (or VM) to run the CI server in, so I don’t want the simulator popping up and distracting me.

Warning - this is long and involved. I’ve also written this after the fact. I hope I’ve captured all the steps but if something doesn’t work for you please let me know and I’ll try to help and update this guide.

Toolkit

I used a set of existing tools to help with this

1. CI Server - Jenkins
2. Unit Tests - SenTest/OCUnit - it’s baked right into Xcode and meets my needs. It’s hard for me to justify using something else like GHUnit because of the pre-integration.
3. Application (UI) Tests - Frank - I wanted to use a behaviour driven approach to UI testing, as well as something my client could actually specify tests in. Frank is cucumber based, so uses an english language syntax, making it easy for non-developers to specify and understand tests.
4. Deployment - Curl - low tech, but the TestFlight API is simple to use, so nothing more complex is really required here. It could be wrapped in a Jenkins plugin, but I’m not the guy to create that…

And this is how I did it. I cobbled together all the tools I needed with help from various blogs, stack overflow answers, and vendor documentation. I’ve referenced the sources where I can. Hat tips to all.

Installation of Prerequisites

Install rvm

You’ll need ruby for compiling Frank, and I recommend you use rvm for this. Paste the following into a shell and follow the instructions.

bash -s stable < <(curl -s https://raw.github.com/wayneeseguin/rvm/master/binscripts/rvm-installer)

Extra install instructions (head builds, multi-user etc) are available at http://beginrescueend.com/rvm/install/

You’ll need to close and open shell after following the instructions (including modification of your .bash_profile). You’ll also need to install your favourite ruby. I recommend installing 1.9.2 with rvm install 1.9.2

You’ll also need rake (for managing Frank’s build process), so you can get that with gem install rake

Install homebrew

I used homebrew to install Jenkins. It’s a good package manager for OSX, and well maintained. Instructions are at https://github.com/mxcl/homebrew/wiki/installation but you can just paste the following into a shell and it’ll install.

/usr/bin/ruby -e "$(curl -fsSL https://raw.github.com/gist/323731)"

Install Python and gcovr

gcovr (and python) are needed to generate the coverage files from the unit and application test output. If you already have a modern python installation (2.7) then skip the python installation step and just install gcovr with your own copy of easy_install

You can use homebrew to install python. Do so with:

brew install python

Then you will need easy_install (or the distribute tools)

1
2

curl -O http://peak.telecommunity.com/dist/ez_setup.py
/usr/local/bin/python ez_setup.py

You will then need to get gcovr.

/usr/local/share/python/easy_install gcovr

Install and configure Jenkins

Thanks to homebrew, the installation step is very easy. Just paste the following into the shell and it’ll install.

homebrew install jenkins

There are a couple of configuration steps that are required as well. Thanks to http://mattonrails.wordpress.com/2011/06/08/jenkins-homebrew-mac-daemo/ for the configuration required.

Create a service account

First of all find an ID that is free on your system. dscl . -search /Users uid 600 searches for users with ID 600, and dscl . -search /Groups gid 600 looks for groups with ID 600. Change the number until you find an empty ID. Then (with appropriate ID changes)…

1
2
3
4
5
6
7
8
9
10
11
12
13

sudo mkdir /var/jenkins
sudo /usr/sbin/dseditgroup -o create -r 'Jenkins CI Group' -i 600 _jenkins
sudo dscl . -append /Groups/_jenkins passwd "*"
sudo dscl . -create /Users/_jenkins
sudo dscl . -append /Users/_jenkins RecordName jenkins
sudo dscl . -append /Users/_jenkins RealName "Jenkins CI Server"
sudo dscl . -append /Users/_jenkins uid 600
sudo dscl . -append /Users/_jenkins gid 600
sudo dscl . -append /Users/_jenkins shell /usr/bin/false
sudo dscl . -append /Users/_jenkins home /var/jenkins
sudo dscl . -append /Users/_jenkins passwd "*"
sudo dscl . -append /Groups/_jenkins GroupMembership _jenkins
sudo chown -R jenkins /var/jenkins

Starting up Jenkins

Create a file at /Library/LaunchDaemons/org.jenkins-ci.plist with the following contents (check the version number in directory for Jenkins!). This will ensure Jenkins starts when the system boots.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>Jenkins</string>
    <key>ProgramArguments</key>
    <array>
    <string>/usr/bin/java</string>
    <string>-jar</string>
    <string>/usr/local/Cellar/jenkins/1.428/lib/jenkins.war</string>
    </array>
    <key>OnDemand</key>
    <false/>
    <key>RunAtLoad</key>
    <true/>
    <key>UserName</key>
    <string>jenkins</string>
</dict>
</plist>

and load it with sudo launchctl load /Library/LaunchDaemons/org.jenkins-ci.plist

At this point, Jenkins should be installed and running. Head to http://localhost:8080 and it should be running.

Configuring Jenkins

In the Jenkins menu, click on Manage Jenkins, Manage Plugins, and then Available. Install the following plugins and make sure the “Restart Jenkins when installation is complete and no jobs are running” checkbox (on the screen after the “Install” button) is checked.

• Jenkins Cobertura Plugin - for code coverage report processing
• Jenkins GIT plugin - for integration with git
• Xcode Integration - for execution and understanding of Xcode files

Install the github plugins if your project is on github. I won’t be covering configuration of this here, but it should be relatively simple.

Once these are installed and Jenkins has restarted, you’ll need to configure the plugins. In the Jenkins menu, click on Manage Jenkins, Configure System and fill in the parameters for your git installation(s) and Xcode Builder paths. Click Save and we’re ready to go.

Configure your Xcode project

We’re going to take a little departure from Jenkins for the moment to prep Xcode for integration. We are going to setup our project for unit tests and Frank.

Unit Tests

If you don’t have one already, you’ll need to set up a new target for Unit Tests in your Xcode project. Select your top level project in the in Project Navigator, and then “Add Target”. Under iOS -> Other choose the “Cocoa Touch Unit Testing Bundle”. Give it a name and then write some tests.

The other thing we’ll need to do here is set up Code Coverage. In the Build Phases area of your new Target, under Link Binary With Libraries, hit the + and select Add Other. Then navigate to /Developer/usr/lib and select libprofile_rt.dylib. This is the library that enables the profiling goodness. After this, select the Build Settings area, and set “Generate Test Coverage Files” and “Instrument Program Flow” both to Yes in the column for your Unit Test target. Ensure that “Library Search Paths” includes $(DEVELOPER_DIR)/usr/lib, but this should be there already.

You should be set up for code coverage now. If you want to check this is working, ensure your build target (up the top on the right on the Run & Stop buttons) is set to your Unit Test target and iPhone Simulator, then build and test your unit test target. Then, open Organizer, choose the Projects item from the toolbar, select your project, and then click the little arrow next to the Derived Data directory. This will open the build location in Finder. In here, open the selected directory, then navigate to Build/Intermediates/<Your Project>.build/Debug-iphonesimulator/<Your Unit Test Target>.build/Objects-normal/i386/ and in there there should be a set of .gcno (generated at build) and .gcda (generated when your test target executed and finished) files. These are the code coverage files. If you’d like to have a look at them before we integrate back into Jenkins, get CoverStory and open them up.

Application (UI) Tests with Frank

Now we’ll set up the application test target with Frank. First of all, we need to install Frank and cucumber.

We will need to use a customised version of Frank to enable the iOS Simulator to exit after execution of the tests. The standard build does not include a method to terminate an application so we’ll need to build this in. Thanks to Martin Hauner at http://softnoise.wordpress.com/2010/11/14/ios-running-cucumberfrank-with-code-coverage-in-hudson/ for the tip on this. I’ve forked frank and included this exit method, and you can get it from https://github.com/rickerbh/Frank/tree/exitCommand with the command git clone git@github.com:rickerbh/Frank.git and then switch to the exitCommand branch. You’ll also need to git submodule init and git submodule update, and then check the submodules that are pulled in as I recall the submodules have submodules :-/

Once all that is done, you’ll need to be in the root directory of Frank that you cloned, and compile my branch of Frank with the following command.

rake build_lib

After this is finished, there should be a file at dist/libFrank.a. This is the customised library that we’ll need to use with the exit command built in.

(Full Frank installation instructions available at http://www.testingwithfrank.com/installing.html - I’ll paraphrase here with a couple of sightly different steps for the custom library and code coverage inclusion) For convenience of installation, I actually installed the proper Frank gem rather than my customised build. You can do this with gem install frank-cucumber. Then, cd to your project directory, and run frank-skeleton. This installs Frank in your project directory. It also copies a version of the official libFrank.a file into Frank/. You’ll need to replace that with the version that we built.

To add Frank to your Xcode project, you’ll need a new target (you don’t want the Frank server installed in the Release version of your application). Duplicate your main application target by right clicking on it and selecting Duplicate. Rename the new target “<Your app name> Frankified”. Then, add the Frank directory (that was created when you ran frank-skeleton) to your Xcode project. Ensure that it’s only added to your frankified target, not your main application target. Add CFNetwork.framework to the Frankified “Link Binary With Libraries” section of the Build Phases. Then, add -all_load and -ObjC to the “Other Linker Flags” Build Setting.

To enable code coverage for Frank, add --coverage to the “Other Linker Flags” Build Setting, and set “Generate Test Coverage Files” and “Instrument Program Flow” both to Yes in the column for your Frankified target.

If you build and run the Frankified target for the iPhone simulator of your application, it should build OK and start the simulator. Head to http://localhost:37265 and you should see the Symbiote browser of your iPhone application.

If you want to see if the coverage is working, head to Build/Intermediates/<Your Project>.build/Debug-iphonesimulator/<Your Frankified Target>.build/Objects-normal/i386/ just like with the Unit Tests area above.

You should then write some tests in cucumber and make sure they work.

Troubleshooting Frank and Code Coverage

I had a lot of trial and error (mostly error actually) getting coverage working with Frank. I had to play a bit with the “Library Search Paths” Build Setting so it could find the correct coverage library to include. I have $(Developer)/Platforms/iPhoneOS.platform/Developer/usr/lib added in the setting, but can’t recall if this is required or not - apologies for this.

If you are getting the .gcno created but not the .gcda files, it could be an issue of your application not exiting correctly when the simulator terminates (as the .gcda files are only written when the application terminates). If this is the case, head into the Info area for your Frankified build target. Add/Set the “Application does not run in background” property to the application, and set it to YES. This will ensure the app terminates when the home button is pressed, and the .gcda files are created.

I also had an issue when the application was attempting to write the .gcda files. It was complaining that fopen$UNIX2003 called from function llvm_gcda_start_file. I found this entry in stackoverflow and created the c methods in my main.m file and it enabled the application to write the files correctly.

You may also need to enable the Accessibility inspector in the iPhone Simulators Settings app under General > Accessibility - instructions from Apple.

If you are getting a message that says Couldn't register XXXX with the bootstrap server. Error: unknown error code. This generally means that another instance of this process was already running or is hung in the debugger. this means that either the Simulator is already running (it must be quit for the headless build to run) or that there is a previous version of the headless test exection that has hung. You can find these with ps -ef | grep Fran (Fran for frankified). Kill them with the kill command.

Configuring Frank for Headless Tests under Jenkins

There will be a file in your Xcode project under the Frank directory at support/env.rb - this will contain some environmental settings that are used for executing the cucumber tests. Replace the content with the below with the appropriate text replacements. You will need different settings for manual command line based test execution, and the Jenkins based tests, so there is an environment based conditional in the file. Default is for command line based testing.

For the replacement text for , just type in what you’ll call your Jenkins UI test job, and remember this for later.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

require 'frank-cucumber'

ENV['TESTING_ENV'] ||= 'command_line'
environment = ENV['TESTING_ENV']

if environment == 'command_line'
 BASE_DIR = "<Your home directory>/Library/Developer/Xcode/DerivedData/<Your long and random derived data dir from Xcodes project organizer>/"
 APP_BUNDLE_PATH =  "#{BASE_DIR}Build/Products/Debug-iphonesimulator/<Your frankified target>.app"
 APP_DIR = "#{BASE_DIR}Build/Intermediates/<Your project name>.build/Debug-iphonesimulator/<Your frankified target>.build"
elsif environment == 'jenkins'
 BASE_DIR = "<Your Jenkins install location>/jobs/<Your UI Testing Jenkins Job Name>/workspace/"
 APP_BUNDLE_PATH =  "#{BASE_DIR}build/Debug-iphonesimulator/<Your frankified target>.app"
 APP_DIR = "#{BASE_DIR}build/<Your project name>.build/Debug-iphonesimulator/<Your frankified target>.build"
end

#### Common ####
SDK_DIR = "/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator5.0.sdk"
APP_BINARY = "#{APP_BUNDLE_PATH}/<Your frankified target>"
USER_DIR = "iPhone Simulator/User"
PREF_DIR = "#{USER_DIR}/Library/Preferences"

In your Xcode project under the Frank directory, there will be another directory named step_definitions. This should contain a .rb file that has some ruby and cucumber/frank definitions it it. We need to add a couple of things to that file. Again thanks to Martin Hauner here.

Add the following lines to the top of the ruby file in the step_definitions directory. I’ll explain what these are…

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

require 'fileutils'

ACCESIBILITY_PLIST   = "com.apple.Accessibility.plist"
ACCESIBILITY_CONTENT = <<PLIST
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>ApplicationAccessibilityEnabled</key>
<true/>
</dict>
</plist>
PLIST

Before do
  # check that pwd contains the "build" dir as we are creating
  # items relative to it.
  #Dir["build"].length.should == 1
  
  # make sure we do start with a clean environment
  FileUtils.remove_dir("#{USER_DIR}",true)
  
  pwd     = "#{Dir.pwd}"
  prefdir = "#{PREF_DIR}"
  FileUtils.mkdir_p prefdir
  
  File.open("#{PREF_DIR}/#{ACCESIBILITY_PLIST}", 'w') do |f|
    f <<ACCESIBILITY_CONTENT
  end
  
  ENV['SDKROOT']               = "#{SDK_DIR}"
  ENV['DYLD_ROOT_PATH']        = "#{SDK_DIR}"
  ENV['IPHONE_SIMULATOR_ROOT'] = "#{SDK_DIR}"
  ENV['TEMP_FILES_DIR']        = "#{APP_DIR}"
  ENV['CFFIXED_USER_HOME']     = "#{pwd}/#{USER_DIR}"
end

After do
  frankly_exit
end

def launch_app_headless
  @apppid = fork do
    exec(APP_BINARY, "-RegisterForSystemEvents")
  end
  wait_for_frank_to_come_up
end

def frankly_exit
  get_to_uispec_server('exit')
  # calling exit in the app will not return any response
  # so we simply catch the error caused by exiting.
  rescue EOFError
end

Given /^I launch the headless app$/ do
  launch_app_headless
end

The Before block gets executed before any tests are run. The accessibility plist/content section sets up a file that enables the accessibility settings for the simulator. This is created every time the cucumber tests are run to ensure accessibility is in the correct state. The SDKROOT, DYLD_ROOT_PATH, IPHONE_SIMULATOR_ROOT, TEMP_FILES_DIR, and CFFIXED_USER_HOME are all directories for the simulator to function correctly. Thanks to Matt Gallagher’s blog entry for aiding my understanding of these.

The launch_app_headless method adds a flag when launching the application so it launches headlessly. If you wanted, you could actually add a conditional so that the headless method is only used when launching under jenkins.

The frankly_exit method will call the new exit method that we built into libFrank.a. This is called from the After block, which gets called after the tests are executed.

That should be all the configuration you need. If you alter your frank/cucumber tests to use the “Given I launch the headless app” call to start the application, you should now be able to run it in a headless manner. Execute cucumber in your Frank directory inside your Xcode project dir to test it out.

Setting up the jobs in Jenkins

The way I have structured my tasks in jenkins is that I have 4 different jobs. I have a unit test execution job that triggers off a git push. If this is successful, I have the UI test job that executes. If this is successful, I then package and archive the binary that was generated from that push. The last job that is configured is a daily distribution of the last successfully tested application to a group on TestFlight.

Setting up the unit test job in Jenkins

Navigate to Jenkins and click on “New Job”. Give it a name (I called mine “Project Unit Tests”), and select the “Build a free-style software project” radio button, then click OK.

You should now be in a screen to configure the build settings for your unit test target. In the source code management area, choose git. Enter your repo name (something like git@localhost:my-project.git). If you have a specific branch you want to build from put it in the “Branches to build” box (mine is */develop). In the “Build Triggers” area below, select “Poll SCM”. I’ve set my schedule to * * * * * meaning it’ll look every minute for a new push.

Navigate down the screen until you find the “Add build step” button. Click it and select Xcode. Then, fill in the following boxes.

• Clean before build - check this box. I like clean builds before testing.
• Target - set this to the unit test target name from Xcode (no escaping of spaces required)
• SDK - set this to the SDK you want to build for. Mine is /Developer/Platform/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator5.0.sdk/
• Configuration - set this to DEBUG
• Keychain path - this should already be set to ${HOME}/Library/Keychains/login.keychain

That’s all the Xcode build information set up. Now, to generate the coverage test files. Add an “Execute Shell” build step with the “Add build step” button. In the “Command” box, call gcovr (which gcovr to find your own install location) with /usr/local/share/python/gcovr -r "<Your Jenkins install location>/jobs/Project Unit Tests/workspace" --exclude '.*UnitTests.*' --xml > "<Your Jenkins install location>/jobs/Project Unit Tests/workspace/coverage.xml"

In the Post-build Actions section, check the “Archive the artifacts” box and set the “Files to archive” field to build/Debug-iphoneos/*.ipa

Check the “Publish Cobertura Coverage Report” box and set the “Cobertura xml report pattern” to **/coverage.xml.

Also check the “Publish JUnit test result report” box and set the “Test report XMLs” to test-reports/*.xml.

Click the Save button down the bottom, and then attempt to run your unit tests manually. The code should be checked out from your git repo, build the unit test target, run the tests and produce the unit test reports and coverage results.

Setting up the application test job in Jenkins

Navigate to Jenkins and click on “New Job”. Give it a name (I called mine “Project UI Tests”), and select the radio button to copy the unit test job that was previously set up. In the Configuration screen for the new job, alter the following fields.

• Build Triggers - set this to be “Build after other projects are built” and type in the name of your unit test job.
• Build Triggers - uncheck poll scm
• Target - Set this to your Frankified target name from Xcode

Change the existing “Execute shell” step to use your UI Test build job name rather than the unit test job name. /usr/local/share/python/gcovr -r "<Your Jenkins install location>/jobs/Project UI Tests/workspace" --exclude '.*UnitTests.*' --xml > "<Your Jenkins install location>/jobs/Project UI Tests/workspace/coverage.xml"

Create a new “Execute shell build step”, and click and drag it (with the little 4x4 set of boxes on the right of the “Execute shell” label on screen) to move it inbetween the Xcode step and the gcovr step. Insert the following commands in the shell box.

1
2
3
4

source <Your home dir>/.rvm/environments/<your ruby version>
export TESTING_ENV="jenkins"
cd "<Your Jenkins install location>/jobs/Project UI Tests/workspace/Frank"
cucumber -f junit --out ../test-reports

The source line sets up the environment for rvm so the frank gem is included correctly - set it to the appropriate ruby version in the ~/.rvm/environments directory. Mine is ~/.rvm/environments/ruby-1.9.2-p290

Uncheck the “Archive the artifacts” option, and click save. You can now attempt to run your application tests via Frank. This will check out the code, build the Frankified target, execute the tests and then process the unit test and coverage reports.

FYI - my unit test reports for this step are empty. If someone figures out how to get cucumber to put something useful in them please let me know!

Setting up the archive job

Similar to the application test job, create a new job that copies the Unit Test job. I called mine Project Developer Build. In the Configuration screen for the new job, alter the following fields.

• Build Triggers - set this to be “Build after other projects are built” and type in the name of your application/UI test job.
• Build Triggers - uncheck poll scm
• Target - Set this to your application target name from Xcode (mine is Project TestFlight - I have a specific target that includes the TestFlight SDK)
• Configuration - I have this set to release. Be sure to setup and test the signing identities correctly in Xcode for this. You must use the adhoc profile that should be used in TestFlight.
• Build IPA - check this.

Remove the execute shell build step with the Delete button.

Uncheck the Cobertura and Unit test report generation Post-build actions. Change the Archive files location to build/Release-iphoneos/*.ipa

Click save, and now whenever both your unit and application test steps pass, you’ll have a version of the application built and archived ready to go to TestFlight.

Distributing to TestFlight

Thanks to the Shine Technologies team for their blog entry that helped here.

Create another free-style software project job (last one, I promise!) in Jenkins - I’ve called mine Project TestFlight Deployment. Set the build triggers to “Build periodically” and set the schedule to whatever time you want to upload the application to TestFlight. Mine is set to 10pm (0 22 * * *).

Add an Execute shell build step. This will call curl to upload the application to TestFlight. You will need your API token and Team token from Testflight. Set the Command to the following

1
2

cd ../..
curl http://testflightapp.com/api/builds.json -F file=@Project\ TestFlight/lastSuccessful/archive/build/Release-iphoneos/Project\ TestFlight-Release.ipa -F api_token=’<api token>’ -F team_token=’<team token>’ -F notes=’This is an auto deploy build of the develop branch with Release configuration’ -F notify=True -F distribution_lists=’<name of test distribution list>’

The ipa that’s being uploaded there is the version that was saved in the last build job. For the name, just look inside the Project TestFlight job and it’ll have the name of the “Last Successful Artifact” - this is what you need to upload.

That should be it.

End - finally

If you experience issues with this, have corrections or useful troubleshooting steps then please let me know. This process was a bit of a pain to get working correctly so I hope this guide is useful for someone. You should also follow me on twitter @rickerbh.

So, I accepted. The issue for me is that this puts my other project on hold for a few months. However, income is good, and this will let me work for longer on my project after I’m done, so it’s a positive move.

The users of my new software will be proper “end-users”. People who do not use computers for a job. People who are unsure, or even wary about computers for fear of breaking them. People who do not know commands like kill -9 when something isn’t working, or even how to drive a CLI.

It would be delinquent of me to not take some advice from well respected professionals in this space. So, I read some books. (I will take some advice from actual people later, but as a first step I think education is always a good step.)

Designing Interactions by Bill Moggridge

Amazon UK, Amazon US

I actually got this book expecting it to have practical advice on how to design software products, and was (pleasantly) surprised when it didn’t. It’s a collection of interviews (and then analysis and commentary on the interviews) with a set of influential product designers. There is a strong bias towards IDEO, but I guess that’s to do with the authors familiarity with the organisation. The book gives insight into the interaction design processes used to create some very popular products, as well as covering some things that haven’t worked. It gives you a good idea of how the designers think about problems - which is great to understand as an outsider to this world.

The two parts of this book that stick with me are Terry Winograd’s discussion on Mark Weiser’s ubiquitous computing - the idea that people don’t want to interact with computers - they want to get something done. The computer is an instrument to be used to get something done - the purpose is not to interact with the computer, but to achieve a goal. The other part was John Maeda’s Laws of Simplicity. These eight laws are about making complex systems simpler for users, either by relating functions, using knowledge that users already have, and recognising when materials (technology in my case) is inappropriate for a task, either by it being too hard to use, or breaking “laws”.

TOG on Interface by Bruce “TOG” Tognazzini

Amazon UK, Amazon US

I got this book because of the Apple Macintosh legacy the author has. Bruce Tognazzini developed the first set of Human Interface Guidelines for Apple in the late 70’s, and was involved with the Macintosh UI which still has a significant influence on the modern interface we use on OSX. The book is a collection of his writing for the Apple Direct publication as well as other text gathered or produced for this book. The book was written in 1992 (updated in 1996 - 15 years ago!) but remains relevant. The principles are as relevant today as they were way back in the 90’s.

Three things made this book useful to me. The first are all Bruce’s Principles and Guidelines (which are outstanding) and the collection of them in the appendix. This gives you an overview (and shortcut to relevant places in the book) for each item he discusses in the book. The second is (and this may sound odd given I’ve used a mac now for 5 years) he describes what the ellipsis means in a Mac menu or on some buttons. I remember seeing it, but I never thought about why it is there. It means that a window or pane will pop up asking for more information before the action you have requested will be executed. This is all about letting users know they can experiment with the system and be assured they can get out again without making any changes. This was a little UI thing I just hadn’t consciously grasped the meaning of, and it’s just nice to understand why it’s there and what it means. The third thing was the in-depth discussion about the Conceptual Model a user generates when they interact with a system. This was like a lightbulb going off for me. This is such a fundamental part of any system and user interface design. It’s obvious it happens (users have a view of what systems do, which may or may not be correct), and designers need to cater for this - exposing elements to users that influence that conceptual model, to make it easier for users to understand and interact with the system. I’ve got a lot of thoughts on this so may write another entry on it.

Anyway, I would definitely recommend both books to anyone involved with software product design - I’m not sure how much new information there will be for experienced UE practitioners, but I’m sure there are some useful nuggets in both for all.

Anyway, I’ve been doing a little bit of work on my application, mostly completion of the requirements, data model, and competitor analysis, as well as reading up a bit on UX and Mac way of doing things (I’ll probably cover this in another entry), and most recently have been prototyping some code that I thought would be particularly tricky.

What this code does is synchronise data across other applications on your mac, with my (intended) application. The reason behind this was to make the act of populating my application with data, and keeping the data fresh over time, simpler for users - or as John Maeda states in his Second Law of Simplicity:

The positive emotional response derived from a simplicity experience has less to do with utility, and more to do with saving time.

I’m into saving time for my (future) happy users, and reusing data that is already on their Mac helps with this - they don’t need to double key or manually join-the-dots between the applications.

The prototyping I was creating was using ScriptingBridge to access data that’s available in other applications that a user may use. The prototype was going well - I had managed to get some queries and filtering down from 5 minutes to 90 seconds to 6 seconds which was a nice level optimisation, and although there are some issues with ScriptingBridge, it was going to let me do what I wanted to do.

One of the key things with the distribution of this application for me is to have it in the Mac App Store. New mac users are a growth market (look at the stats), and Apple is pushing them down the Mac App Store route to discover and purchase applications. Not having the app in the Mac App Store would be foolish from my perspective.

Today, I was seeing how I could get the application working under sandboxing - as this is now a requirement for new Mac Apps. It’s all about making applications safer for users in terms of the resources they can use in terms of network, disk access etc (although some prominent developers aren’t convinced).

I was sad to discover that ScriptingBridge is precisely one of the technologies that is hit hard by the sandboxing. Basically, applications can receive AppleEvents, send AppleEvents to themselves, and respond to AppleEvents they receive (source). The upshot of this is that AppleEvents are pretty useless in a environment of sandboxed applications, as you can only send them to yourself (and no-one else can send them to you).

There may be a way around this - Temporary Exceptions to the AppleEvent sending issue. You can obtain a temporary exception to send AppleEvents to other applications through the com.apple.security.temporary-exception.apple-events key-value pair in your Entitlements file. The main issues I see with this are:

1. They are likely to attract more attention in the review cycle - this in general is a good thing as it’s important that Apple check what your application is doing to ensure that it’s being a good citizen. However, this is likely to slow down the review process and I suspect guidance on what’s acceptable is not consistently applied.
2. They are temporary - Apple could disallow/reject them in the app updates, or just remove the function. The clue is in the name, people.
3. The intent behind the exception - I suspect that the intention behind the temporary exception is to allow pre-existing applications to migrate to a 100% compliant sandboxing world over time, not for new applications. Approval is at risk here, and I don’t want to sink significant effort into getting rock solid sync only to be told it’s not allowed.
4. The overall future of AppleEvents - this (in my mind) is a clear intention that AppleEvents will not have a strategic future at Apple, and that existing applications may drop support for them as no sandboxing compliant applications can actually use the functions. It seems to me risky to use a technology that seems to have a limited future.

This leaves me with two options. I can either remove the synchronisation functionality from the application, or I can distribute it outside the Mac App Store. My wife actually suggested a third - do both. I think that’s what I’ll do. Mac App Store is first priority, and depending on the markets response, I’ll look at options for data synchronisation.

Still, it’s a massive PITA.

It was pitched as “an experiment that merges technology and the arts” - and this blend (to me at least) is intriguing. Since I discovered “creative coding” I have been fascinated by the experimental applications that fit in this space, so didn’t want to miss out on this event. I have no idea how I got an invite… I wonder if it was because I’m a Nokia dev member, or because I have previously been active on the oF forums, or maybe I was just very lucky.

Some marketing and community/dev evangelist type people talked for a bit, and they weren’t over the top with pushing WP7.5 - which was good. There was a lot of talk about the lineage of the Metro design (that I found very interesting) - Metro is a relatively unique looking interface, and has some new ideas and interactions in it - so it was nice to hear how it was conceived.

Then, they pulled up 3 teams of developers and designers to talk about the applications they had made over the last two weeks - essentially showcasing the WP7.5 development environment (ease of use, speed, different technologies etc). This was the most interesting part for me. The applications were

1. a music app that collaboratively generated music across 4 synchronised phones - Vequencer
2. a music video/game in which you take the form of a 3D shape and can shift gravity and change shapes to navigate through the levels - Redshift
3. a kaleidoscope app merging video and generative art that changes based on environmental factors such as motion and sound - Kaleidobooth

The applications themselves were quite impressive, but what impressed me more is that the team that did the second app (Field, Treehouse, and Ed from the XNA Users Group) had no experience with the WP7 or XNA development environments previously, and managed to create a 3D game in 2 weeks, with excellent graphics and sound. Very impressed.

And to top it all off, I got a free phone :-) Nokia Lumia 800 - it’s actually really nice. Screen is brilliant.

AND alphalabs are running a little competition too - app development - cash prizes. Doesn’t appear to be on their website yet, but I recall it closes in early Jan-2012.

(Update 20111128 - Ed from XNA User Group was also part of team two - thanks for the update Tristan!)

1. Brick red - bad UI
2. Blue - data to collect
3. Green - good UI
4. Pink - application function, feature, or derived data

The functions are further classified into “things that should be there for a first release” and “things that can wait until later”.

What I’m looking for now is a sensible way to capture and manage all this information. Carrying around 300 pages of screenshots is just silly. I could have electronically marked up the Keynote presentation rather than do this on paper, but I don’t see myself reusing the information if it’s stored in that format.

As part of a contract my company has right now, I’m using a CASE tool for a project with a client. The business analysts on this project are tracking all requirements, use cases and UI modules within a tool called Enterprise Architect by Sparx Systems. I’m currently leading the technical workstream and we are also using it to produce our technical application design. It seems like a very comprehensive tool, but it’s Windows only. I’d love for a tool like that to be native on the Mac.

Other CASE and UML tools I’ve used in the past are:

• Popkin System Architect (became Telelogic, then IBM and consumed into the Rational suite)
• Rational Rose
• ArgoUML
• Troux Architect
• Various Eclipse plugins

The issue I have with all of these is that it seems they will be disconnected from the development workflow if you use a mac, or are working on a non-Java project. These tools are supposed to help with the development process, but I can’t see how that will work if they aren’t connected to it. Yes, I understand the value in the whole planning and design side, but the disconnect to development seems large. If I didn’t care about having the process connected, I’d just use OmniOutliner as I have in the past for other personal projects - it can track requirements, feature/release planning, data model elements etc. But because of the potential size of this application, I feel I should be using something more structured.

Maybe the project should change to creating a decent CASE tool for the Mac :-)

At the moment the plan is to use Enterprise Architect, and we’ll see how that goes. One good thing is that I can export data out of it if the process doesn’t work out, so there will be little wasted effort.

If anyone has used CASE tools on the mac for Objective-C based projects, I’d love to hear what was used, and how the experience was - good or bad.

I guess the key difference here is that I’m not planning on having any employees at 6 months. I don’t plan on being able to replace the lucrative contracting I’ve been doing either. In fact, I don’t really expect any sales at 6 months.

What I am aiming for is to have a software product that I believe has a future. If, 6 months in, I have something that I can start to sell and get feedback on, I’ll be a very happy man.

One thing that is common in pharmaceuticals (@mrsrickerby works in that industry, so I have a little understanding of how things work there) is that a “Core Data Sheet” - aka a core product specification - is written before and during development and testing of the product . This document specifies needs and wants which at the end of each phase of development are used as the yardstick to make go/no-go decisions. For example, if you want to show a 5% improvement in some disease state but your phase 2 study doesn’t achieve this, you stop development. It is a living document which, as data is collected, the actual product profile is documented which ultimately becomes the package insert (the bit of paper in the box).

This made me think about how I can manage my scope. The main marketing materials for me will be (1) a web site and (2) the Mac App Store description. I figure that writing the app store description will be the most effortless way to describe the product, the problem it solves, and how it solves that problem for the customers. If I can’t write down the very simple things like what problem this solves, and how it does it, then I should stop right now.

I think this also aligns with something I read recently (although I swear I’ve read this before months and months ago…) from the world’s toughest programmer, Mike Lee. App Genius Mike Lee Talks Product Engineering mentions that you should produce some marketing materials (he suggests a video) to explain why people should buy your product. I don’t plan on making a video, but the app store description fulfils the same purpose, and I’d argue that it’s more valuable, as it saves on a job later as it will be refined over time.

This is the approach I’ll be taking to my scoping.

1. Define the problem my customers are experiencing
2. Describe how my software solves those problems for them
3. Scope the software to solve those problems, and eliminate unnecessary features (and keep them out!)

After talking to @mrsrickerby at the pub about this (all our big decisions are made at the pub), we collectively decided that I am going to continue to work for myself. Not as a contractor though, but trying to create a sustainable software company, that is more than a 1 man band.

Ever since I attended university, I have wanted to make software products for small businesses. I really believe the small business segment is underserved by existing products in the marketplace, and given the size of these organisations (1-10 people is the company/customer size I’d want to target), software and computers need to get out of the way and let the people run their businesses, rather than manage and maintain software. This is also probably the last opportunity I’ll ever have to give a project of this magnitude a go. I expect we’ll be looking to settle down soon, get a family home, big mortgage etc and I can’t take risks like this when I’d have all that to lose. It’d be unfair on everyone involved.

So, I’ll be working for 6 months when we arrive in Australia, at home, by myself, trying to create a product to help small business people run their businesses, as unobtrusively as possible.

I’ll also be enlisting the help of some friends. I can design software and systems very well, but user experience, graphic design, copywriting and the like are not my forte. Luckily I know some people in these areas, and I’ll be drawing on their knowledge and skills too.

So, the 6 months starts in the New Year (2012) and if by June 2012 and it looks like I could have something to replace the contracting work I’d alternatively be doing, I’ll be continuing on with the product. The alternative isn’t bad - it’s just not my dream.

Luckily I’ve managed to save up a runway of cash from working in the UK, and my wife is getting a good salary too, so we won’t be eating pot noodles to make the $$$’s stretch. My wife is very supportive.

The rationale behind the move is that we would both like to be closer to our families. We’re both from New Zealand, and the UK for us was only ever temporary. We’ve been here 5 years, and it’s time to move on. We’ve had a good time here. Reading is the place I’ve spent the 3rd most time in, only being beaten by Auckland (if you count living in a hotel in Sydney for 9 months as living in Auckland), and Christchurch where I spent just over 21 years.

My wife has a job organised there, but I don’t. I’m a telco consultant, and have worked for myself for the past 18 months or so doing this, as well as developing iOS applications for myself and the occasional client. I really like software product development, and would like to do more of this. Melbourne isn’t the best city in Australia for what I do (Sydney would be a more sensible choice for my work), but it’s probably time for a change, or at least, a commitment to try something I’ve wanted to do for a long time.

More soon.

In the Apple Developer Library, it explicitly states that for MacOS applications take both the Language and Regional preferences of the user into account, but only look at the preferred language on iOS - Support for Internationalization. This means that a single variant per language is supported.

However, these is a way around this. I’m not sure if this is a good thing to do, but it works for me and I haven’t noticed any ill side effects yet.

To support both US English and British English in your iOS application, create 2x Localization.strings files just as you would for multiple language. Put the US English translation file Localization.strings in a directory in your iPhone app called English.lproj (Apple defaults) and the British English translation in a directory named en_GB.lproj (just in case they decide to support regions in the future).

Then, you’ll need to create some code to manually set the preferred localization. In your main.m file (yup, main.m is being edited) alter it so it performs some logic similar to below.

1
2
3
4
5
6
7
8
9
10
11

int main(int argc, char *argv[]) {
  NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
  NSString *language = [[NSLocale preferredLanguages] objectAtIndex:0];
  NSString *locale = [[NSLocale currentLocale] objectForKey: NSLocaleCountryCode];
  if ([language isEqualToString:@"en"] && [locale isEqualToString:@"GB"]) {
      [[NSUserDefaults standardUserDefaults] setObject:[NSArray arrayWithObjects:@"en_GB", @"en", nil] forKey:@"AppleLanguages"];
  }
  int retVal = UIApplicationMain(argc, argv, nil, nil);
  [pool release];
  return retVal;
}

When the line

1

int retVal = UIApplicationMain(argc, argv, nil, nil);

gets executed, it seems to set up all the Localization bundles before calling the application:didFinishLaunchingWithOptions method on your app delegate, so putting Localization code in the app delegate is too late. So, what the code above does is retrieve the users current language and region, and compares those against pre-determined values - en for the language and gb for the region. If these match, then I force a new setting in the NSUserDefaults to overwrite the users preferred language. Then, when the UIApplicationManager function gets called, it appears to retrieve the users preferred language setting, and look up the Localization for that - which in my case I’ve forced to be en_GB.

One thing you need to be careful about is persistence of this NSUserDefault setting. It is saved once it’s set, and persists through multiple application executions. To get around this (lets say the user changes their region back to US), you need to remove the setting after the bundle initialization has taken place. In you app delegates application:didFinishLaunchingWithOptions method, just execute the following code.

1

[[NSUserDefaults standardUserDefaults] removeObjectForKey:@"AppleLanguages"];

This wipes out the NSUserDefault setting that the app made in the main.m file.

If anyone knows of issues with this approach (apart from being a dirty hack), or faults with my code please let me know in the comments below. I wish Apple supported different regions per language natively in iOS but they don’t. This is the only way I’ve found to do this, and continue to use localization functions such as NSLocalizedString.

How frickin’ exciting!

Seriously, WTF? I assume it’s some sort of movie tie-in…

I want to tidy up some of the code before I check it back into my clone of the source, but this is a really good basis for some smart location and direction aware augmented reality apps on iPhone.  Wonder what the iphonearkit license is - it’s unclear…

— EDIT —

Bugger.  It appears that zac has implemented similar functionality to me already :-(  Bloody github and it’s slow (never!) updates to fork queues and network graphs.  Oh well, maybe I won’t bother tidying my code.

Next up, something more substantial.

My 4th iPhone application was approved yesterday by Apple, and it launches in the iTunes store today. It’s called Kit Quiz: UK and is a UK team based football (soccer) shirt quiz game. It features over 130 shirts from UK football teams, and will have more added shortly.  There are 3 modes of gameplay, from the practise model “Friendly” to a time challenge “Blitz”.

It’s integrated with Twitter and Facebook so you can check out your friends scores and find out once and for all who can recognise the most football shirts.

Couple of screenshots below for anyone interested.  Download it now!

</shameless self promotion>

The situation I was finding was that PHP apps would run, but only if you explicitly call the script (ie index.php) rather than just the directory. If you called the directory, passenger would take over and give me a rails routing error.

The issue was to do with the passenger vhosts configuration. On my machine I have an number of ruby on rails apps configured with the passenger preferences pane (creating vhost entries within /private/etc/apache2/passenger_pane_vhosts/. I have enabled user_dirs, so that the users of my machine’s pages (and other apps) are served from their ~username/Sites directory.

My users configuration info for apache is installed in /private/etc/apache2/users/, and the instructions to load the configuration from that directory is stored within /private/etc/apache2/extra/httpd-userdir.conf (content below).

1
2
3
4
5
6
7
8
9
10
11
12
13

# Settings for user home directories
#
# Required module: mod_userdir
#
# UserDir: The name of the directory that is appended onto a user's home
# directory if a ~user request is received.  Note that you must also set
# the default access control for these directories, as in the example below.
#
UserDir Sites
#
# Users might not be in /Users/*/Sites, so use user-specific config files.
#
Include /private/etc/apache2/users/*.conf

To get everything working together nicely, I merely wrapped this inside a vhosts configuration directive, and gave it a ServerName of localhost - so that this vhost would be the one that responds to requests for localhost, rather than some random passenger vhost assuming it was the boss of everything. New /private/etc/apache2/extra/httpd-userdir.conf below.

1
2
3
4
5

<VirtualHost *:80>
  ServerName localhost
  UserDir Sites
  Include /private/etc/apache2/users/*.conf
</VirtualHost>

Thanks to this, all of my rails apps are served under passenger, and I can have static HTML, PHP and camping apps (previously configured - nothing to do with the above) all served from within my ~username/Sites directory.

Hope this helps someone.