What controls the keyboard anyway?

Our first exposure to different keyboard types probably comes from UITextField and UITextView. Both provide conform to the UITextInputTraits protocol which gives us options to set the keyboard type, return key type, keyboard appearance, and other behaviors. Those options cover many of the types of text input we might want to support; plain text, passwords, email addresses, urls, and so on. That’s a good place to start customizing our keyboard options but UITextInputTraits itself doesn’t present the keyboard so when we need behavior the protocol doesn’t provide we will have to keep looking.

Traversing up the class hierarchy we see that UITextField, UITextView, and indeed all UIView objects inherit from UIResponer. All of the responder objects in our views form a responder chain, a sequence of objects which will be given a chance to respond to non-touch input events. (If this isn’t a familiar topic then take a look at “Responder Objects and the Responder Chain” in the “Event Handling Guide for iOS” for a full discussion of how the system works.) Whenever a responder becomes the first responder (see -becomeFirstResponer) it determines what, if any, keyboard needs to be shown. UIResponder gives us two read-only properties for controlling the keyboard’s appearance; inputView which provides the keyboard itself and inputAccessoryView which controls the accessory view attached to the top of the keyboard (containing the “next” and “previous” buttons when editing a form in Mobile Safari for example). By returning our own views from these properties we can replace the system keyboards with any custom UIView we care to construct.

Start simple: customizing UITextView

UITextField (and UITextView) redefine their inputView and inputAccessoryView properties to be readwrite instead of readonly. When working with these view classes we can therefore set their keyboard easily from some other class, like our view controller.

Suppose we were want to support editing markdown formatted text in our app. The system keyboards work well for this but it takes three taps to enter a # or * and \ doesn’t appear on the keyboard at all. That’s going to make it difficult for our users to emphasize text or insert code blocks. Let’s add an input accessory view to give them “emphasize”, “strong”, and “code” formatting controls.

Given a simple view controller with UITextView *textView and UIView *accessoryView outlets we can set the text view’s inputAccessoryView in our -viewDidLoad.

@interface MarkdownViewController : UIViewController

@property (nonatomic, strong) IBOutlet UITextView *textView;
@property (nonatomic, strong) IBOutlet UIView *accessoryView;

@end

@implementation MarkdownViewController

@synthesize textView;
@synthesize accessoryView;

- (void)viewDidLoad
{
    [super viewDidLoad];
    self.textView.inputAccessoryView = self.accessoryView;
}

- (void)viewDidUnload
{
    [super viewDidUnload];
    self.textView = nil;
    self.accessoryView = nil;
}

@end

Now when the text view becomes the first responder we see our accessory view added to the top of the keyboard.

Responding to input

Showing our accessory view is only half of the solution. We also want to make changes to our text view’s content when a user taps one of the accessory view’s buttons. Let’s create a custom view class for our accessory view and give it a reference to the text field.

@interface MarkdownInputAccessoryView : UIView

@property(nonatomic, weak) id <UITextInput> delegate;

- (IBAction)toggleStrong:(id)sender;
- (IBAction)toggleEmphasis:(id)sender;
- (IBAction)toggleCode:(id)sender;

@end

@implementation MarkdownInputAccessoryView

@synthesize delegate;

- (IBAction)toggleStrong:(id)sender {
    UITextRange *selectedText = [delegate selectedTextRange];
    if (selectedText == nil) {
        //no selection or insertion point
        //...
    }
    else if (selectedText.empty) {
        //inserting text at an insertion point
        [delegate replaceRange:selectedText withText:@"*"];
        //...
    }
    else {
        //updated a selected range
        //...
    }
}

- (IBAction)toggleEmphasis:(id)sender {
    //...
}

- (IBAction)toggleCode:(id)sender {
    //...
}

@end

Our controller can then set the delegate property and the accessory view will be able to update the text field.

//...
@property (nonatomic, strong) IBOutlet UIView *accessoryView;
//...
- (void)viewDidLoad
{
    [super viewDidLoad];
    self.accessoryView.delegate = self.textView;
    self.textView.inputAccessoryView = self.accessoryView;
}

Adding complexity: keyboards for a custom UIView

Adding a custom input view is much the same as adding a custom input accessory view. When we’re working with a UITextField or UITextView we can create the custom view and pass it to the appropriate property’s setter.If however we have built a custom UIView subclass then we have to do a little more work.

If it still makes sense for a view controller or other class to provide the view with its input views then we can redeclare inputView and inputAccessoryView as readwrite properties, exposing setters so that the view can be given references to the input views it should use. Alternately we can override the inputView and inputAccessoryView getter methods to return appropriate views. I tend to prefer the latter option because it allows a view to how its own input controls should be presented but if selecting an appropriate input view depends on factors like the current interface idiom or language then it may make more sense for an external service to provide an input view for the current view.

If we wanted to build a view for displaying a score of sheet music we might build something like the following.

@class MusicScoreView;

@interface MusicScoreInputView : UIView

@property (nonatomic, weak) IBOutlet MusicScoreView *delegate;

@end

@interface MusicScoreView ()

@property(nonatomic, readwrite, strong) IBOutlet UIView *inputView;

- (void) loadInputView;

@end

@implementation MusicScoreView

@synthesize inputView;

- (id)initWithFrame:(CGRect)frame {
    self = [super init];
    if (self) {
        [self loadInputView];
    }
    return self;    
}

- (id)initWithCoder:(NSCoder *)coder
{
    self = [super initWithCoder:coder];
    if (self) {
        [self loadInputView];
    }
    return self;
}

- (void)loadInputView {
    UINib *inputViewNib = [UINib nibWithNibName:@"MusicScoreInputView" bundle:nil];
    [inputViewNib instantiateWithOwner:self options:nil];
}

@end

@interface MusicScoreInputView : UIView

@property (nonatomic, weak) IBOutlet MusicScoreView *delegate;

