If you are writing an iPhone GameKit app without using GKPeerPickerController (as I did in PhotoBeamer), you need to detect when Bluetooth is disabled and ask the user to turn it on in the settings app. Apple doesn’t provide a way for a developer to enable Bluetooth other than through GKPeerPickerController.

This is pretty easy to do. First, create your GKSession and set it to be available:

    session = [[GKSession alloc] initWithSessionID:kMyAppSessionID
                                       displayName:nil
                                       sessionMode:GKSessionModeClient];
    session.delegate = self;
    [session setDataReceiveHandler:self withContext:nil];
    session.available = YES;

Next, set up your - (void)session:(GKSession *)session didFailWithError:(NSError *)error delegate method to detect when Bluetooth is not available and alert the user:

// GKSessionErrorDomain causes link error (rdar://problem/7014349)
#if 0
#define kGKSessionErrorDomain GKSessionErrorDomain
#else
#define kGKSessionErrorDomain @"com.apple.gamekit.GKSessionErrorDomain"
#endif
 
- (void)session:(GKSession *)session didFailWithError:(NSError *)error {
    if ([[error domain] isEqual:kGKSessionErrorDomain] &&
        ([error code] == GKSessionCannotEnableError))
    {
        // Bluetooth disabled, prompt the user to turn it on
    } else {
        // Some other error, get the description from the NSError object
    }
 
    // destroy the GKSession and clean up
}

The GKSessionErrorDomain symbol causes a link error for me, so I’m temporarily using the constant string instead. When Apple fixes the SDK, I’ll change that #if 0 to use the official symbolic name.

Note that this error will sometimes occur on a reconnection attempt even when Bluetooth is enabled, presumably because the old session is still partially active.

It would be nice to have a more user-friendly way to turn on Bluetooth without leaving the app and without using the full GKPeerPickerController UI. I’ve filed a bug report (rdar://problem/7061502) asking for this functionality. You should file one too.

Additionally, in any build that leaves the developer’s desk it is especially important to include version information so that bug reports can be traced back to the correct version of the source, and to ensure that any distributed version can be located in the version control system. I use git for source control (installed with MacPorts), though the script should be easily adaptible to CVS or SVN.

The goals for this script were:

• Automatically tag the project with a unique build number before each build.
• Build all supported configurations with a single command. Sometimes compiler errors or warnings are only revealed with certain preprocessor flags or optimization settings.
• Ensure any build created for distribution is cleanly committed to version control and tagged.
• Name tags so that they can be easily correlated to user-visible version information.

Preliminaries

Before we get into the script, a bit of groundwork is needed in the XCode project.

Build Configurations

By default, XCode includes two configurations in a new project: Debug and Release. I add a third configuration, Distribution, created by copying the Release configuration, but signed with my distributions certificate instead of the development certificate. This allows me to test using the same build settings that will be used for the submitted app.

I also set a couple of preprocessor flags based on the build configuration. The Debug configuration sets DEVELOPMENT_BUILD=1 and DEBUG_BUILD=1, while the Release build just sets DEVELOPMENT_BUILD=1. These flags are used for several purposes, including conditional logging, but in the context of this article they are used just for version string generation.

The versioning tool discussed in the next session also requires a build variable. Search for the CURRENT_PROJECT_VERSION key and set its value to 1.

Apple’s Versioning Tool

First, we need to take a little side trip into Apple’s built-in versioning support. XCode includes agvtool, which with a bit of setup can be used to satisfy our versioning requirements. The first step is to separate the “marketing version” from the build version. Both components are stored in the Info.plist file, though a new XCode project only includes the build version key.

I set the marketing version to the version I plan to specify in iTunesConnect when the app is submitted. The build version is simply set to 1 initially and incremented with each build thereafter (this should match the CURRENT_PROJECT_VERSION build variable).

Displaying the Version

In the About view controller’s viewDidLoad method I include the following:

- (void)viewDidLoad {
   NSString *versionString = [NSString stringWithFormat:
                        NSLocalizedString(@"Version: %@%@ (%@)", @"Version string format"),
                        [[NSBundle mainBundle] objectForInfoDictionaryKey:@"CFBundleShortVersionString"],
#if DEBUG_BUILD
                        @" Debug",
#elif DEVELOPMENT_BUILD
                        @" Beta",
#else
                        @"",
#endif
                        [[NSBundle mainBundle] objectForInfoDictionaryKey:(NSString*)kCFBundleVersionKey]];
   [versionLabel setText:versionString];
   // Additional initialization
}

This provides enough information to determine the build and configuration from any copy of the app. Actually, the marketing version isn’t even needed, but it allows the user to compare with the information in iTunes.

The remainder of this article breaks down the script, section by section. You can download the script (updated July 14, 2009) and use or adapt it to your own projects. The script is under a BSD license.

The description below details the 1.0 version of the script.

Helper Functions

The first section of the script defines a few helper functions.

The die function simply prints its arguments to stderr and exits.

die() {
	echo "$*" >&2
	exit 1
}

The usage function prints its args (if any) followed by a usage message and exits.

usage() {
	if [ -n "$1" ] ; then
		echo "$@" >&2
		printf "\n"
	fi
	echo "usage: build [-n] [config...]" >&2
	echo "    -n : do not update build number or commit to git">&2
	if [ -n "$xcodeconfigs" ] ; then
		printf "\n    Known configs:" >&2
		printf " %s" $xcodeconfigs >&2
		printf "\n\nDefault action is to build all configs\n" >&2
	else
		echo "This does not appear to be a valid project directory!" >&2
	fi
	exit 3
}

The usage message is:

usage: build [-n] [config...]
    -n : do not update build number or commit to git

    Known configs: Debug Release Distribute

Default action is to build all configs

Defaults and Known Configurations

By default, the script will run agvtool and the git operations, and build all configs in the project.

nocommit=0
configs=

The list of known configurations is determined by filtering the output of xcodebuild -list with sed:

# all known configurations
xcodeconfigs=$(xcodebuild -list | sed '
		/Build Configurations:/,/^[[:space:]]*$/	!d
		/Build Configurations/				d
		/^[[:space:]]*$/				d
		s/[[:space:]]*\([^[:space:]]*\).*/\1/
	')

The output of xcodebuild -list looks like:

$ xcodebuild -list
Information about project "SpinSlide":
    Targets:
        SpinSlide (Active)

    Build Configurations:
        Debug (Active)
        Release
        Distribute

    If no build configuration is specified "Release" is used.

The four-line sed script first deletes all lines except those between Build Configurations: and the first blank line. The second and third lines delete the Bould Configurations line and the blank line, respectively. Finally, each line is replaced by just the first word on that line.

Next the script checks for an empty list of configurations, which can occur if there is no project bundle in the current directory.

if [ -z "$xcodeconfigs" ] ; then
	# no project bundle?
	usage;
fi

Argument Processing

Command line arguments are processed in a loop. The only supported flag is ‘-n‘, which suppresses avgtool and git operations. All non-flag arguments are assumed to be build configuration names, and are checked against the list of known configurations generated in the last section before being added to the list of configurations to build.

while [ -n "$*" ]; do
	case "$1" in
		-n) nocommit=1 ; shift ;;
		-*) usage ;;
		*)	if echo $xcodeconfigs | grep -wq "$1" ; then
				configs="$configs $1"; shift
			else
				usage "Invalid config '$1'"
			fi
			;;
	esac
