Madefire Press

build system

Keeping sane with a build system

Posted by Dan ,
general | Permalink | 7 Comments »

Any software developer can tell you what a nightmare it can be to make sure two consecutive builds are the same. A lot of pulled hair and late nights have gone before us as a testament to having a sane and uniform build system that is responsible for churning out builds the same way each time. As a small team we have been slowly improving on this aspect of things. Here’s how we’ve added a bit of sanity to the process of developing our iOS app at Madefire.

Jenkins

There are a lot of continuous integration and build systems out there. We’ve decided to go with Jenkins as our system. While we have the iOS app we also have other facets of our technology stack that need testing, including server side and web tools. Jenkins helps us make sure we’re not locked in to just a single platform for everything, since it will run on OS X, Linux, and Windows if needed. The ability for Jenkins to have a master and many slaves that we can add as needed is also a big help. If we ever find ourselves in a place where our current builds are backed up we will just need to add another machine to the pool.

One of the absolute greatest strengths of Jenkins is the plugin system. Many people have published their hard work in extending Jenkins as plugins. The plugins we use all the time are:

Without these we’d have to write our own scripts to handle quite a lot of functionality.

What We Build

We have a slew of build jobs on Jenkins, one for the web services, one for authoring scripts, and four for our iOS builds. For the rest of this post we’re going to focus on the iOS builds we have:

  • • Dev — every time we push to master on Github this starts a build, mostly as a sanity check to make sure nothing breaks long term.
  • • AppStore — when we’re ready for the App Store submission process we build here and then use the result to test and submit.
  • • Testflight — when we need an AdHoc build to share with our registered test devices we start this build and it pushes the final product to Testflight on success.
  • • Enterprise — we also have an Enterprise iOS account for all of our test devices so that we don’t take too many device slots on our regular portal. Like the Testflight build, this pushes the product to Testflight on success.

The Build Machine

For iOS development we’re limited to a Mac as our build machine. For our purposes we put a headless Mac mini (don’t forget to turn on screen sharing so you can get back to it) in the office and let it do its thing. We got the base model with 2GB of RAM. If we need more we can expand later, but for now this is more than enough machine for this use. As usual, we installed Xcode on it and made sure git was usable. We created a builder user whose only job is to run Jenkins as a client and build things.

The world of iOS development requires code signing in order to get an app onto a device. In order to make this work, we exported our certificates and profiles, including the distribution certificates, and installed them for the builder user. We haven’t yet got a system to keep the build machine up to date with provisioning profiles, but on the list to look at is cupertino from @mattt.

Configuring Xcode Projects

We want to build repeatably without worrying about the configuration of our local machines every time. We did this via a combination of Xcode Build Configurations and Schemes. Providing a Scheme per build type allows you to have pre- and post-build commands that are tailored to each type of build (e.g., changing push configurations based on the build type). We also use build configurations to tailor the build settings to each build type. For example, for each build configuration we can have a specific code signing parameter setup so that we don’t have to worry about which profile and certificate will get used. Other things that can be changed per Build Configuration (and with preprocessing the Info.plist file) are the display name of the app and bundle identifier.

Xcode Build Configurations
Xcode Build Configs for the Project

Xcode Code Signing Parameters
Xcode Code Signing Parameters for the Target

Once we had the Build Configs defined we created a Scheme for each one. This step may be overkill for your project. You may be able to get away with a Dev, AdHoc, and AppStore Scheme trio and then just flip Build Configurations to get what you need. Once everything is setup in Xcode and you can build it and get the results you expect, it’s time to make some Jenkins jobs.

This is Xcode. Jenkins Knows Xcode.

As mentioned above, we have a Dev build that builds every time we push to the master branch on Github. We don’t need nearly as much churn as that for our AppStore, Testflight, and Enterprise builds. In fact, since two-thirds of those builds are uploading to Testflight, for these we want to only start builds manually to avoid too many versions being too confusing on Testflight. For the App Store we only want that when we’re ready to submit, never any other time. In the Xcode plugin for Jenkins there are many fields to consider. From our Xcode configuration work above we have the needed values for Target, Xcode Schema File, and Configuration. The next step is that we want to change the Marketing version, or in Info.plist parlance the CFShortBundleVersionString. Originally, we were going to change the Technical Version or CFBundleVersion but Apple requires that to be a number and we use it for content version compatibility checks. In our Info.plist we will leave the value for CFBundleVersion alone at whatever our latest release to the App Store version is. All builds that are for non-engineer use should come from Jenkins.

For the Marketing version field we put a prefix like "TF-" for Testflight and "E-" for Enterprise and the Jenkins variable for the build number. When we look at a build we’ll be able to know which build Scheme and Configuration was used and when it was built via Jenkins. This is set at build time and doesn’t need to be commited to our repo every time we want to build. For our App Store version we have a small script that runs before the build to increment the CFBundleVersion/Technical version, commit that back to the repository, and push it to the origin. This allows us to only have the build number increment when Jenkins builds an App Store build, which is manually triggered.