@end

@implementation MusicScoreInputView

@synthesize delegate;

@end

Visual styling: reacting to the keyboard

Now that we can display a custom keyboard we still need to make sure to adjust our views when it appears. Since the actual presentation of our input view is handled by UIKit we need to observe and react to the notifications the framework sends to announce changes in the input view’s position. Apple provides a set of NSNotifications we can observe:

• UIKeyboardWillShowNotification
• UIKeyboardDidShowNotification
• UIKeyboardWillHideNotification
• UIKeyboardDidHideNotification

Each of these notifications includes a user info dictionary which describes the frame of the keyboard before and after its transition and the timing of the animation which will be used to show or hide it. When we rotate a device the keyboard may be resized to better support the new orientation. In that case we’ll need to update the insets or positions of our other views as well to reflect these new dimensions. Again UIKit provides a set of notifications we can observe to determine the changing bounds of the keyboard and react accordingly.

• UIKeyboardWillChangeFrameNotification
• UIKeyboardDidChangeFrameNotification

Given these we can respond to the appearance or disappearance of the keyboard as needed.

- (void)viewWillAppear:(BOOL)animated {
    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(updateScrollInsets:) name:UIKeyboardWillShowNotification object:nil];
    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(updateScrollInsets:) name:UIKeyboardWillChangeFrameNotification object:nil];
    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(resetScrollInsets:) name:UIKeyboardWillHideNotification object:nil];
}

- (void)viewDidDisappear:(BOOL)animated {
    [[NSNotificationCenter defaultCenter] removeObserver:self];
}

In most cases we will want to respond by adjusting the contentInset and scrollIndicatorInsets of a UIScrollView to add enough padding to the bottom of our scroll view’s content view that all of its content can scroll to a position above the top of the keyboard. Alternately we might adjust the frames of some of our views directly but this is less desirable because it might leave a blank region on the screen (rather than showing the scroll view’s background color), especially on an iPad where the user can choose to split the keyboard.

To calculate the appropriate insets we need to be aware that the keyboard is presented anchored to the bottom of the window, which is not necessarily flush with the bottom of the current view controller’s view (for example we might have a tab bar or tool bar visible). We should only add insets equal to the height of the portion of our view which is being hidden by the keyboard.

- (void) updateScrollInsets:(NSNotification *)notification {
    //determine what portion of the view will be hidden by the keyboard
    CGRect keyboardEndFrameInScreenCoordinates;
    [[notification.userInfo objectForKey:UIKeyboardFrameEndUserInfoKey] getValue:&keyboardEndFrameInScreenCoordinates];
    CGRect keyboardEndFrameInWindowCoordinates = [self.view.window convertRect:keyboardEndFrameInScreenCoordinates fromWindow:nil];
    CGRect keyboardEndFrameInViewCoordinates = [self.view convertRect:keyboardEndFrameInWindowCoordinates fromView:nil];
    CGRect windowFrameInViewCoords = [self.view convertRect:self.view.window.frame fromView:nil];
    CGFloat heightBelowViewInWindow = windowFrameInViewCoords.origin.y + windowFrameInViewCoords.size.height - (self.view.frame.origin.y + self.view.frame.size.height);
    CGFloat heightCoveredByKeyboard = keyboardEndFrameInViewCoordinates.size.height - heightBelowViewInWindow;

    //build an inset to add padding to the content view equal to the height of the portion of the view hidden by the keyboard
    UIEdgeInsets insets = UIEdgeInsetsMake(0, 0, heightCoveredByKeyboard, 0);
    [self setInsets:insets givenUserInfo:notification.userInfo];
}

- (void) resetScrollInsets:(NSNotification *)notification {
    UIEdgeInsets insets = UIEdgeInsetsMake(0, 0, 0, 0);
    [self setInsets:insets givenUserInfo:notification.userInfo];
}

- (void) setInsets:(UIEdgeInsets)insets givenUserInfo:(NSDictionary *)userInfo {
    //match the keyboard's animation
    double duration = [[userInfo objectForKey:UIKeyboardAnimationDurationUserInfoKey] doubleValue];
    UIViewAnimationCurve animationCurve = [[userInfo objectForKey:UIKeyboardAnimationCurveUserInfoKey] intValue];
    UIViewAnimationOptions animationOptions = animationCurve;
    [UIView animateWithDuration:duration delay:0 options:animationOptions animations:^{
        self.textView.contentInset = insets;
        self.textView.scrollIndicatorInsets = insets;
    } completion:nil];
}

Summary

We’ve seen how to define custom input and input accessory views to enhance or replace the system keyboard. How to add those input views to existing text fields, text views, and to our own custom view classes. When an input view does appear we can also now appropriately adjust the rest of our content to accommodate it. With these tools we should now be ready to build custom input views tailored to the type of data we need and the context in which it will be gathered.

The examples given above are also available at https://jonah-carbonfive@github.com/jonah-carbonfive/CustomInputViewDemo.git

Monkey-patching is extending or modifying the behavior of code at runtime without changing its original source code. You can monkey-patch any code, it doesn’t matter whether it’s your own code or not. This is distinctly different than traditional sub-classing because you are not creating a new class, instead, you are reopening an existing class and changing its behavior.

Monkey-patching is possible in Objective-C by using categories. In fact, the definition of a category practically matches that of monkey-patching:

"A category allows you to add methods to an existing class—even to one for which you do not have the source."

In this series of posts, we’ll use categories to add and change methods, to add new instance variables and properties, and introduce swizzling, a technique that allows us to extend and preserve existing functionality. TL;DR »

Category Basics

To modify an existing class specify the category in both its interface and implementation definitions:

Interface Definition

Implementation

Adding Simple Methods

The most basic usage of categories is to add a new method to an existing class.