done

If no configurations were specified on the command line, all known configurations are built.

# default to building all configs
if [ -z "$configs" ] ; then
	configs=$xcodeconfigs
fi

Check for Modified Files

The next step is to check for modified files. If modified files exist and -n was not specified, the script will exit with an error. If -n was specified the script continues after setting the isdirty flag.

if ! git status | grep -q 'nothing to commit (working directory clean)' ; then
	if [ "$nocommit" -eq "0" ] ; then
		# if committing the directory must be clean at first
		git status
		die "directory is dirty"
	else
		# development build, just remember that it was dirty
		isdirty=1
	fi
else
	isdirty=0
fi

This step is git-specific, and must be adapted if you are using a different VCS.

Versioning

The next step handles all of the versioning and source control operations.

The steps required depend on the command line options used.

Tagged Builds

First, we handle the case where the -n flag was not specified. The first step is to use agvtool to determine the marketing version. This will not be changed when the build number is incremented. Checking the marketing version first lets us verify that the project is set up properly before making changes.

if [ "$nocommit" -eq "0" ] ; then
	# read out the marketing version
	# do this separate from the cut so we can check the exit code
	mvers=$(agvtool mvers -terse)
	if [ $? -ne 0 -o -z "$mvers" ] ; then
		die "No marketing version found"
	fi
 
	if echo "$mvers" | grep -q = ; then
		mvers=$(echo "$mvers" | cut -f 2 -d =)
	fi

The output of agvtool looks like:

"SpinSlide.xcodeproj/../Info.plist"=1.0

The cut command is used to extract the field after the = sign.

After this point, the environment has been fully verified, so we can go ahead and increment the build version.

	# going to commit, bump the version number
	agvtool bump -all