Further down in the Xcode plugin options is Build IPA?. We do indeed want an IPA generated for us so we can upload it to Testflight or store it on S3 for later retrieval. In addition the plugin will zip up the dSYM and upload it so your crashes can be symbolicated. The Embedded Profile setting will need to point to a copy of the provisioning profile. You’ll have to have your profiles available to Xcode to code sign. In addition we keep a copy in the builder users home directory (or at least a symlink to the Xcode location) for easy access.

A word of warning on the Xcode Plugin distributed by default for Jenkins: there is a known bug that only surfaces if you don’t set the Technical version manually. It is noted in the Github pull request #9 for the Xcode plugin. Once we’re done with our release cycle we’ll be looking into contributing effort to help get a new release of the plugin out, but until then we’ve built a version of the Xcode plugin that contains the patch from the pull request. It is available in the downloads of the Madefire fork of the Xcode plugin.

Previously, we had installed the needed code signing certificates in our Keychain. Thankfully, the Xcode plugin can unlock your keychain for you. We tick the Unlock Keychain? option and then fill in Keychain path and Keychain password. The default login keychain location is ${HOME}/Library/Keychains/login.keychain. The password is the same as the builder user’s login password. Now Xcode can code sign your builds until heat death of the universe (extra-ordinary conditions excepted).

Artifacts For Digital Archeology

At the bottom of the Jenkins job configuration page there is a button that says Add post-build action. We have three post-build actions:Upload artifacts to S3, Upload to Testflight, and Git Publisher.

S3

The S3 Plugin is a little different for most Jenkins plugins in that it actually has a global configuration in the main Jenkens management screen. We configured one S3 profile to upload to and then returned to the jobs. For each one, we selected the configured profile and told it what files to upload with the Source entry. This field must be an Ant style glob, so we put something like **build/Product NameConfiguration-*.*. That will grab both the IPA and dSYM zip file. The Destination bucket we grabbed from the S3 interface. We decided for now to configure only one bucket for all builds to go into. We can change that later if we need to.

Testflight

For Testflight uploads the configuration is fairly straightforward. The API Token is your Testflight user’s personal key (we’ll make a builder user on Testflight so these automated builds don’t all look like they’re coming from one person) and the Team Token is key for the team where builds will be uploaded. For the IPA File path we choose ${WORKSPACE}/build/Product NameConfigurationMarketing version.ipa. This is different from the default output by the Xcode plugin (see the note about the fix above) that would be ${WORKSPACE}/build/Product NameConfigurationTechnical version.ipa. Having the same technical version until we run an AppStore build means we would potentially have a lot of overlapping files named the same thing, but containing different builds. To rectify this, we rename from the Technical version file name to the Marketing version file name in a shell script after the Xcode build has occurred. Please remember that each Xcode project will be different and the values will need to be customized to it, those are not variables in Jenkins.

Our Build output directory is set to ${WORKSPACE}/build so that the build products are local to the Jenkins workspace and easily accessible. The dSYM file is named similarly to the IPA as ${WORKSPACE}/build/Product NameConfigurationMarketing version-dSYM.zip (and we have to rename it the same as the IPA above). For the Build Notes we put a fairly generic string of "Uploaded from Jenkins. (Technical version ${BUILD_ID})". The ${BUILD_ID} variable puts the date and time just in case. That message will help us find uploaded builds and when we’re ready to send that Testflight build out we’ll change the build notes.

Tagging

We decided that we wanted to keep track of where every build for Testflight, Enterprise, and AppStore was in our tree. The Git plugin has a post build step called Git Publisher. With it we can tag the git repo with a tag like "REL_Technical version". That tag is then pushed back to our Github repo and we can step back through the tree if we need to. We worried about too many tags, but since we’re manually building these we shouldn’t have too many of them to worry about. If we were to do this tagging step for builds kicked off when code is pushed, it would likely be just noise, but for just our distributed builds it will be a bigger help down the road when we need to look at the state of the tree for a build.

Final Thoughts

Now we have builds that are generated by a stable non-developers’ machine. They are uploaded to S3 and Testflight automatically for us, removing another manual step from the process (for the AppStore builds we skip the Testflight upload). For all Jenkins jobs we have it email our engineering email list if there is a failure, and again when it returns to healthy. It’s almost so easy that we can forget it’s there and just let it work for us, as computers are supposed to do.

There are a few things that would make Jenkins configuration easier. In order to get all of this working we created a single job and made changes to the configuration until it worked. We then created new jobs that copied the working job and changed the few parameters that needed to be unique. It would be great to have common configuration things like Github and Testflight that could be centrally managed for all the redundant parts. The only per-job configuration would be items like filenames of artifacts that are specific to a job. We’d also like to see more variables from the Token Macro plugin. Getting the built product’s version string (e.g., 1.0) anywhere would be great. Possibly the Xcode plugin can be modified to export those values like the Git plugin does for the repository. That is something we’ll have to investigate later. Overall, Jenkins is a great tool to use. Anyone from small to large companies should be doing continuous integration and using a tool like Jenkins to have consistent builds for release. It will save you time down the road, and maybe save your bacon in a pinch.

Get the RSS feed

Sign-up for our newsletter