Suppose in our application we want to output dates relative to the current time, e.g., “13 minutes ago”, “4 hours ago”, “just now”, etc. Traditional object-oriented solutions would have us introducing a new class that either extends NSDate (e.g., creating a RelativeDescriptionDate subclass with a timeAgoInWords instance method) or is a standalone helper/utility class (e.g., [NSDateHelper timeAgoInWordsFromDate:myDate]).

But with categories, we can reopen the NSDate class and simply add a new instance method:

NSDate+Formatting.h

NSDate+Formatting.m

Now every NSDate object will have the new method available to it. The following code:

Will print out the following on the console:

The Dangers of Simply Overriding Methods

We can take this a step further and instead of adding new behavior we’ll override existing behavior. Continuing with our example, what if we wanted the default description of a NSDate object to include the time ago in words? We could simply do the following:

However, this is strongly discouraged for two reasons.

1. Other frameworks may rely on the expected behavior of the original method. We now have to go through the trouble of re-implementing that behavior, in addition to the new functionality we wanted to introduce, or risk strange side effects and possibly even crashing out.
2. If multiple categories implement the same method, the last one loaded wins! The load order is consistent within an application, but it’s arbitrary, out of our hands, and fragile. For all we know, our implementation could itself be overwritten by an internal framework category!

Because of these reasons, this blunt approach to overriding methods should only be used for the simplest of cases. Later in this series, we’ll explore how swizzling allows us to override a method while preserving all implementations.

Including Your Monkey-Patches

Categories are not automatically “picked up” in a project. Any code that relies on the behavior will need to #import the necessary header files:

However, including the same set of headers over and over again is redundant. We should first create a single header file that imports all of our most frequently used categories:

We can then import this single header file into a prefix header that is added to all source files. XCode projects often have a .pch file in the Supporting Files group for this very purpose.

Next Up

While adding and overriding classes is straightforward, there is one very big caveat when using Categories; you cannot add new instance variables to a class. We’ll take a look at working around this limitation in the next post.

tl;dr

• Use Objective-C categories to add functionality to existing classes without subclassing.
• Avoid simple overrides with categories as it can cause problems with other frameworks.
• Use prefix headers to easily import your extensions.

Step 1: Modify Your Default PList File

Your default plist file is usually named ${PRODUCT_NAME}-Info.plist and is located beneath the “Supporting Files” group of your Xcode project. Add a new row/item of type String to the plist file and name it Configuration. Set the value to be ${CONFIGURATION}, the Xcode provided environment variable for the current build configuration.

Step 2: Create a Custom Environments.plist File to Store Configuration Data

Right-click on the “Supporting Files” group and select “New File” (New File > Resource > Property List). Save File as “Environments”, this will create a file named “Environments.plist”. Now that you have your custom plist file ready to be modified, add all of your build configurations (Debug and Release by default) of type Dictionary to the plist. You can also begin to enter custom properties underneath each build configuration (entered as myAPIURL in my example).

Optionally, you can segregate your property files per build configuration. For example, create plist files for each of your build configurations (i.e. Debug.plist, Release.plist).

Step 3: Make your Custom Configuration Available to your Application

Create a singleton or implement a strategy to load your configuration data on a per build configuration basis. You can determine your scheme’s current build configuration by reading the “Configuration” property within your default plist file (as applied in step one).

For example, here is a singleton that will load your configuration:

Now you should be able to access properties within your application by sending getter messages to the Environment instance.

Environment *myEnvironment = [Environment sharedInstance];
NSString *apiURL = myEnvironment.myApiURL;

Step 4: Add Additional Build Configurations to your Application

Within Xcode, select your Project within the left-hand navigation. Your project and target settings should be visible and editable. Next, select your project settings so that your build configurations are exposed (by default, Xcode creates the Debug and Release build configurations for you). At this point you can create a new build configuration for a custom environment (i.e. acceptance, staging or demo).

Also, don’t forget to add your custom configuration data for your new build configuration.

Now Your Ready!

Your application now has access to configurations per environment by use of build configurations. We’ve made the current build configuration readable by adding it to the default plist file. We used the current build configuration as an identifier for key’ing entries in a custom properties file (Environments.plist). The custom properties file contains configuration properties per build configuration. In order to read the custom properties programmatically, we created an object (Environment.m) to read the file. Finally, we added custom build configurations to support new, application specific, environments.

Some side notes:

• One target, configurable schemes: You can change the build configuration you would like to use for a target by editing (or creating) your scheme. This will quickly allow you to run your target against different application environments.
• Properties like bundle identifier and bundle name can be set by user defined properties and further specified by your build configurations. This will make deploying you application to devices easier.
• The Xcode command line build tool has a parameter named “configuration”. This will allow you to build your application per environment (i.e. xcodebuild -configuration Debug).

