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“.

I have been able to run test suites from the command line but only for “logic” tests. From the iOS Development Guide:

Xcode offers two types of unit tests: logic tests and application tests.

Logic tests.
These tests check the correct functionality of your code in a clean-room environment; that is, your code is not run inside an application. Logic tests let you put together very specific test cases to exercise your code at a very granular level (a single method in class) or as part of a workflow (several methods in one or more classes). You can use logic tests to perform stress-testing of your code to ensure that it behaves correctly in extreme situations that are unlikely in a running application. These tests help you produce robust code that works correctly when used in ways that you did not anticipate. Logic tests are iOS Simulator SDK–based; however, the application is not run in iOS Simulator: The code being tested is run during the corresponding target’s build phase.

Application tests.
These tests check the functionality of your code in a running application. You can use application tests to ensure that the connections of your user-interface controls (outlets and actions) remain in place, and that your controls and controller objects work correctly with your object model as you work on your application. Because application tests run only on a device, you can also use these tests to perform hardware testing, such as getting the location of the device.

I am able to create a set of logic tests as a separate build target and scheme which will successfully run as part of an xcodebuild build.

1. Create a new “LogicTests” unit test build target.
2. Leave the “Test Host” build setting blank.
3. Set the “Test After Build” build setting to “No”.
4. Do not write tests which require an application to be present (ie no window or application delegate available).
5. Create a new “LogicTests” scheme which includes the “LogicTests” build target in its run action.
6. Run the “LogicTests” scheme using xcodebuild.

Scheme for running logic tests

> /Developer_Xcode4/usr/bin/xcodebuild -workspace WrappingScrollView.xcworkspace -scheme logictests -sdk iphonesimulator4.3 -configuration Debug clean build

…

Run test suite logictests
Test Suite ‘logictests’ started at 2011-04-06 07:44:57 +0000
Run test case testExample
Test Case ‘-[logictests testExample]‘ started.
/Users/Jonah/Desktop/WrappingScrollView/WrappingScrollViewDemo/logictests/logictests.m:30: error: -[logictests testExample] : Unit tests are not implemented yet in logictests
Test Case ‘-[logictests testExample]‘ failed (0.000 seconds).

Test Suite ‘logictests’ finished at 2011-04-06 07:44:57 +0000.
Executed 1 test, with 1 failure (0 unexpected) in 0.000 (0.000) seconds

That’s not a great solution but it at least allows me to run some tests on a continuous integration server. Hopefully I can find a way to run application tests through xcodebuild as well.

In case it is of any help to other developers struggling with the difference between command line and Xcode builds. The “Run Script” build phase of a unit test build target just runs “${SYSTEM_DEVELOPER_DIR}/Tools/RunUnitTests”. The RunUnitTests script in turn invokes a platform specific script like “${SYSTEM_DEVELOPER_DIR}/Platforms/iPhoneSimulator.platform/Developer/Tools/RunPlatformUnitTests” which ultimately calls RunTestsForBundle in “${SYSTEM_DEVELOPER_DIR}/Tools/RunPlatformUnitTests.include”. Hopefully it will prove possible to use these scripts to match the behavior seen when running tests from within Xcode to automatically run application tests.

> /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.

Thankfully Tony Arnold demonstrated one possible solution with his Xcode 4 Uncrustify Automator Services. Here’s how you can get your external code formatting tool up and running again with Xcode 4.