Now we extract the (newly incremented) build version…

	bvers=$(agvtool vers -terse)
	if [ $? -ne 0 -o -z "$bvers" ] ; then
		die "No build version found"
	fi

… and combine the marketing version and build numbers into a human-readable string and a tag identifier, which has the spaces replace by underscores.

	# read out the build version, must exist if the marketing version does
	fullvers="$mvers build $bvers"
	tag=$(echo "$fullvers" | tr ' ' _)

Finally, we commit the changed .plist and tag the new version.

	# commit the changed version and tag it
	echo "Committing "$fullvers" with tag $tag"
	git ci -a -m "Set build version '$fullvers'" -n || die 'commit failed'
	git tag "$tag" -m "$fullvers"

Untagged Builds

Untagged builds are much simpler. The SHA1 of the current version is used as the tag. If the source directory is dirty, the current date and time is added to make a unique identifier.

else
	# not committing, use the SHA1 as the version
	fullvers=$(git rev-parse HEAD 2>/dev/null)
 
	# if it's dirty, append the date, time, and timezone
	if [ "$isdirty" -ne 0 ] ; then
		fullvers="$fullvers+ $(date +%F\ %T\ %Z)"
	fi
fi

Build Prep

To ensure the build matches the source, we delete the build directory and the Payload directory (the former is used by XCode, the latter by this script).

# clean up old builds so that everything is built from scratch
rm -rf build
rm -rf Payload
all=

Build and Package

Next we loop over the requested configurations, building and packaging each one.

# build and package each requested config
for config in $configs ; do

The build is performed with the xcodebuild utility, supplied with XCode. A failed build stops the script.

	xcodebuild -alltargets -parallelizeTargets -configuration $config build || die "Build failed"

Build output is stored in a tree named for the build type (tagged or untagged), version, and XCode build configuration:

	# packaged output goes in Releases if tagged, Development otherwise
	if [ "$nocommit" -eq "0" ] ; then
		basedir=Releases
	else
		basedir=Development
	fi
	releasedir=$basedir/$config/"$fullvers"
	mkdir -p "$releasedir"

