Now that the Jenkins server is running as a Launch Agent, it’s time to create a build job for building and testing an app.

1. The first step is to provide Jenkins the necessary certificates and provisioning profiles. Add them as always to the keychain of the current user.
   Attention! If the Jenkins asks for access to the Keychain, press Always allow in the appearing popup. Otherwise the build process will stop. Alternatively you can unlock the keychain via script (this exposes your password – not recommended!)Additionally I had to login to the Apple developer account in Xcode, otherwise the provisioning profiles won’t be recognised.

    $ security unlock-keychain -p <MAC_USER_PASSWORD> (<KEY_CHAIN_PATH>)

2. Choose New Item from the left side of the Jenkins dashboard.
3. Choose Build a free-style software project, give it a speakable name and click OK.
4. Add a description (html is supported) that explains what the job is doing, when it is triggered and which steps are executed.
5. Select Discard Old Builds and set Max # of builds to keep to 10.
6. Configure Source Code Management (the repository url, credentials and the branch to build).
7. Configure Build-Trigger (e.g. poll SCM every 2 minutes: ‘H/2 * * * *’)
8. Choose Add build step. If you want to use the Xcode plugin, choose Xcode and fill out the parameter inputs. Or choose Execute shell if you want to follow along and use the script approach.
   If you want to leverage the full power of the script approach, have a look at this build system.

Script code for building the app

• Organise Output

  BUILD_DIRECTORY=~/Desktop/Jenkins_Build

  ARTEFACTS_DIRECTORY=~/Desktop/Jenkins_Artefacts/${BUILD_TAG}

• Clean build directory before building

  rm -rv $BUILD_DIRECTORY

  mkdir -p $BUILD_DIRECTORY

• Set Xcode version (if a different version is required)

  export DEVELOPER_DIR=/Applications/$XCODE_APP_NAME.app/Contents/Developer

• Print current Xcode version

  echo “Xcode version: “ `xcodebuild -version`

  echo “Xcode path: “ `xcode-select -print-path`

• Build the app

  xctool 	-project ${ProjectName} \
  	-scheme JenkinsTest \
          -sdk iphoneos \
         	-configuration Release \
          CONFIGURATION_BUILD_DIR=$BUILD_DIRECTORY \
          clean \
          build
  

• Create IPA / Signing the app (Specify a special certificate and provisioning profile if you want to create ipa files for different use cases)

  xcrun	-sdk iphoneos \
  	PackageApplication \
          -v $BUILD_DIRECTORY/JenkinsTest.app \
          -o $BUILD_DIRECTORY/JenkinsTest.ipa \
  	#-sign “iPhone Distribution” \
  	#-embed PATH/Example_Ad_Hoc.mobileprovision
  