Install Uncrustify (port install uncrustify, brew install uncrustify, or directly from http://uncrustify.sourceforge.net/)

Open Automator and create a new Service.

Creating a new Automator Service

Inputs to Automator Services are more limited than the options available in Xcode 3′s User Scripts. To reformat selected text we can still pass the input from Xcode to a Run Shell Script action.

uncrustify -l OC -q -c ~/.uncrustify/uncrustify_obj_c.cfg

Uncrustify Selected Text

To reformat open files we need to use AppleScript to get the paths to those files so that we can pass them to Uncrustify. I wasn’t able to find a reliable way to select only the currently visible source file so I settled on the following script to reformat all open and modified source files instead.

tell application id "com.apple.dt.Xcode"
	repeat with current_document in (source documents whose modified is true)
		set current_document_path to path of current_document
		set raw_source to text of current_document
		set formatted_source to do shell script "uncrustify -l OC -q -c ~/.uncrustify/uncrustify_obj_c.cfg -f " & current_document_path
		set text of current_document to formatted_source
	end repeat
end tell

Uncrustify Modified Documents

Open Xcode, find the new Services available in the “Xcode” menu. Use the Services Preferences to bind these Services to keyboard shortcuts to your liking.

Services available in Xcode

Enjoy cleaner code.

Running unit tests with GTM
I have been using GTM to run iPhone unit tests as part of the build process for a “Unit Tests” build target (see Alon’s post on our iPhone Unit Testing Toolkit). Running these tests with a TeamCity build agent just requires a command line build runner which calls the `xcodebuild` command and specifies the project, built target, and configuration to build.

Ad-hoc builds
Ad-hoc builds run with a similar command:

Now my ad-hoc builds are produced automatically, always up to date with my working code changes, and available as an easy download from my TeamCity server. TeamCity will also save the artifacts for each build so I can easily retrieve the dSYM for a particular ad-hoc build to symbolicate a crashlog for that build on any developer’s machine.

Future improvements
If necessary I can run tests on actual iPhone hardware by changing the sdk (`-sdk iphoneos4.0`) but I am not yet sure how I could specify which one of multiple devices would run the tests. It would be nice to eventually be able to choose between multiple devices so I can deliberately run some tests on a device with a specific OS version or feature set.
With my current configuration TeamCity can only report a pass/fail status for iPhone tests. I need to consider modifying the GTM test runner script or switching to GHUnit or Cedar to get per-test results and then be able to build up a history of individual test failures.
I also need to add a build configuration which uses agvtool to automatically increment the project’s build number as part of every ad-hoc build.

I created an “Environments” resource group in Xcode and added a copy of my project’s “Resource/Info.plist” file for each environment.

A plist for each environment.

These plists should not be members of any build target (just like the original Info.plist.

Info.plist files should not be members of a build target.

In each build target’s settings I then set the “Info.plist File” to the plist I created for that target’s environment. Note that the path to this file is the actual path on disk relative to the project root; if you have an ‘Environments’ group in the project but no actual ‘Environments’ directory in your project then this path would be incorrect.

Specifying the plist for a build target.

In code I can then access the plist’s dictionary via the application bundle:

[[NSBundle mainBundle] infoDictionary]

Now I can define the domain name of an API I will be using in each plist and automatically connect to localhost when running tests, to a staging server when using a development build, and to the production server when building a release or adhoc build. Each environment has it’s own build target so I can also specify a different app product identifier for each target and install the different app versions side by side on the same device.

I setup a set of styling rules using UniversalIndentGUI’s live preview and saved the resulting config file. I was then able to add a set of custom user scripts in Xcode to run Uncrustify against the current file or selection. I found that I had to specify the source as objective-c to prevent Uncrustify form running some C/C++ styling rules which I did not want.

Uncrustify custom scripts in Xcode

#!/bin/sh

~/Applications/UniversalIndentGUI/indenters/uncrustify -l OC -q -c ~/Applications/UniversalIndentGUI/config/uncrustify_obj_c.cfg

Now I can quickly clean up most of the minor formatting inconsistencies which creep into my code. Now I just need to polish my config file until it better matches my expectations for code formatting. In defining my preferred code style I have tried to follow the example provided by:

• Coding Guidelines for Cocoa
• Google Objective-C Style Guide
• Cocoa Style for Objective-C

My current config file for Uncrustify is available here: uncrustify_obj_c.cfg if you would like to use it as a starting point.

My config file is now also available as a gist: https://gist.github.com/841452 for anyone who would like to suggest improvements or create their own fork.