(Where it all started in 2015, the Watch update, and almost perfect in 2016)

The 2016 version of my build number system was so close to what I wanted – it automated my build numbers for every target based on the git commit count and kept my git history clean (no build number bumps in source control). It worked almost everywhere ... except Siri extensions. For those it would never increment the build number before the Info.plist was copied. Which was inconsequential from a production standpoint, in the wild for all intents and purposes it was great. The only issue was you'd always get a warning about mis-matched build numbers on upload, and more annoyingly, an email with the same warning too.‌                                                                        

So the change that made it work now without warnings on upload? Oh, it was so devilishly simple.

Make the build number edit in the build folder, not in your source on the original Info.plist. 🤦‍♂️

git=`sh /etc/profile; which git`
bundleVersion=`"$git" rev-list --all |wc -l`
/usr/libexec/PlistBuddy -c "Set :CFBundleVersion $bundleVersion" "${TARGET_BUILD_DIR}/${INFOPLIST_PATH}"

As a byproduct of this change, this also lets you remove the Clear Build Number phase from my 2016 solution as the script never touches your source-controled Info.plist.

Setup Guide

For those who haven't been following along with my struggles, getting started with this build number automation is super simple. For every target you have that gets shipped to App Store Connect, add a build script phase (with an appropriate title like Set Build Number) and copy and past the above code into the script block.

So your targets will look something like this:

And that's it! Enjoy.

I wrote previously about how I set up automated build numbers that were source-control friendly and didn't require a build server.

Unfortunately WatchKit apps (unlike WatchKit extensions) don't have build phases exposed in Xcode, so things get tricky.

After a month of trying I couldn't find a way to get automated numbering working through build scripts in the project itself. It always resulted in code signing errors as the best you could do with phases was change the number after the fact. I ended up having to fall back to using agvtool during release builds to manually bump (or at least using Fastlane, automatically bump) build numbers.

Then a friend pointed me in the right direction.

Manually editing .pbxproj for fun and profit

While the UI isn't exposed, you can still add build phases to the project file for a watchkit app.

Please back up your project first. You'll be manually editing the Xcode project file here.

In your app's folder right click the project file and show package contents. Then open project.pbxproj in your favorite text editor.

Step 1: We need to add a new build phase manually. I'd recommend you complete my previous tutorial first so you have existing phases for automating your build number that you can just duplicate.

Search the file for "CFBundleVersion", part of the script from the last tutorial. You should see it in a block like this left over from my last tutorial:

81B5AC951B0A816900E3CD52 /* Build Number */ = {
  isa = PBXShellScriptBuildPhase;
  buildActionMask = 2147483647;
  files = (
  );
  inputPaths = (
  );
  name = "Build Number";
  outputPaths = (
  );
  runOnlyForDeploymentPostprocessing = 0;
  shellPath = /bin/sh;
  shellScript = "git=`sh /etc/profile; which git`\nbranch_name=`$git symbolic-ref HEAD | sed -e 's,.*/\\\\(.*\\\\),\\\\1,'`\ngit_count=`$git rev-list $branch_name |wc -l | sed 's/^ *//;s/ *$//'`\nsimple_branch_name=`$git rev-parse --abbrev-ref HEAD`\n\nbuild_number=\"$git_count\"\n\nplist=\"${TARGET_BUILD_DIR}/${INFOPLIST_PATH}\"\ndsym_plist=\"${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Info.plist\"\n\n/usr/libexec/PlistBuddy -c \"Set :CFBundleVersion $build_number\" \"$plist\"\nif [ -f \"$DSYM_INFO_PLIST\" ] ; then\n/usr/libexec/PlistBuddy -c \"Set :CFBundleVersion $build_number\" \"$dsym_plist\"\nfi";
};

Copy and paste that block to duplicate it right below the first one, and then change the ID (81B5AC951B0A816900E3CD52 in my case) to something unique. I just changed the ending 2 to a 1. Do a quick search with the new ID to make sure you didn't accidentally pick an ID that's already been used elsewhere in the file.

Remember this ID you just made, we need it for step 2.