Each build target is then packaged, one at a time.

	# Package each app
	for app in build/$config-iphoneos/*.app ; do
		basename="$(basename "$app" .app)"

The application bundle is copied into a directory called Payload/Payload. The first directory name isn’t significant, but the second is important to make a working .ipa file.

		mkdir -p Payload/Payload
		cp -Rp "$app" Payload/Payload

To have an icon in iTunes, the package must include a 512×512 PNG or JPEG named iTunesArtwork at the root. The following code supports per-project default artwork as well as app-specific artwork (if there are multiple apps in a single project).

		# Get app-specific iTunes artwork or project-specific artwork
		# if available
		if [ -f "$basename".iTunesArtwork ] ; then
			cp -f "$basename".iTunesArtwork Payload/iTunesArtwork
		elif [ -f iTunesArtwork ] ; then
			cp -f iTunesArtwork Payload/iTunesArtwork
		fi

A .ipa file is just a .zip file with a particular content format. When building for distribution through the AppStore, the .zip extension is required. Otherwise the .ipa extension is used.

		# Distribution builds have a .zip extension, development
		# builds have a .ipa extension
		if [ "$config" -eq "Distribute" ] ; then
			ext=zip
		else
			ext=ipa
		fi

Next we use ditto to zip the contents, then delete the temp directory.

		# zip the Payload directory then delete it
		output="$releasedir/$basename.$ext"
		ditto -c -k Payload "$output" || die "Failed to compress"
		rm -rf Payload

We remember the name of the generated file to display at the end of the script.

		# add to the list of output files
		all="${all:+$(printf "%s\n" "$all")}$(printf "\t%s" "$output")"

XCode supports splitting the debug symbols from the app. If this option is enabled (as it should be for Release and Distribution builds) we save the debug symbols with the app:

		# save debug symbols (if available) with the app
		if [ -d "$app.dSYM" ] ; then
			output="$releasedir/$basename.dSYM.zip"
			ditto -c -k "$app.dSYM" "$output" || die "Failed to compress debug info"
			all="$(printf "%s\n" "$all")$(printf "\t%s" "$output")"
		fi

Finally, we update a symlink to point to the latest version.

		# update a symlink to the latest version
		(cd $basedir/$config ; ln -sf "$fullvers/$basename.$ext")
	done
done

Report Results

Once all the builds have completed and been packaged, a build summary is displayed to the user.

# report the generated files
printf "Created: $all\n"

Registration

Registration is simple, although the menu item is hidden in the Help menu instead of being in the Application menu (which doesn’t actually exist). Once you’ve entered the registered name and serial number, the app is fully activated. Registration is per-user, not per-machine, so you can install it on your desktop, laptop, home desktop, etc. Registration includes free perpetual updates.

Reinventing the… uh… clock

When you launch Mockups, you are presented with a new mockup window, ready for your design. Across the top are a number of controls you can add to the Mockup. These controls are broken down into a number of categories. Since I write iPhone apps for a living, we’ll select the iPhone category to get started, then set about creating a workflow for the built-in clock app.

First, drag a iPhone object into the mockup to act as a container for our views. Bring up the properties window (it’s greyed out until you point at it) and select the middle background pattern, which shows a Nav Bar at the top and a Tab Bar at the bottom. Then click in the “Quick Add” box and start typing “Icon”. Select the “Icon and Text Label” and type in “World Clock”. Click on “Icon search” and type in “Circle”, then select the “Dot, Little Black Circle” icon. Change the font size to 9 and icon size to Small to make it fit better, and drag it over the tab bar area on the phone. In a similar way, we can quickly make the Alarm, Stopwatch, and Timer buttons and place them in their approximate locations. Select all 4 icons and Align Bottom, then Distribute Centers Horizontally and Group them. We’ll save this as “iPhone Clock App World Clock”.

Next we clone the mockup (??N) three times and save the clones as “iPhone Clock App Alarm”, “iPhone Clock App Stopwatch”, and “iPhone Clock App Timer”. Later we can link the icon buttons to the different views, but for now we’ll continue creating the World Clock view. In a few moments we can add an Edit button and a + button and use a Label to finish the Nav Bar.

Next we complete the content view. Simple add a Rectangle/Canvas to the content area, an icon for the clock, and a few Labels for the City, Time, AM/PM and Day, adjusting the fonts appropriately (remember, the goal is an approximate representation of the final app). Duplicate the row we just created a few times to fill out the content area.

In-App Navigation

The last step on this view is to fill out the links. Just select each control and choose the desired mockup from the Link dropdown. A small blue arrow will appear on the control. If you switch to View->Full Screen Presentation (?F) you can click on these linked buttons to navigate around the mockup.

We can use the included iPhone Picker control to quickly mockup the Timer screen as well. The buttons in the middle are made from Canvases and Labels to allow customizing the text layout and colors, much as we’d have to do in Interface Builder or programmatically if we were to build this app for real. It would be nice if Mockups let you change button colors. Maybe that feature will be added soon.

Full Screen Presentation

We can go on like this adding additional mockups until we’ve covered all the screens in the app. Along the way we can share the files with the rest of the team to get feedback much more quickly than if we were writing code for all of this. If you are in the same office as the rest of your team or use some sort of web collaboration software, you can use the Full Screen Presentation mode to click through the various screens in the app, using the ridiculously large pointer (and I mean that in a nice way) to point out parts of the interface as you discuss it.

Conclusions

Mockups is extremely easy to use. I wrote this review as I was learning the app for the first time. The hand-drawn images really do have the intended “lo-fi” effect, encouraging you to stay focused on the big picture instead of spending hours tweaking individual pixels. Mockups will definitely become part of the AppMobi design process. It will be a big help as we move ahead with development of our more sophisticated productivity apps.

Some of my favorites:

On C:

“1972 - Dennis Ritchie invents a powerful gun that shoots both forward and backward simultaneously. Not satisfied with the number of deaths and permanent maimings from that invention he invents C and Unix.”
~ James Iry A Brief, Incomplete, and Mostly Wrong History of Programming Languages

On Objective-C:

“1986 - Brad Cox and Tom Love create Objective-C, announcing "this language has all the memory safety of C combined with all the blazing speed of Smalltalk." Modern historians suspect the two were dyslexic.”
~ James Iry A Brief, Incomplete, and Mostly Wrong History of Programming Languages

On LiveScript/JavaScript/ECMAScript:

“1995 - Brendan Eich reads up on every mistake ever made in designing a programming language, invents a few more, and creates... JavaScript”
~ James Iry A Brief, Incomplete, and Mostly Wrong History of Programming Languages

Visit his blog to read more.

Go to the Arguments tab and add the following entries into the “Variables to be set in the environment” box:

• NSAutoreleaseFreedObjectCheckEnabled
• NSDebugEnabled
• NSZombieEnabled

Set the value for all each to YES.

Your settings should now look like:

You may also want to set NSHangOnUncaughtException=YES. Additional useful debugging tips can be found in this thread.

Edit: CocoaDev has additional NSZombieEnabled tips, and notes that you may not want to leave this enabled all the time, especially if your application churns through a lot of objects, as the memory never gets freed. The fact that your code is running on a desktop or laptop system instead of the phone helps a lot here, so this is probably a lot less of a concern than for a desktop application. They also provide instructions for setting these flags in your .gdbinit using:

set env NSAutoreleaseFreedObjectCheckEnabled=YES
set env NSDebugEnabled=YES
set env NSZombieEnabled=YES

find /export -type f -print | perl -ne 'chomp; $count++; $total += (stat())[7]; END { print "$count files $total bytes total ", $total/$count, " byte average\n"; }

After running this, I was surprised at just how large the “average” size was, which led me to wonder just which average they were looking for here: mean or median? While I was at it, I decided to calculate the mode as well.

The one-liner evolved to:

find /export -type f -print | perl -ne 'chomp; $count++; $size = (stat())[7]; push @sizes, $size; $total += $size; $sizes{int(($size+511)/512)}++; print "$count\r" if ($count % 2048 == 0); END { $median = (sort @sizes)[$#sizes / 2]; $mode = 512 * (sort { $sizes{$b} <=> $sizes{$a} } keys %sizes)[0]; print "$count files $total bytes total ", $total/$count, " byte mean $median byte median $mode byte mode\n"; } BEGIN { $| = 1; }'


We can make this a bit more legible:

find /export -type f -print | perl -ne '\
      chomp; \
      $count++; \
      $size = (stat())[7]; \
      push @sizes, $size; \
      $total += $size; \
      $sizes{int(($size+511)/512)}++; \
      print "$count\r" if ($count % 2048 == 0); \
BEGIN { $| = 1; } \
END { $median = (sort @sizes)[$#sizes / 2]; \
      $mode = 512 * (sort { $sizes{$b} <=> $sizes{$a} } keys %sizes)[0]; \
      print "$count files $total bytes total ", $total/$count, \
            " byte mean $median byte median $mode byte mode\n"; }'

Let’s take it line by line. First, the shell pipeline find /export -type f -print | perl -ne 'stuff' recursively descends into the /export directory and prints the names of all regular files found, one per line. This output is piped into Perl, which processes the commands in the -e 'stuff' block once per line due to the -n flag.

The heavy lifting is done in the Perl program:

Gathering the Information

chomp; strips the trailing newline from the input line.

$count++; counts the number of lines.

$size = (stat())[7]; gets the size in bytes of the input file.

push @sizes, $size; saves the size in a list of all file sizes seen.

$total += $size; adds up the total number of bytes seen.

$sizes{int(($size+511)/512)}++; converts the size in bytes into a size in 512-byte blocks, and counts the number of files with a given block count. This creates a histogram of file sizes using 512-byte bins.

Showing Progress

print "$count\r" if ($count % 2048 == 0); prints a progress indication for every 512 files processed.

BEGIN { $| = 1; } is a BEGIN block, which means it is executed once at the beginning of the program. It sets the perl built-in variable $| to a true value, so that output is displayed immediately. With out this, the progress indication would not print until it had been output hundreds of times.

Calculating Results

Results a reported in the END {} block, which, as you may guess, is executed once at the end of the program. It starts with a few calculations:

$median = (sort @sizes)[$#sizes / 2]; sorts the list of sizes seen (sort @sizes), the selects the middle item from the sorted list ($#sizes is the index of the last element in the list, we use half of that as the index to get the middle element).

$mode = 512 * (sort { $sizes{$b} <=> $sizes{$a} } keys %sizes)[0]; calculates the mode (the most frequently-occurring item). Working from the inside out, keys %sizes gets a list of the keys from the %sizes hash. Then sort { $sizes{$b} <=> $sizes{$a} } keys %sizes sorts those keys by hash value in descending order, so that the most-frequently occurring element comes first. The first element is accessed at index 0, then multiplied by 512 to convert back to bytes.

Sorting The Data: The sort is done by passing a custom comparison routine { $sizes{$b} <=> $sizes{$a} } to the built-in sort function.

Perl’s sort will call this routine repeatedly with pairs of list elements in $a and $b. The routine should return 0 if the elements are equal, less than 0 if $a should come first, or greater than 0 if $b should come first.

The default comparison is $a <=> $b, which is a lexical sort. Since out data is numeric, we could use the equivalent $a <=> $b, which in this case would sort the list in ascending order by size. Reversing the comparison to $b <=> $a sorts in descending order by size. Finally, using the hash values rather than the keys sorts by frequency of occurrence.

Output Results

Now it’s a simple matter of displaying the results:

print "$count files $total bytes total ", $total/$count, " byte mean $median byte median $mode byte mode\n"; }'