• Zip dsym for distribution

  zip -r $BUILD_DIRECTORY/$PROJECT_NAME.dSYM.zip BUILD_DIRECTORY/*.app.dSYM

• Save artefacts

  mkdir -p $ARTEFACTS_DIRECTORY
  mv $BUILD_DIRECTORY/$PROJECT_NAME.dSYM.zip $ARTEFACTS_DIRECTORY/
  mv $BUILD_DIRECTORY/JenkinsTest.ipa $ARTEFACTS_DIRECTORY/
  

Script code for testing the app

• Build tests and write test report. (If you want to run tests against multiple SDKs, have a look at the xctool documentation)

  xctool	-workspace SampleProject.xcworkspace \
         	-scheme ExampleApp \
         	-reporter plain \
         	-reporter junit:test-reports/report.xml \
         	test \
         	-freshSimulator \
         	-freshInstall
  

Publish test results (JUnit-compatible output)

1. Choose Add post-build action and then choose Publish JUnit test result report.
2. Add test-report/*.xml into the field Test report XMLs.
3. After some builds, when enough data was collected, a graph will be shown in the status view of the build job.

Test results

?  The last post in this series shows how to get insights in code quality with code metrics…

Now that the user account is ready for use, the next step is to install and configure Jenkins server itself. Let’s start right away…

Install Jenkins server

1. The best way to install Jenkins is via Homebrew. It is less problematic compared to the installation with the installer or the war-file. If you’re still interested in these ways of installing Jenkins, please see this nice blog post.

   $ brew install jenkins

2. Install and set Java (at least version 1.7). Please follow these instructions. If this does not work, try these steps:
   • Check the current java version

     $ java -version

   • Check current Java version link (typically this returns ‘java -> /System/Library/Frameworks/JavaVM.framework/Versions/Current/Commands/java’)

     $ ls -la /usr/bin | grep java

   • Remove current Java version link

     $ sudo rm /usr/bin/java

   • Create new Java version link

     $ sudo ln -s /Library/Internet\ Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java /usr/bin

3. Configure Jenkins as Launch Agent not as Launch Daemon. A few words about this, because it is important. There are some differences. Most important, Jenkins needs to be run as a Launch Agent to execute tests. Otherwise it has no access to the window manager and therefore can not launch and interact with the iOS Simulator. The other major difference is, that a Launch Agent is started after the user has logged in (because it runs on behalf of the user), while the Launch Daemon is started at system start.
   For more information about the differences between Launch Agent and Launch Daemon see these blog posts [1][2].
   If you see the following error, then Jenkins is configured as a Launch Daemon (described here and there):

   [DEBUG] Session could not be started: Error 
   Domain=DTiPhoneSimulatorErrorDomain Code=2 
   UserInfo=0x100270b90 “Simulator session timed out.”

   To configure Jenkins as a Launch Agent, do the following:

   • Create the directory for Launch Agents if it does not exist.

     $ mkdir -p ~/Library/LaunchAgents

   • Copy Jenkins’ plist to the Launch Agents directory.

     $ cp /usr/local/opt/jenkins/*.plist ~/Library/LaunchAgents

   Now Jenkins gets started right after the user has logged into the system. If you want more automation, you can use the automatic login, (‘System Preferences → Users & Groups → Login Options → Automatic login’). But this reduces security because the system is not password protected anymore. I am ok with entering a password if I work directly on the machine once in a while. And usually the Jenkins does not reboot that often.

4. Start and stop the Jenkins manually with these commands:

   Start:
   $ launchctl load ~/Library/LaunchAgents/homebrew.mxcl.jenkins.plist
   

   Stop:
   $ launchctl unload ~/Library/LaunchAgents/homebrew.mxcl.jenkins.plist

5. The web interface/dashboard of the Jenkins server should be reachable at http://localhost:8080.

Configure the Jenkins server

1. Configure the server parameters, mainly to grant more memory to Jenkins. Edit the default plist file at ~/Library/LaunchAgents/homebrew.mxcl.jenkins.plist. My plist looks like this:

   <?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>homebrew.mxcl.jenkins</string>
   				<key>ProgramArguments</key>
   				<array>
   					<string>/usr/bin/java</string>
   					<string>-d64</string>
   					<string>-Xms1024m</string>
   					<string>-Xmx2048m</string>
   					<!-- Use Concurrent GC-->
   					<string>-XX:+UseConcMarkSweepGC</string>
   					<string>-XX:+CMSClassUnloadingEnabled</string>
   					<string>-XX:MaxPermSize=256m</string>
   					<string>-Dmail.smtp.starttls.enable=true</string>
   					<string>-jar</string>
   					<string>/usr/local/opt/jenkins/libexec/jenkins.war</string>
   					<string>--httpListenAddress=127.0.0.1</string>
   					<string>--httpPort=8080</string>
   				</array>
   				<key>RunAtLoad</key>
   				<true/>
   			</dict>
   		</plist>
   

    

   JVM Virtual Memory

   Set the heap size minimum and maximum with -Xms and -Xmx to give Jenkins a bit more memory power and let Jenkins use a 64-bit data model, if available, with -d64.

   <string>-d64</string>
   <string>-Xms1024m</string>
   <string>-Xmx2048m</string>
   

   HTTP address and port

   Usually Jenkins runs on ‘127.0.0.1:8080’. These values have to go to the ‘jenkins.war’ file.
   If you face the problem that the Jenkins dashboard does not open, try to enable access from all IP addresses by setting ‘httpListenAddress=0.0.0.0.’.

   <string>-jar</string>
   <string>/usr/local/opt/jenkins/libexec/jenkins.war</string>
   <string>--httpListenAddress=127.0.0.1</string>
   <string>--httpPort=8080</string>
   

   If you want to know more about the other configurations like HTTP proxy, garbage collection, environment variables, redirect stdout and stderr, etc., read the configuration part in this blog post.

2. Install the Jenkins plugins you need for your workflow. Here are some of my favorites:
   • Git Plugin
   • Timestamper
   • JobConfigHistory Plugin
   • Disk Usage Plugin
   • GitHub Plugin
   • (Xcode Plugin)
3.  The last plugin helps to configure the iOS part of the build process. You make some definitions and the plugin executes the rest of the build process. If you don’t want to have your build configuration stored on Jenkins only and want to build your apps locally on your machine the same way, use build scripts. Commit these scripts to your VCS and you have an executable build system everywhere where the project is checked out.
   

   Xcode plugin settings

   To default build tool is xcodebuild, which is part of the command line tools. But its output and flexibility regarding test execution could be better. And xctool does this job better. The configuration is almost the same.

   $ brew install xctool

4. Manage the Jenkins. From the left side of the dashboard select Manage Jenkins.
   

   Configure System

   • Extend PATH variable, otherwise you have to to specify full qualified paths for commands. Under Global properties select Environment variables and add a variable named “PATH” with the value /usr/local/bin:$PATH.
   • Configure Git
   • Configure Jenkins Location
   • Configure Git plugin
   • Configure Xcode Builder (= Xcode plugin) optionally
   • Configure E-Mail setup (to notify users about a broken build)
   • Configure other appropriate settings according your taste
   

   Configure system

   Configure Global Security

   • Define how users are created and how they authenticate, under Access Control. The easiest way is to let Jenkins manage usernames and passwords by choosing Jenkins’ own user database under Security Realm.
   

   Configure global security

   Manage credentials

   • Set credentials which will be used by build jobs and Jenkins itself (i.e. for access to integrated systems like GitHub or Stash, …).
   • Set a SSH private key and give it a speakable name.
5. Share all schemes that should be used in Jenkins.
   • Open project in Xcode
   • ‘Product ➝ Schemes ➝ Manage Schemes…’
   • Select the Shared checkbox for the required scheme
   

   Share a scheme

?  How to setup a build job that runs on the installed Jenkins server is the topic of the next post…

Continuous integration for iOS is an important part of a professional software development workflow and a helper to automate the build and test process.
Besides automatic builds and tests, Jenkins gives the opportunity to run code metrics, to distribute build artefacts to servers or to run every other task which is required for the job.
Once setup, a developer can focus on writing code and tests. Jenkins does the rest of the job. And this always the same way and while the developer is coding.
At the end you get stable build results and an overview about the quality of your code and where it can be improved.

There are many blog posts out there, some good, some bad and some wrong. This series here is my summary of infos that I found in various blog posts and tried out in many exploration times. The next four posts contain what I have done to setup a Jenkins on OS X Yosemite which is able to build, test and analyse my projects.

The setup process can be clustered in the following parts:

1. Create and/or configure the user account on OS X.
2. Install and configure the Jenkins server.
3. Create and configure one or more build jobs.
4. Configure one or more build jobs to run code metrics.

*Ok, then let’s rock! :)*

1. Create and configure the OS X user account

Some of the following steps belong to my personal preferences and are not necessarily required, however very helpful. They are marked with a little (*).

1. Create a new user account with admin rights for OS X.
2. (*) Basically configure the system (faster mouse and keyboard, always visible scrollbars, nice background) and install the tools that make you faster (i.e. a visual git client).
   
3. (*) Install zsh.

   $ curl -L https://raw.github.com/robbyrussell/oh-my-zsh/master/tools/install.sh | sh

4. (*) Install iTerm2.
5. (*) Configure zsh and iTerm2 to your needs to speed up usage. (the command line will be used very often)
6. Install Homebrew and follow the instructions.

   $ ruby -e “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)”

7. Install wget via Homebrew.

   $ brew install wget

8. (*) Install Ruby via RVM or rbenv to get a controlled Ruby environment. The following example generates a `.ruby-version` file in the project repository (should be committed) which sets the local Ruby version for the project to 1.9.3-p327.:

   $ rbenv local 1.9.3-p327

9. Install Xcode and command line tools. [How to]
10. Grant Jenkins access to the required source code. Typically this means to generate one or more SSH keys and register them at a hosting service (e.g. Github, Bitbucket, …) For how to generate a SSH key see the awesome Github help page.

?  The next post will be about the installation and configuration of the Jenkins server itself…