Step 2: We need to add a new build phase to the watchkit app. Do a search on the file for "com.apple.product-type.application.watchapp" to find the config used by the watchkit app. It'll look like this:

81B0136E1A6ABD5C0080C8C5 /* WatchKit App */ = {
	isa = PBXNativeTarget;
	buildConfigurationList = 81B013841A6ABD5C0080C8C5 /* Build configuration list for PBXNativeTarget "WatchKit App" */;
	buildPhases = (
		81B0136D1A6ABD5C0080C8C5 /* Resources */,
	);
	buildRules = (
	);
	dependencies = (
	);
	name = "WatchKit App";
	productName = "Slopes WatchKit App";
	productReference = 81B0136F1A6ABD5C0080C8C5 /* WatchKit App.app */;
	productType = "com.apple.product-type.application.watchapp";
};

Add a new line to the build phases using the ID of the phase you created from the last step.

buildPhases = (
  81B5AC951B0A816900E3CD51 /* Build Number */,
  81B0136D1A6ABD5C0080C8C5 /* Resources */,
);

At this point you can save and run and have automated build numbers working for your watchkit app too, satisfying Xcode 6.3's requirement that all your targets must share the same build number.

Big thanks to Conrad Kramer for getting me thinking in the right direction.

Build numbers are one of those things that we just have to deal with while writing software, but it usually provides little benefit to end-users. Much like a git commit hash, it's best left to the computers to generate for us. Lets talk about automating build numbers out of our lives.

Before digging into the how, lets define what I'm trying to achieve though automation:

• I want the version number (1.5.1) to be manually updated as I see fit as it is largely a marketing aspect, not a technical one. I'll usually do this on the release branch when I start a new version.
• I want the build number (1086) to be set automatically based on the number of commits, on the current branch in git, at the time of the build.
• I want the build number to include the branch name (1086-secret-feature-x) if we aren't building a binary for the App Store.
• I want the build numbers to be updated without any affect on my source control.

That last one is a bugger.

My old way - Using an Info.plist preprocessor

A few years ago I invested a little time automating build numbers for my apps in Xcode. Like many I stumbled upon this post from Cocoa is my Girlfriend that leverages info.plist preprocessing and git.

His method takes advantage of being able to define variables in a header file which Xcode will use to automatically replace values in your info.plist file. Just add a build script to keep the value in that header file up-to-date based on the number of git commits and you have automated build numbers. Pretty simple to get working.

Where it falls apart is how that header file affects your source control checkins. Every build will dirty the header. If you don't want to dirty your git repo with checkins on this file you'd need to do something like git update-index --assume-unchanged Source/InfoPlist.h or add it to the .gitignore to make sure it isn't ever checked in (after you check in a dummy file the first time so people who checkout the repo don't get errors), but that falls apart quickly if you're switching branches a lot.