: Succeeded! Received 18977 bytes of data for url http://www…
: fetched comments: ( …<74k of JSON>
: *** …GetData: http://…/query?id=1001&sc=17&fields=…&apiKey=
: applicationDidBecomeActive completed
: JSON parsing finished in 24 ms. String alloc took 2 ms. Comment stripping took 1 ms.
: CallbackHandler registered delegate,, instance=0×263650

There are a number of examples of using precompiler macros to eliminate log output on non-debug builds but I recently started using Xcode 4′s breakpoints and find them to be my favorite mechanism. Breakpoints can be configured to log arbitrary output and automatically continue to avoid stopping program execution. They can be dragged from one line to another, added, disabled, and removed while your app is running. You can even check them in as part of your project to share them with other developers.

Console logging with breakpoints
Create a new breakpoint by clicking in the source editor’s gutter.
Control-click the breakpoint to edit its behavior.

When hit the example breakpoint above will log -didReceiveMemoryWarning my title is "Demo!" to the console.

Sharing breakpoints
In the breakpoint navigator control-click a breakpoint to share it as part of a workspace.
Shared breakpoints are stored in .xcworkspace/xcshareddata/xcdebugger/Breakpoints.xcbkptlist


I’ve found breakpoints to be a great way to log debug information about the app in a configuration which I can choose to share with my team and which runs no risk of appearing in a release build. The breakpoints navigator gives me an easy way to jump to any of these log statements and it is trivial to switch a breakpoint from just logging to pausing the app so I can debug in depth. I’ll still use NSLog for exceptional conditions I want to report in any build but so far you won’t find a single one in my current project.

Have you found a NSLog alternative you are happy with? Is there anything you couldn’t replace with logging breakpoints instead?

I created a basic project configuration in TeamCity 6 to checkout my iOS project from git.

I set the artifact paths for this configuration to

project_name.acceptance.app*
ad_hoc/*.png

This will eventually allow TeamCity to collect the icons, project_name.acceptance.app.ipa, and project_name.acceptance.app.plist files needed to perform an over the air install of the ad hoc build.

Finally I created the following custom script build step (available as https://gist.github.com/949831).

#!/bin/bash

# https://gist.github.com/949831
# http://blog.carbonfive.com/2011/05/04/automated-ad-hoc-builds-using-xcode-4/

# command line OTA distribution references and examples
# http://nachbaur.com/blog/how-to-automate-your-iphone-app-builds-with-hudson
# http://nachbaur.com/blog/building-ios-apps-for-over-the-air-adhoc-distribution
# http://blog.octo.com/en/automating-over-the-air-deployment-for-iphone/
# http://www.neat.io/posts/2010/10/27/automated-ota-ios-app-distribution.html

project_dir=`pwd`

# Configuration
environment_name="staging"
keychain="ci_keys"
keychain_password="super secret"
workspace="MyApp.xcworkspace"
scheme="Ad Hoc"
info_plist="$project_dir/MyApp-Info.plist"
environment_plist="$environment_name.plist"
environment_info_plist="$environment_name-Info.plist"
product_name="My App $environment_name"
mobileprovision="$project_dir/ad_hoc/MyAppStaging.mobileprovision"
provisioning_profile="iPhone Distribution: My Company, LLC"
build_number="%env.BUILD_NUMBER%"
artifacts_url="http://my_ci_server.example/artifacts/$build_number"
display_image_name="Icon-57.png"
full_size_image_name="Icon-512.png"

function failed()
{
    local error=${1:-Undefined error}
    echo "Failed: $error" >&2
    exit 1
}

function validate_keychain()
{
  # unlock the keychain containing the provisioning profile's private key and set it as the default keychain
  security unlock-keychain -p "$keychain_password" "$HOME/Library/Keychains/$keychain.keychain"
  security default-keychain -s "$HOME/Library/Keychains/$keychain.keychain"

  #describe the available provisioning profiles
  echo "Available provisioning profiles"
  security find-identity -p codesigning -v

  #verify that the requested provisioning profile can be found
  (security find-certificate -a -c "$provisioning_profile" -Z | grep ^SHA-1) || failed provisioning_profile
}

function describe_sdks()
{
  #list the installed sdks
  echo "Available SDKs"
  xcodebuild -showsdks
}

function describe_workspace()
{
  #describe the project workspace
  echo "Available schemes"
  xcodebuild -list -workspace $workspace
}

function increment_version()
{
  cd "MyApp"
  agvtool -noscm new-version -all $build_number
  cd ..
}

function set_environment()
{
  #copy the info plist for the selected environment into place
  cp -v "MyApp/$environment_info_plist" $info_plist || failed environment_plist
  #copy the environment settings plist into place
  cp -v "MyApp/$environment_plist" "MyApp/environment.plist" || failed environment

  #extract settings from the Info.plist file
  info_plist_domain=$(ls $info_plist | sed -e 's/\.plist//')
  short_version_string=$(defaults read "$info_plist_domain" CFBundleShortVersionString)
  bundle_identifier=$(defaults read "$info_plist_domain" CFBundleIdentifier)
  echo "Environment set to $bundle_identifier at version $short_version_string"
}

function build_app()
{
  local devired_data_path="$HOME/Library/Developer/Xcode/DerivedData"

  #get the name of the workspace to be build, used as the prefix of the DerivedData directory for this build
  local workspace_name=$(echo "$workspace" | sed -n 's/\([^\.]\{1,\}\)\.xcworkspace/\1/p')
  #build the app
  echo "Running xcodebuild > xcodebuild_output ..."

#  disabled overriding PRODUCT_NAME, setting applies to all built targets in Xcode 4 which renames static library target dependencies and breaks linking
#  xcodebuild -verbose -workspace "$workspace" -scheme "$scheme" -sdk iphoneos -configuration Release clean build PRODUCT_NAME="$product_name" >| xcodebuild_output
  xcodebuild -verbose -workspace "$workspace" -scheme "$scheme" -sdk iphoneos -configuration Release clean build >| xcodebuild_output

  if [ $? -ne 0 ]
  then
    tail -n20 xcodebuild_output
    failed xcodebuild
  fi

  #locate this project's DerivedData directory
  local project_derived_data_directory=$(grep -oE "$workspace_name-([a-zA-Z0-9]+)[/]" xcodebuild_output | sed -n "s/\($workspace_name-[a-z]\{1,\}\)\//\1/p" | head -n1)
  local project_derived_data_path="$devired_data_path/$project_derived_data_directory"
  #locate the .app file

#  infer app name since it cannot currently be set using the product name, see comment above
#  project_app="$product_name.app"
  project_app=$(ls -1 "$project_derived_data_path/Build/Products/Release-iphoneos/" | grep ".*\.app$" | head -n1)

  # if [ $(ls -1 "$project_derived_data_path/Build/Products/Release-iphoneos/$project_app" | wc -l) -ne 1 ]
  if [ $(ls -1 "$project_derived_data_path/Build/Products/Release-iphoneos/" | grep ".*\.app$" | wc -l) -ne 1 ]
  then
    echo "Failed to find a single .app build product."
    # echo "Failed to locate $project_derived_data_path/Build/Products/Release-iphoneos/$project_app"
    failed locate_built_product
  fi
  echo "Built $project_app in $project_derived_data_path"

  #copy app and dSYM files to the working directory
  cp -Rf "$project_derived_data_path/Build/Products/Release-iphoneos/$project_app" $project_dir
  cp -Rf "$project_derived_data_path/Build/Products/Release-iphoneos/$project_app.dSYM" $project_dir

  #rename app and dSYM so that multiple environments with the same product name are identifiable
  echo "Retrieving build products..."
  rm -rf $project_dir/$bundle_identifier.app
  rm -rf $project_dir/$bundle_identifier.app.dSYM
  mv -f "$project_dir/$project_app" "$project_dir/$bundle_identifier.app"
  echo "$project_dir/$bundle_identifier.app"
  mv -f "$project_dir/$project_app.dSYM" "$project_dir/$bundle_identifier.app.dSYM"
  echo "$project_dir/$bundle_identifier.app.dSYM"
  project_app=$bundle_identifier.app

  #relink CodeResources, xcodebuild does not reliably construct the appropriate symlink
  rm "$project_app/CodeResources"
  ln -s "$project_app/_CodeSignature/CodeResources" "$project_app/CodeResources"
}

function sign_app()
{
  echo "Codesign as \"$provisioning_profile\", embedding provisioning profile $mobileprovision"
  #sign build for distribution and package as a .ipa
  xcrun -sdk iphoneos PackageApplication "$project_dir/$project_app" -o "$project_dir/$project_app.ipa" --sign "$provisioning_profile" --embed "$mobileprovision" || failed codesign
}

function verify_app()
{
  #verify the resulting app
  codesign -d -vvv --file-list - "$project_dir/$project_app" || failed verification
}

function build_ota_plist()
{
  echo "Generating $project_app.plist"
  cat << EOF > $project_app.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>items</key>
  <array>
    <dict>
      <key>assets</key>
      <array>
        <dict>
          <key>kind</key>
          <string>software-package</string>
          <key>url</key>
          <string>$artifacts_url/$project_app.ipa</string>
        </dict>
        <dict>
          <key>kind</key>
          <string>full-size-image</string>
          <key>needs-shine</key>
          <true/>
          <key>url</key>
          <string>$artifacts_url/$full_size_image_name</string>
        </dict>
        <dict>
          <key>kind</key>
          <string>display-image</string>
          <key>needs-shine</key>
          <true/>
          <key>url</key>
          <string>$artifacts_url/$display_image_name</string>
        </dict>
      </array>
      <key>metadata</key>
      <dict>
        <key>bundle-identifier</key>
        <string>$bundle_identifier</string>
        <key>bundle-version</key>
        <string>$short_version_string $build_number</string>
        <key>kind</key>
        <string>software</string>
        <key>subtitle</key>
        <string>$environment_name</string>
        <key>title</key>
        <string>$project_app</string>
      </dict>
    </dict>
  </array>
</dict>
</plist>
EOF
}

echo "**** Validate Keychain"
validate_keychain
echo
echo "**** Describe SDKs"
describe_sdks
echo
echo "**** Describe Workspace"
describe_workspace
echo
echo "**** Set Environment"
set_environment
echo
echo "**** Increment Bundle Version"
increment_version
echo
echo "**** Build"
build_app
echo
echo "**** Package Application"
sign_app
echo
echo "**** Verify"
verify_app
echo
echo "**** Prepare OTA Distribution"
build_ota_plist
echo
echo "**** Complete!"

That is quite a few functions but the bottom of the script steps through them in what is hopefully an understandable sequence.

1. Unlock the keychain containing the private key and provisioning profile used to sign the ad hoc build. Necessary since the TeamCity user’s login keychain may be locked when this build runs.
2. List the available sdks on the build machine (unnecessary but I found it helpful when debugging build settings).
3. List the schemes found in the workspace to be built (again purely for debugging).
4. Copy a plist containing application settings to “environment.plist” which will be copied into the app bundle when built and used to define application behavior, for example it contains the url of the server this build should communicate with.
5. Build the app using the specified workspace and scheme. Copy the resulting app and dSYM to the project directory so TeamCity can easily find them as build artifacts.
6. Sign the app using the specified mobile provisioning profile and create a “.ipa” package.
7. Verify that the app was successfully signed.
8. Create a plist to allow over the air installation of the app.

Once run any device which has been added to the mobile provisioning profile used to sign this build can install the app just by visiting (using an appropriate %system.teamcity.buildType.id% for the TeamCity build configuration).

itms-services://?action=download-manifest&url=http://teamcity.example.com:8111/guestAuth/repository/download/%system.teamcity.buildType.id%/.lastSuccessful/project_name.acceptance.app.plist

Possible issues:

• Access to the keychain will present a security dialog the first time this build runs so it was necessary for me to sign into the TeamCity user’s account using VNC and allow access to that keychain.
• I found that builds occasionally failed to correctly create the CodeResources symlink so I recreate it manually. When this link was broken the ipa would fail verification.
• An iOS device won’t be able to install the app if the artifacts require authenticating to the TeamCity server so I enabled guest access. Alternately I could have exposed those artifacts through some other service and created a nice installation guide page which links to them if I didn’t want to allow guest access to my TeamCity server.

For additional resources for building over the air distribution builds take a look at:

Mike Nachbaur’s posts on “How to Automate your iPhone App Builds with Hudson” and “Building iOS Apps for Over the Air Ad Hoc Distribution“.
Vincent Daubry’s “Automating Over The Air Deployment for iPhone“.
Basil Shkara’s “Automated OTA iOS App Distribution“.

> /Developer_Xcode4/usr/bin/xcodebuild -help
Usage: xcodebuild [-project ] [[-target ]…|-alltargets] [-configuration ] [-arch ]… [-sdk [|]] [=]… []…
xcodebuild -workspace -scheme [-configuration ] [-arch ]… [-sdk [|]] [=]… []…
xcodebuild -version [-sdk [|] [] ]
xcodebuild -list [[-project ]|[-workspace ]]
xcodebuild -showsdks

The workspace and scheme names should be known from the project. The default configuration options are “Debug” and “Release”. The “-showsdks” option lists available SDKs.

> /Developer_Xcode4/usr/bin/xcodebuild -showsdks
Mac OS X SDKs:
Mac OS X 10.6 -sdk macosx10.6

iOS SDKs:
iOS 4.3 -sdk iphoneos4.3

iOS Simulator SDKs:
Simulator – iOS 3.2 -sdk iphonesimulator3.2
Simulator – iOS 4.0 -sdk iphonesimulator4.0
Simulator – iOS 4.1 -sdk iphonesimulator4.1
Simulator – iOS 4.2 -sdk iphonesimulator4.2
Simulator – iOS 4.3 -sdk iphonesimulator4.3

Available build actions are listed in the xcodebuild man pages. Unfortunately these do not match the actions available in a scheme and the command line does not provide a mechanism for testing, running, profiling, or analyzing builds.

> man xcodebuild
…

buildaction …
Specify a build action (or actions) to perform on the target. Available build actions are:

build Build the target in the build root (SYMROOT). This is the default build action.

archive Archive a scheme from the build root (SYMROOT). This requires specifying a workspace and scheme.

installsrc Copy the source of the project to the source root (SRCROOT).

install Build the target and install it into the target’s installation directory in the distribution root (DSTROOT).

clean Remove build products and intermediate files from the build root (SYMROOT).

Given all of these configuration options it is then possible to perform builds from the command line.

> /Developer_Xcode4/usr/bin/xcodebuild -workspace WrappingScrollView.xcworkspace -scheme WrappingScrollViewDemo -sdk iphonesimulator4.3 -configuration Debug clean build
Build settings from command line:
SDKROOT = iphonesimulator4.3

=== CLEAN NATIVE TARGET JCFWrappingScrollView OF PROJECT JCFWrappingScrollView WITH CONFIGURATION Debug ===
Check dependencies

…

** CLEAN SUCCEEDED **

=== BUILD NATIVE TARGET JCFWrappingScrollView OF PROJECT JCFWrappingScrollView WITH CONFIGURATION Debug ===
Check dependencies

ProcessPCH /Users/Jonah/Library/Developer/Xcode/DerivedData/WrappingScrollView-fqscqfdtpoqunuanehtbgpseirdj/Build/PrecompiledHeaders/JCFWrappingScrollView-Prefix-dkkjrdaonxokgpbkgjfmpmcpadoz/JCFWrappingScrollView-Prefix.pch.gch JCFWrappingScrollView/JCFWrappingScrollView-Prefix.pch normal i386 objective-c com.apple.compilers.llvmgcc42
cd /Users/Jonah/Desktop/WrappingScrollView/JCFWrappingScrollView
setenv LANG en_US.US-ASCII

…

** BUILD SUCCEEDED **

Hopefully that is sufficient to automatically produce ad-hoc builds on a continuous integration server.

1. Background
2. Using a Static Library
3. Creating a Static Library
4. Future Improvements

Background

Workspaces:

Xcode 4 introduced the concept of workspaces as containers for multiple projects. There are a couple of key behaviors of workspaces which we want to build on when choosing how to share code across projects.

• By default, all the Xcode projects in a workspace are built in the same directory, referred to as the workspace build directory.
• Xcode examines the files in the build directory to discover implicit dependencies.
• Each project in a workspace continues to have its own independent identity.

Schemes:

Within a workspace or within a project which is a member of a workspace we have schemes. Schemes replace the Active Target, Build Configuration, and Executable settings from Xcode 3 and define which targets to build, the order in which to build them, and what action to take when a build is complete. We’ll want our shared code to easily fit into the scheme of any projects which use it. The Xcode 4 Transition Guide covers this new structure in more detail.

Targets:

Within a scheme we have one or more build targets which define a set of source files to build, the settings used to build those files, and any dependencies on the build products of other targets which must be completed first. Ultimately we would like a consumer of our code to be able to state that their project’s build target depends on our shared code and have Xcode build this shared code and make it available to the active build target. We can achieve that by providing a project containing the code to be shared and a static library build target which packages it into a build product other developers can add as a build target dependency.

Using a static library

1. Creating a workspace
2. Adding projects to a workspace
3. Adding build target dependencies
4. Adding the static library’s headers
5. Configuring the project’s scheme
6. Fixing indexing

Creating a workspace

We can create a new empty workspace from Xcode’s file menu or open an existing project and select “Save As Workspace…” to create a new workspace containing our project. This will create a “.xcworkspace” package in the file system.

An empty Xcode 4 workspace

Adding projects to a workspace

Once we have a workspace we can right-click in the workspace’s navigator to create a new project or add an existing “.xcodeproj” package.

Adding a new project to a workspace

Adding an existing project to a workspace

We want to end up with a single workspace containing our app’s project and the projects for any static libraries we are going to depend on. It is worth noting that these projects are all siblings in the workspace, our static libraries are not added as references within our app’s project.

Adding build target dependencies

With all of the projects we need available in our workspace we can select our app’s build target and add a static library to the “Link Binary With Libraries” build phase.

Libraries and frameworks available to add to the "Link Binary With Libraries" build phase

A static library added to the "Link Binary With Libraries" build phase

Adding the static library’s headers

We also need to make sure that our app’s build target can locate the public headers used in this static library. Open the “Build Settings” tab and locate the “User Header Search Paths” setting. Set this to “$(BUILT_PRODUCTS_DIR)” (or “$(BUILT_PRODUCTS_DIR)/static_library_name” if we want to be more specific but then we’ll have to update this setting every time we add another library) and check the “Recursive” check box. Now our built target will search our workspace’s shared build directory to locate linkable header files.

Setting the User Header Search Paths

User Header Search Paths set

The “User Header Search Paths” setting defines the headers available as quoted imports (eg “#import “MyLibraryClass.h”) while the “Header Search Paths” setting defines those headers available as bracketed imports (eg “#import ). I’ve found that Xcode will only autocomplete header names in the quoted form so I always add libraries to the user header search path even though, from my project’s perspective, they might be more appropriate as system level (angle bracketed) libraries.

When using a static library which includes categories we will also have to add the “-ObjC” flag to the “Other Linker Flags” build setting. This will force the linker to load all objective-c classes and categories from the library. If the library contains only categories “-all_load” or “-force_load” may be needed as well. See Technical Q&A QA1490 for a more detailed explanation of these settings.

Configuring the project’s scheme

At this point Xcode should have detected this implicit dependency between our app’s project and the static library’s project and have automatically configured our schemes correctly. Unfortunately I haven’t found this to be the case in practice. Instead we will have to edit our current scheme and add the static library’s build target before our app’s build target.

Setting the scheme's target build order

Fixing indexing

At this point we should be able to include headers from dependent static libraries, use the included classes, and still successfully build our app. Unfortunately Xcode will not show any classes from these linked static libraries in code completion despite the workspace documentation stating that “indexing is done across the entire workspace, extending the scope of content-aware features such as code completion and refactoring.”
As a workaround we can drag the public headers from the static library’s project into our app’s project, adding them as references. These headers do not need to be included in any of our build targets, simply having references to the headers in our project will allow their classes to appear in code completion.

Creating a Static Library

If we plan on releasing some of our own code for reuse as a static library there are several things we should do to make sure that the process described above is as easy and simple as possible for our library’s users.

1. Namespace classes appropriately
2. Create a build target
3. Expose public headers
4. Set the installation directory
5. Set the public header path
6. Exclude user specific files from VCS

Namespace classes appropriately

Use an appropriate prefix for classes, protocols, functions, and constants in the library to prevent collisions with names in the library’s user’s project.

Create a build target

Provide a static library build target in the project for our users to link against. Xcode provides templates for creating projects with static libraries or adding static library build targets to existing projects.

Expose public headers

Determine which header files should be visible to users of the library. Provide a clearly named group containing these headers so that our library’s users can easily locate them as part of the workaround described in “Fixing Indexing” above. This also helps us clarify what the public interface our library provides is and what classes are implementation details which are likely to change as the library evolves.

For each public header file make sure it is set as “public” in the “Target Membership” section of the inspector pane. Only public headers are going to be available for our users to import.

Making a header file public

Set installation directory

Our static library build target is going to be a member of a user’s workspace and subject to that workspace’s installation rules. Our static library build product could therefore be installed in a location set by Xcode’s preferences, in the derived data path, or in a path specified by our build target. Since we can’t control the user’s settings we should make sure our library is well behaved in all cases. I set the “Installation Directory” build setting to “$(BUILT_PRODUCTS_DIR)” so that the static library build product can be found in a known location and set the “Skip Install” build setting to “Yes” to avoid accidentally installing iOS libraries into “/usr/local/lib”.

Setting the installation directory

Set the public header path

We need to specify a location to copy our static library’s public headers to so that they can be included in our users’ header search paths. Setting the “Public Headers Folder Path” to “$(TARGET_NAME)” will create a folder named after our static library build target in the workspace’s shared build directory and be indexed by the “User Header Search Paths” setting described above.

Setting the public headers path for the static library

Exclude user specific files from VCS

Our workspace and project include a number of files which contain data relevant only to our user account; window positions, open files, and so on. There’s no need to check these into source control, at least not in our release branch, so let’s set some reasonable ignore rules in git or whatever VCS we are using. Github provides a convenient set of .gitignore files

Future Improvements

Hopefully Xcode 4 will eventually live up to the promise of it’s documentation and consistently auto-detect implicit dependencies and index files across the workspace correctly. There certainly seem to be a number of other developers struggling with this behavior:[1], [2], [3], [4], [5], [6], [7], [8]. Until that indexing improves I find that this process is at least somewhat simpler and cleaner than trying to maintain simulator and device compatible static library builds in Xcode 3.
I’ve found this pattern preferable to copying third party classes directly into my projects as it allows me to easily keep version history and make updates to static library projects in my workspace and avoids coupling my project too closely to the private structure and contents of the static library.
Please let me know if you can see any areas where this pattern could be improved or if you’ve found your own alternative means of sharing code.

Any app which contains code like
[viewController.view addSubview:someOtherViewController.view];
or
viewController.view.bounds = CGRectMake(50, 50, 100, 200);
or which loads a nib doing the equivalent is abusing UIViewControllers. Given time this will emerge as bugs or at least pain for developers continuing to work on the app.

What? How is that wrong?

The core problem, and surprise for too many developers, is stated in the “View Controller Programing Guide for iOS” in “About Custom View Controllers“:

Each custom view controller object you create is responsible for managing all of the views in a single view hierarchy. In iPhone applications, the views in a view hierarchy traditionally cover the entire screen, but in iPad applications they may cover only a portion of the screen. The one-to-one correspondence between a view controller and the views in its view hierarchy is the key design consideration. You should not use multiple custom view controllers to manage different portions of the same view hierarchy. Similarly, you should not use a single custom view controller object to manage multiple screens worth of content.

Essentially the rootViewController of the current UIWindow should be the only UIViewController with a visible view.

With multiple UIViewController’s views visible at once some of those controllers may not receive important messages like -viewWillAppear: or -didReceiveMemoryWarning. Additionally some of their properties like parentViewController and interfaceOrientation may not be set or updated as expected.

“Why won’t my UIViewController rotate with the device?” states this even more explicitly.

If you add an additional view controller’s UIView property to UIWindow (at the same level as your primary view controller) via the following:

[myWindow addSubview:anotherController.view];

this additional view controller will not receive rotation events and will never rotate. Only the first view controller added to UIWindow will rotate.

Now Apple is able to provide “container view controllers” like UINavigationController and UITabBarController which manage the presentation of other UIViewController’s views. Unfortunately to do so requires the use of private API calls which are not available for any app seeking approval for distribution in the App Store (discussed in more detail here: https://devforums.apple.com/message/310806#310806). We can come close but without a supported path for implementing custom container view controllers nesting UIViewControllers’ views will not give us all the behavior we expect from a UIViewController.

Isn’t close good enough?

Not really. We can implement a custom container view controller which sends messages like -viewWillAppear to its child view controllers but that only solves part of the problem.

• Without being able to rely on interfaceOrientation those child view controllers may never support rotation correctly.
  Since view controllers’ views are expected to fill the window views “behind” modal view controllers may not be drawn or may be unloaded while visible.
• Without properties like parentViewController or navigationController being set all of our child view controllers need to be aware of how they are being presented and the fact that they cannot rely on all the behavior they should be able to expect from inheriting from UIViewController.
• Child view controllers may not be properly inserted into the responder chain so they may never see events passed up the chain from their views.

With no public setters available for these properties or documentation of these behaviors there’s currently no way to resolve this situation (see this thread for further discussion: https://devforums.apple.com/message/365171#365171). Since there is currently no supported means of creating container view controllers those behaviors which do work now are not guaranteed to continue to function in future iOS updates and may vary between existing iOS versions.
By nesting UIViewControllers we create a UIViewController instance which cannot rely on the entire contract offered by UIViewController. A non-obvious and context specific problem for any developer working on the app in the future.

So what’s the alternative?

The “View Controller Programming Guide for iOS” at least suggests an alternative:

Note: If you want to divide a view hierarchy into multiple subareas and manage each one separately, use generic controller objects (custom objects descending from NSObject) instead of view controller objects to manage each subarea. Then use a single view controller object to manage the generic controller objects.

A controller does not necessarily have to be a subclass of UIViewController. We can create controller objects responsible for managing specific behaviors or portions of our view and have these controllers inherit from NSObject instead of from UIViewController. This allows you to break up your app’s controller logic into manageable classes with clear responsibilities while still following the limitations of UIViewController. This works well when you want to have different controllers manage different sections of a single view hierarchy.


@interface SampleController : NSObject {
}
@end


This is however an inadequate replacement for custom container view controllers which should be able to manage transitions between arbitrary UIViewControllers. Instead we have to either reinvent much of UIViewController’s behavior (-viewWillAppear: and -viewDidDisappear: style lifecycle methods, unloading and reloading of views on demand, transformation of views in response to device rotations) or abuse UIViewController and risk producing unstable apps.


@protocol ViewController
- (void)viewDidAppear:(BOOL)animated;
- (void)viewDidDisappear:(BOOL)animated;
- (void)viewWillAppear:(BOOL)animated;
- (void)viewWillDisappear:(BOOL)animated;
-(UIView *)view;
@end

@interface SampleContainerViewController : UIViewController {
}
- (void)setViewControllers:(NSArray *)viewControllers animated:(BOOL)animated;
@property(nonatomic, copy) NSArray *viewControllers;
@end


For now I have found that the best solution is to stay within the supported constraints of UIViewController and build custom non-UIViewController controllers as necessary. Have you found a better alternative, chosen to use UIViewControllers anyway, or avoided this problem entirely?

The fallacies of distributed computing

1. The network is reliable.
2. Latency is zero.
3. Bandwidth is infinite.
4. The network is secure.
5. Topology doesn’t change.
6. There is one administrator.
7. Transport cost is zero.
8. The network is homogeneous.

Fallacy #7: “transport cost is zero”.

Arnon Rotem-Gal-Oz’s explanation of this fallacy points out two possible interpretations, both of which can be problematic mistakes.

First you can consider the cost of moving data between your application and the network interface. The performance impact of serializing objects or parsing data add a cost above and beyond the limitations of bandwidth and latency. Apple’s 2010 WWDC session 117 “building a server-driven user experience” for their comparison of the size and load time of data in xml, json, and plists (slide #40 & 41 at ~27:30). While the size of each format was similar the time required to parse the result varied tremendously; 812ms for xml, 416ms for json, 140ms for an ascii plist and only 19ms for a binary plist.

Secondly you can consider the cost of maintaining network services and infrastructure. How much load does each user place on your servers and what do they cost to run? How many concurrent requests can your servers actually handle and what does it cost to scale those systems? What does using your app cost your users who live with monthly data limits or pay on a per-kilobyte basis?

The fallacies of distributed computing

1. The network is reliable.
2. Latency is zero.
3. Bandwidth is infinite.
4. The network is secure.
5. Topology doesn’t change.
6. There is one administrator.
7. Transport cost is zero.
8. The network is homogeneous.

Fallacy #5: “topology doesn’t change”.

WWAN connections use significantly more power than WiFi connections. This becomes important when working with long lived connections or streaming media. A connection established over the WWAN will keep that interface active even if a WiFi network becomes available. To avoid running both interfaces it is up to the app to close and re-establish any active connections on the newly available network interface. Use Apple’s Reachability example to monitor changes in available interfaces and react as necessary. Also take a look at Paul Danbold’s “Advanced networking” talk from the 2009 Tech Talk World Tour.

Those changes to the network are also likely to result in changes to the device’s available bandwidth and latency so apps which make decisions based on those characteristics may need to monitor their connections and adapt to changing conditions. Since apps which stream significant amounts of audio or video are required to use http live streaming they can automatically switch between available streams designed for higher or lower bandwidth connections as network conditions change.