(I've been trying git-flow in Tower recently, which makes heavy usage of branches)

You also run into issues with caching as Xcode tries to cache your info.plist file in between builds and doesn't always re-trigger the pre-processing. This can be a little frustrating when you'd archive without remembering to do a clean first.

My new way - getting dirty with PlistBuddy

If we can't rely on Xcode to update the plist file for us we'll have to do it ourselves. Here is the script in its entirety:

git=`sh /etc/profile; which git`
branch_name=`$git symbolic-ref HEAD | sed -e 's,.*/\\(.*\\),\\1,'`
git_count=`$git rev-list $branch_name |wc -l | sed 's/^ *//;s/ *$//'`
simple_branch_name=`$git rev-parse --abbrev-ref HEAD`

build_number="$git_count"
if [ $CONFIGURATION != "Release" ]; then
	build_number+="-$simple_branch_name"
fi

plist="${TARGET_BUILD_DIR}/${INFOPLIST_PATH}"
dsym_plist="${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Info.plist"

/usr/libexec/PlistBuddy -c "Set :CFBundleVersion $build_number" "$plist"
if [ -f "$DSYM_INFO_PLIST" ] ; then
	/usr/libexec/PlistBuddy -c "Set :CFBundleVersion $build_number" "$dsym_plist"
fi

This makes all the needed build number changes in the build directory itself, so there is no affect on your source-controlled files.

One item of note: it was important to not forget the dSYM info.plist in a script like this (dSYM is the file that stores the debug symbols for your app to help you track down crashes). Leaving that update out will cause HockeyApp, for one, to complain at the mis-match between the build number in the app and the build number in the debug symbols. I'm not sure if this mis-match would affect crash logs in iTunes Connect, too, I never let it get that far.

How to install this script

• Select your project at the top of the navigator on the left
• Select the target you'd like to enable automatic build numbers for
• Select build phases
• From the menu select Editor -> Add Build Phase -> Add Run Script Build Phase
• Copy and paste the above script
• Drag the build phase you added to re-order it to be just after the Copy Bundle Resources step

For good measure I'll usually go into where you normally define the build number (under General for the target) and set it to "UKNOWN." I've never had the script fail, but I'm always paranoid and want to see something obviously wrong if it does.

And, by the way, this can work for any executable target type except Watchkit Apps. This means you can synchronize your build numbers across your app target and any extensions you may have.

I'm looking for a way to easily synchronize version numbers across targets, haven't gotten there yet.

During development of Slopes I decided to refine my Xcode project setup to gracefully allow for multiple versions of my app to exist on-device at the same time. Dev/staging/production is a familiar concept to most software developers, and really it’s surprising it isn’t a default setup in Xcode.

Simon Wolf posted a great article earlier this year on setting up an XCode project to support multiple builds, while having to maintain only a single target. In his article Simon goes over how to make sure each build generates an app with a unique display name (“Slopes β” for a beta build, for example), all of which can be installed on-device simultaneously.

But I’ve found that the name isn’t enough. I, and my testers, have had a difficult time differentiating between the builds on name alone. I wasn’t the biggest fan with his suggestion where one could use the notification badge as an additional visual indicator. I wanted to customize the icon.

Pre-Xcode 5 using a single target prevented me from customizing the app’s icon per build (without annoying build scripts). Fortunately with the introduction of media assets in Xcode 5 there’s a way now.

Before you start, spend some time in Photoshop to generate an app icon for each build you want to customize. I created unique icons for my dev and beta builds.

Feel free to reuse the PSD I made for dev and beta badges. It’s based on the icon template from appicontemplate.com.

Multiple icons using media assets

If you’re migrating from an Xcode 4 project and you haven’t migrated your app icons to media assets yet, you need to do so. Apple makes this switch easy: go to your main target’s general info and hit the use media assets button next to your existing app icon. This will copy your existing app icons into a media asset folder in your project. You’ll see one asset in there called AppIcon.

If your project started in Xcode 5, using media assets for your app icon will be the default. You’ll already see an asset called AppIcon in your catalog.

With the your app’s media asset catalog selected from the project navigator on the left go the system menu and select Editor->New App Icon. Rename this new icon set to AppIconDev and drag in your customized app icons for your dev build. Do the same thing for another new app icon you’ll call AppIconBeta.

With your icons set up, the last step is to tell Xcode which icon set to use for each build. Head over to the build settings for your target and look for the setting called “Asset Catalog App Icon Set Name” under the Asset Catalog Compiler group.

Right now the icon set name should be set to AppIcon for all your configurations. That’s fine for our App Store build but we need to change the name for the dev and beta builds.

If you followed Simon’s article you can expand that setting to see you can specify the app icon set for three configurations: debug, release, and beta (or “adhoc” in Simon’s setup). If you didn’t follow his article, I’d really recommend you go do that and get unique names and bundle IDs set up for your three builds.

Set the icon set name for debug to AppIconDev and set the name for beta to AppIconBeta. Least the icon set name for release the same.

Bonus Round

Similar to how Simon avoided hard-coding the app name and bundle ID by using two custom build settings, BUNDLE_ID_SUFFIX and BUNDLE_DISPLAY_NAME_SUFFIX, you can avoid hard-coding the app icons names with a third suffix: BUNDLE_ICON_SET_SUFFIX. With that in place you can set the icon set name setting to AppIcon${BUNDLE_ICON_SET_SUFFIX} for all three configurations.