1. Navigate to a .app file in the Finder, e.g. /Applications/Mail.app
2. Control-click the app icon and select “Show Package Contents”
3. Navigate to Contents/Info.plist
4. Open with a plist editor or your favorite text editor.

These files advertise a number of interesting attributes including the application’s official version and copyright strings. They also include important clues to the system about what kinds of files the application knows how to read and write, and what its minimum system requirements are.

Minimum System Requirements

Declaring the right Info.plist values not only allows a developer to control which operating systems a product should run on, but which of the application’s architectures should be considered for a particular operating system. For example, Black Ink uses a number of keyed values describing its requirements:

	<key>LSArchitecturePriority</key>
	<array>
		<string>x86_64</string>
		<string>i386</string>
		<string>ppc</string>
	</array>
	<key>LSMinimumSystemVersion</key>
	<string>10.4.0</string>
	<key>LSMinimumSystemVersionByArchitecture</key>
	<dict>
		<key>i386</key>
		<string>10.4.0</string>
		<key>x86_64</key>
		<string>10.6.0</string>
		<key>ppc</key>
		<string>10.4.0</string>
	</dict>

Notice the fidelity of some of these options. Black Ink is an application that is compiled with binary code for three separate architectures embedded into it: 64-bit Intel, 32-bit Intel, and 32-bit PowerPC. In order to give the user the best possible experience after they double-click the application icon, the system consults the Info.plist values to determine which binary is most appropriate to load on the current system.

The options for Black Ink start by indicating that all things being equal, it prefers to run as 64-bit Intel, but will settle for 32-bit Intel or PowerPC in a pinch. Next, it conveys that it should not be run on any operating system earlier than Mac OS X 10.4. Finally, it adds an additional restriction by architecture, stating that in the case of 64-bit Intel, the system should consider Mac OS X 10.6 the minimum required OS.

Why so picky? For example, Mac OS X 10.5 will run on computers that are new enough to support 64-bit Intel code, but the 10.5 operating environment itself doesn’t contain enough compatible libraries to make it very useful to a full-featured Cocoa application. So we need to convince the 10.5 system to ignore our 64-bit Intel code. And this is how it’s done.

Embedding Info.plist

This is all well and good for applications, but what about other code that may be run on a variety of hardware and operating systems? In particular, command-line tools do not come in the same bundled-folder format that applications do. Fortunately, Apple thought of this when they implemented support in their developer tools for embedding the contents of an Info.plist directly into the binary itself. You just have to pass the Info.plist path to Apple’s linker tool when it’s constructing your binary file. (Thanks to Paul Kim for reminding me of this functionality). What this means in practice is adding arguments like this to your Xcode target’s “Other Linker Flags” build setting:

-sectcreate __TEXT __info_plist $(INFOPLIST_FILE)

This instructs the linker to crete a new text segment named “__info_plist” in the resulting binary, and to fill it with the contents of the referenced Info.plist file. To make sure the INFOPLIST_FILE expands correctly, just make sure you set it in the separate build setting for identifying the Info.plist (the one you’d normally use in an app, and that is just ignored by default for a command-line tool target).

I brushed up on all this information because I wanted to help ensure that some recent work I did to create a standalone MultiMarkdown tool would be backward compatible with older systems. This required adding an embedded plist much as I’m describing here.

(Note: I have gotten some feedback to the effect that the __info_plist segment’s minimum system version requirements may not actually be consulted properly on Mac OS X 10.5. This would be a bummer, and in fact sort of reject the whole point of embedding the Info.plist in this case. I’m going to see if I can confirm whether it doesn’t in fact work.)

You could technically embed all kinds of stuff in the binary, with different section names. But the contract in this case is that when Mac OS X is determining information about an executable, it will consult the bundle’s Info.plist file, if it happens to be an executable in a bundle, or the binary’s __info_plist segment, if it happens to have one.

Another common reason for needing to embed Info.plist information into a standalone binary is if you are using Apple’s code signing mechanism to sign an individual binary tool. Code signing uses information from the Info.plist of a product, and in the case of standalone binaries, the only product-cohesive place to put this is in the binary itself.

Examining Binary Info.plists

After you’ve performed the magic above, you’ll probably be keen to inspect your command-line tool’s Info.plist to see if it worked. To do this, you can use the otool command from the Finder. If you run otool with the “-l” option to show all load commands, it will include the load command that identifies the __info_plist segment. Use grep to narrow it down to the part you’re interested in:

otool -l ./yourTool | grep info_plist -B1 -A10

Any results at will confirm that there is Info.plist information in the binary, but how does it look? The “-s” option to otool lets you examine the contents of a specific segment in a binary, but it dumps it out as hex code. Fortunately, another system-bundled tool called “xxd” is capable of easily converting between hex-dump and text formats. As it turns out, some of Apple’s bundled developer tools (at least on my Mac) contain these embedded __info_plist sections, so if you don’t have a command line tool of your own to try this on, you can peek at what the “atos” tool has to say for itself:

otool -s __TEXT __info_plist /usr/bin/atos | xxd -r

In Summary

Info.plist values are important for conveying information about your product, from the crudest, most obvious stuff like version number, to the most nuanced details such as which architectures are supported. Knowing how to specify an application or tool’s requirements as precisely as possible will ensure that the product performs optimally on whatever supported system your user happens to be using. I’ve barely scratched the surface here with a few common deployment keys that control execution behavior on Mac OS X. Be sure to skim Apple’s Information Property List Key Reference to see if there are other useful bits of information you can share for your application or for your command-line tool.

Unfortunately, this seemingly minor update presented a major failure in my debug builds, which I’m adventurously compiling using the LLVM clang compiler. They built fine with Xcode 3.2.2, but starting in 3.2.3, I got a linkage failure, tracing back to the popular open source RegExKitLite:

Undefined symbols:
  "___gxx_personality_v0", referenced from:
      _rkl_debugCacheSpinLock in RegexKitLite.o
      ...
  "__ZSt9terminatev", referenced from:
      +[NSString(RegexKitLiteAdditions) clearStringCache]
      in RegexKitLite.o

What? Those symbols smack of C++, but there isn’t any C++ code in my project. At least, I don’t think there is. RegExKitLite is so famously advanced in its designed, I couldn’t easily tell you whether there was stuff in there intended as C++ or not. On a whim, I tried to switch the file type to C++ to see if that made clang any happier. No, it screamed bloody murder. It agrees with me, RegExKitLite is not C++ code.

So why the link errors? I examined the compile line carefully for RegExKitLite and confirmed that it’s using clang in a manner that should only be generating plain C linkage:

/Developer/usr/bin/clang -x objective-c -arch x86_64 ...

But when I look at the resulting RegExKitLite.o with the “nm” command-line tool, it shows the culprits symbols have been listed as references in the binary object file:

% nm RegexKitLite.o | grep -e terminate\\\|personality
                 U __ZSt9terminatev
                 U ___gxx_personality_v0

Normally when I’m getting some kind of issue like this, I just type in the problematic symbols in to Google and usually find somebody else has found and solved the problem. No such luck this time. There are lots of false positives for the typical reason somebody runs into this link error: they are compiling legitimate C++ code but neglecting to link with the stdc++ library. But in our case, we are not compiling C++ code, but we’re ending up with C++ dependencies nonetheless.

I hopped on to the #clang IRC channel on irc.oftc.net, where a couple extremely helpful clang engineers (thanks to dgregor and rjmccall) helped talk me through the problem, and determine that it does seem to be a clang 1.5 bug. They confirmed that with their latest and greatest clang the bug seems to be fixed, but I was curious to confirm it myself, so I checked out and built the latest clang, too. Sure enough, all is well for future generations!

But what do we do now, stuck with the clang 1.5 that ships with Xcode? There is a crude workaround: simply link to stdc++. But yuck! All that C++ linkage dirtying up my pristine Objective-C project? Since I only use clang (for now) to build debug builds, I don’t have too much of a problem doing this. But if I was shipping these binaries I would be very hesitant to make that concession.

Radar #8230225: clang 1.5 forces linkage to C++ for non-C++ source file
(Open Radar Link)

The best we can do is report the issue to Apple and let them decide whether it’s worth their time to backport whatever fix in later clang is missing from clang 1.5. If you have other suggestions for how to work around the problem in the mean time, please do chime in with a comment below.

Update: The author of RegExKitLite kindly chimed in below with a pointer to the revision in the clang source repository that that fixes the issue. He also suggests a simple, and seemingly safe workaround, involving a slight tweak to the RegExKitLite source code.

Essentially, the idea is that before you do any major refactoring in your existing code base, you should attempt to locate a “bottleneck” to how that code is reached, and test the interface at that bottleneck. So, if all the code paths to Class A and Class B are through Class C, I can effectively just cover Class C with unit tests and be relatively certain that the functionality of Classes A and B are covered to the extent that I care about them.

Refactoring then becomes a lot less stressful, because you’re more likely to catch stupid mistakes and changes in functionality you might cause in the process. I realize that no set of tests is a guarantee against introducing new bugs, but in the process of covering classes with test coverage, you also end up learning quite a bit about what the classes actually do. This is no small victory when working with code that you either didn’t write, or that you haven’t reviewed in a number of years.

As I’ve become more and more dedicated to testing in my Mac and iPhone projects, the size of my test suites has grown. I’m subscribing to guidelines for good test writing: that they should be fast and as isolated as possible. But they still take a non-trivial amount of time to run. It’s gotten to the point where the tests for my “web publishing frameworks” take at least a minute to run on my MacBook. This is pretty fast in the big scheme of things, but a long time to wait when I’m engaged in a rapid edit, build, and test iteration.

I figured there must be some way to limit the test cases that get run to just the specific one I’m working on at the moment. And it turns out there is. Thanks to the “Other Test Flags” build setting in Xcode, I can temporarily change the behavior so that it runs only a subset of all the tests contained in my test bundle. For example, right now I’m working on tests that cover the functionality of my RSRESTCall class:

The -SenTest option is passed on to the test rig, in my case the default “otest” command that comes with Xcode. This lets the test rig know that instead of the default behavior of finding and running every test in the bundle, it should just run the tests in the “RSRestCallTests” SenTestCase subclass.

Something I didn’t mention yet but which is also aiding me greatly in the measuring my test coverage is the “gcov” library that also comes bundled with Apple’s developer tools. I’m using this to create a “Code Coverage” build of my code, that makes it possible to see exactly which lines of code did or did not get run during a particular set of tests. This, in conjunction with a cool application from Google’s Mac developers, makes it pretty easy for me to seek out uncovered areas of code, think about how to cover them with tests, and iterate.

1. I don’t know what they are.
2. I love them! You should always use them!
3. I hate them! You should never use them!
4. I appreciate them, but I’m lazy and don’t use them that much.

Of these, I have the most respect for the first and fourth. If you don’t know what unit testing is, you can hardly be blamed for failing to employ them. Go learn more about them and maybe you’ll enjoy the rest of this entry a bit more. If you are familiar with them but feel that you don’t use them enough, don’t beat yourself up. You’re probably using them “about the right amount.” That is to say, as much as you need to, in order to alleviate your pains.

Groups 2 and 3 could practically be folded into one, because each is about as useless the other. Some things in life demand a strict behavioral code, but programming is not one of them. Some kinds of code bases and programming tasks are extremely conducive to unit testing, and others are not. Use them wherever they make sense, and where they accelerate your ability to improve upon your existing code base. I won’t go into much more about the whens and ifs, but Wil Shipley and Bill Bumgarner have delved deeper into this question, if you’re interested in reading more.

Laziness Incubators

Let’s assume for the sake of argument that you’ve learned about unit testing, and self-disqualified yourself from either of the extremist groups described above. You probably find yourself in that fuzzy group that I’ve labeled lazy yet appreciative. Laziness on its own is one thing, but it doesn’t help when tedious roadblocks are put in our way to incubate further laziness.

“I should really add a unit test suite for this complicated class.”

…

“But then I’d have to create a new unit test file, and stuff…”

I’m ashamed to admit that this is how many a unit test has been put off. Other laziness incubators include the friction of adding a suitable unit test bundle target to a project, and the difficulty of deciding how to factor your unit tests so that they make sense in the context of your project. Oh, and let’s not overlook the difficulty of having to think up how to write the specific unit tests themselves.

Apple makes some of these roadblocks somewhat easier, with built-in unit testing support for Xcode. Unfortunately, they only go about 80% of the way in many regards, leaving us floundering to figure out how to fill the gaps for the remaining assistance we might need. These gaps where we’re forced to scramble for solutions can be a great deterrent to using unit tests as much as we might like.

Debugging Unit Tests

So you’ve overcome inertia and established unit testing build targets in your projects. You came up with an approach that makes sense for your code, created a new unit test suite source file, and actually written a few tests for your code. But now you’re bound to run into a vexing question: “how the heck do I debug this thing?”. Since unit tests are generally built into a standalone bundle, there’s nothing for Xcode to run. But when you come across a failing unit test and you can’t figure out why, you find yourself wishing you could step through the code just as you might in an application.

The answer to this question, as well as many other “missing pieces” for unit test support in Xcode, comes from Chris Hanson, who shares a great deal of useful information on his blog, including this gem on debugging unit tests. This post also contains a number of useful links if you’re still struggling with the other roadblocks such as adding a target, etc.

What we learn from Chris is essentially that the easiest way to debug unit tests in your project is to set up some executable, any executable, and arrange for your unit test bundle to be “injected” into the executable at runtime. Now, to debug your unit tests, you just ask Xcode to debug the injected executable.

It turns out this isn’t very difficult, but it’s tedious. To set up this custom executable, you need to add a bunch of cryptic command line arguments and environment variables to your project. Yuck! This cumbersome process has caused me on many occasions to “just skip doing unit tests for now.” That’s not really helpful to me or to the health of my code, so I finally got off by butt and wrote a handy AppleScript to do it for me:

Download Add Unit Test Executable. Free AppleScript.

What does this script do? In a nutshell, it asks for the name of your unit test bundle. Provide it, without the “.octest” extention, and the script will add a custom executable to your application, with all the gross arguments and environment variables needed to “make it work” in both Xcode 3 and Xcode 3.1. I added it to my Xcode application-specific scripts folder, and select it (using FastScripts) whenever I find myself in a project that doesn’t already have a suitable custom executable for debugging unit tests.

My script uses TextEdit.app as the test harness application, because it’s on everybody’s Mac, and because it seems like a fairly innocuous host application. Of course, you could use your own application, or another custom host application of your choosing. Just edit the script to suit your needs.

Hope this helps some of you overcome one source of laziness getting in the way of writing excellent unit tests!

But every once in a while even the most polished and refined software exhibits that nastiest of malfunctions: the crashing bug. In the middle of a possibly important user task, the application comes screeching to a halt and disappears, leaving the user with nothing more than a cryptic message from the operating system, along with an offer to send the crash log off to Apple.

Needless to say, crashes suck. A lot. For users, especially. If there’s one behavior of your application that you should focus on eliminating, it’s the behavior of crashing. Above all other “nuisances,” this is the one that is absolutely unacceptable.

Which is why crash logs are so important. Occasionally, when a user is sophisticated enough to understand the value of the crash log and, instead of choosing to send it to Apple, copies and pastes it into an email to you, you should be overjoyed! Finally! A crash has been captured in the wild and delivered to you for easy inspection. This artifact not only proves that a crashing bug exists, but usually includes highly detailed information about where and how the crash has happened.

Which is why it boggles the mind to think that some developers see these crash logs as relatively useless. In my own experience of reporting bugs to other developers, I have found frequently that my crash log is considered more as a statistic than as a specimen. While I expect a response like “great, I see what the bug is, and I’ll get this fixed,” I often get responses more like “sigh, I’ve seen this a few times but have no idea what’s going on!”

Sometimes I find that the developer in question simply needs to be educated about the tools at his or her disposal. I imagine the hours wasted speculating about what the crash log means, and can’t help but think if they knew how to analyze it, they could have the bug solved (in many cases) in moments. Oh – and I’m sounding high and mighty right now, so before I get too carried away, let me just say that I too need to be educated on a great many things, but making sense of crash logs is not particularly high on that list. I leave it to other bloggers to fill in the gaps of my education.

Crash Logs: The Crappy Way

So what is this big thing that developers are missing? Well, a crash log essentially shows the “path” that the little hamsters in your computer were running on when they fell off the cliff. It paints a picture of where the program got misguided and went off doing something it never should have done. Problem is, the picture is a little blurry. Below is an actual crash log submitted by an actual MarsEdit user (abbreviated and condensed to fit the blog):

Thread 0 Crashed:
Foundation 0x93cc2a2e _NSAPAddPage + 94
Foundation 0x93cc3b27 __NSAutoreleaseObject + 263
Foundation 0x93cc3962 -[NSObject(NSObject) autorelease] + 18
Foundation 0x93cceaca +[NSString stringWithFormat:] + 106
marsedit   0x000637fb 0x1000 + 403451
marsedit   0x00053883 0x1000 + 338051
marsedit   0x000539ea 0x1000 + 338410
marsedit   0x00053d7b 0x1000 + 339323
marsedit   0x00053e45 0x1000 + 339525
marsedit   0x0005238b 0x1000 + 332683

For any non-programmers who are still reading (bravi!), you may have a little trouble understanding what the heck this means. This is an ordered description of the path the computer followed while trying to do something. Problem is it ended up crashing. The path is shown in reverse-order, so the crash is at the top of the list, inside Foundation (an Apple system library). Trying to make human sense of this goes something like this:

1. Something in MarsEdit at address 0x0005238b…
2. … called something in MarsEdit at address 0x00053e45
3. … called something in MarsEdit at address 0x00053d7b
4. … called something in MarsEdit at address 0x000539ea
5. … called something in MarsEdit at address 0×00053883
6. … called something in MarsEdit at address 0x000637fb
7. … which called a standard string library method “stringWithFormat”
8. which eventually crashed in the system.

You can sort of see how some developers are forced to throw up their arms in despair, right? But what if you could turn this muddled picture into something a bit sharper? The fact is, you can. The reason the picture is so blurry is because MarsEdit shipped without debugging symbols. The reasons for this are mostly to keep the shipping application as small as possible, but there are also some good reasons to hide the symbols if they reveal too much about your business strategy.

Crash Logs: The Happy Way

Many developers seem to think that gathering useful crash logs requires shipping a symbol-laden application, but aren’t willing to do so. The fact is, you can have the best of both worlds by shipping a symbol-stripped version of your application, but keeping a symbol-laden version on-hand for the developer’s convenience.

What am I getting at? Apple offers a tool called “atos”, which makes it relatively easy to map an address from a symbol-stripped application to a name in a symbol-laden version of that same application. As long as the two applications were built with the same sources and using the same build options, the addresses are bound to match up. It’s just the symbols that are “stripped” from the shipping application.

Let’s take a look at what happens when I apply my atos powers to the crash log I pasted above. From the Terminal, I invoke atos with the literal memory addresses of all the mysterious points in the “path” from the crash log. You can list the addresses in whatever order you want, but I’m listing them so that the result will be in order from top to bottom, the same way I reasoned out the crash in plain “crappy” English above:

iBook> cd MarsEdit.app/Contents/MacOS
iBook> atos -arch i386 -o MarsEdit \
	0x0005238b 0x00053e45 0x00053d7b 0x000539ea 0x00053883 0x000637fb

Note also that I specified the architecture explicitly. This is because I am debugging this on a PowerPC Mac, but the crash log I received showed that the customer is running on an Intel machine. This yields a magical response with, behold, real meaningful symbols!

-[RSXMLRPCCall invoke:] (in MarsEdit) (RSXMLRPCCall.m:397)
-[RSXMLRPCRequest requestText] (in MarsEdit) (RSXMLRPCRequest.m:239)
-[RSXMLRPCRequest serializeParams:] (in MarsEdit) (RSXMLRPCRequest.m:216)
-[RSXMLRPCRequest serializeDictionary:toString:] (in MarsEdit) (RSXMLRPCRequest.m:153)
-[RSXMLRPCRequest serializeData:toString:] (in MarsEdit) (RSXMLRPCRequest.m:123)
-[NSData(extras) base64StringWithLineLength:] (in MarsEdit) (NSData+extras.m:215)

Now I can apply my human sense again, but with the benefit of symbolic names instead of raw memory addresses:

1. MarsEdit invoked an RPC network request
2. … which while building the actual request cargo text
3. … was trying to serialize the parameters
4. … when it tried to serialize a dictionary object
5. … whose data
6. … upon being converted to a Base64 representation
7. … caused a “stringWithFormat:” call that went blammo!

Not only does the plot to this story make a lot more sense now, but I’ve even got handy pointers to the line numbers in the source code. Let’s see, NSData+extras.m, around line 215:

NSString *charString = [NSString stringWithFormat:@"%c", base64EncodingTable [outbuf [i]]];

Survey says? That’s the line I’m going to zero in on now as I try to figure out why this crash is occurring. Sure, I’ll have to now speculate as to why, and under what circumstances the observed crash might occur. So the magic of “atos” doesn’t take all the work out of debugging a crash log, but it brings most crashes out of the “frustratingly impossible” into the realm of “all in a day’s work.” I can use my knowledge of the situation to ask intelligent questions of the user, and hopefully get to the bottom of it, so that no other user ever has to see the nasty crash again.

I can do more than just tell the user “thanks for the report, I have no clue what’s happening here. Sorry.”

Doing It For Yourself

I hope I’ve intrigued you by the power of what I was able to achieve with “atos”, but of course to do the same with your own project, you’ll need to make sure you can come up with a “symbol-laden version” of your release app, so you can apply the same magic. The best way I know to do this is to simply add another build configuration in xcode, that is just like your “Release” configuration, but doesn’t strip out debugging symbols. You can read more about this approach and others in Apple’s fine documentation.

If you find yourself dealing with crash logs on a regular basis, it might be a good idea to make building a “symbol-laden” version of your app part of the standard build and distribute process. For myself, I’ve found it happens rarely enough that I’m happy with a process whereby I re-checkout a tagged version of the sources from Subversion, and then rebuild a copy using the “Release With Symbols” build configuration.

Nota Bene: If you’re on Leopard and trying to replicate a symbol-laden version of an app you shipped with Tiger, you’ll probably have to tweak Xcode to use the old linker, in order to get a build whose memory addresses match up with your old Tiger-built application. Might be easier to just go back to Tiger and rebuild it there.

I know this was probably common knowledge for some of you, but I also know from experience of chatting with my colleagues that this is completely new, forehead-slapping “why didn’t I know about that?!” type material for many others. I hope it saves you hours of work. Possibly even enough hours to continue reading long articles such as this one!

The podcast is called the Mac Developer Roundtable, and I felt honored to be invited to participate for the first episode. We recorded it a week or two ago, and it has just gone live:

Mac Developer Roundtable Episode 1

In this first episode, we all chatted about Leopard and in particular what’s new and exciting for developers. Tune in to hear the collected wisdom of Fraser Speirs, Uli Kusterer, Marcus Zarra, and of course our host Scotty.

One question I raised in the show was whether the new “ibtool” (formerly nibtool) in Leopard makes the whole process of automated localization any easier. To be honest, I resist localized versions for many of my applications largely because the hassle of integrating localization updates has always seemed really awkward to me. I’d love to get into a position where I could easily integrate updates to localizations without having to hand tweak things all the time. I know there are some existing solutions using nibtool but I wonder if things have gotten even better in Leopard?

Got any great localization techniques to share?

I love the emphasis on “researchability.” He points to the fact that projects of a certain size become impossible to keep in your head. So when you go to work on any particular subsection of the app, you need to be confident that you’ll find your balance quickly so you can get on with your work.

In particular, I liked the suggestion that weak binding in the form of notifications or key-value observing can be detrimental to researchability. Brent notes that the weak binding makes it difficult to mentally follow the source code, so it can be prudent to strongly bind classes that are otherwise useless without each other.

He also reminds us of some good IDE habits for maintaining code. I was glad to be reminded that the function popup in Xcode is keyboard invokable (as Brent says, “Every time you touch the mouse, God kills a kitten.”). This is very cool because with keyboard navigation of the menu you can quickly jump to a method by name.

Another tip he reminds us about is the “Open Quickly” option (cmd-shift-D). I use this feature frequently, but not in the way he describes. It’s infuriating that when you want to “open quickly,” the dialog for typing in the name of a source file doesn’t tab-complete. Imagine how much more powerful it would be if you could type “MyPic<tab>” and get “MyPictureThingyController.h”. Having to type the whole name of a file in removes most of the quickness. When I use the shortcut, I do so with the cursor inside the quotes or brackets of an include line. When invoked in this context, Xcode is smart and just jumps to the desired header file.

Update: Quentin over at Rogue Amoeba noticed this shortcoming a long time ago, and developed an Xcode plugin to address the problem. Check out Xcode Open Quicker.

- (BOOL) windowShouldClose:(id)sender;

If you implement this delegate method and return NO for a particular window, then the user’s attempts to close it are thwarted (hopefully because you just did something friendly like ask them if they were sure or not).

If we’re agreed that delegation and dynamic messaging are a good idea, we should be prepared to use them in our own code as well. Let’s say we’re writing a custom class where delegation of this kind would be useful. We’d like to be as much like Apple as possible, to further solidify the patterns that we all use on a regular basis.

My example application is a coffee maker, and it makes coffee at regular intervals unless the delegate method believes it should not:

- (BOOL) coffeeMaker:(RSCoffeeMaker*)theMaker
	shouldBrewForScheduledDate:(NSDate*)scheduledDate;

What must the code in the coffee maker do in order to satisfy this contract? The “scheduledBrewTimerFired:” method might look something like this:

- (void) scheduledBrewTimerFired:(NSTimer*)brewTimer
{
	BOOL shouldBrew = YES;

	// Give the delegate a chance to reject
	SEL delSelector =
		@selector(coffeeMaker:shouldBrewForScheduledDate:);

	if ((mDelegate != nil) &&
		([mDelegate respondsToSelector:delSelector] == YES))
	{
		shouldBrew = [mDelegate performSelector:delSelector
			withObject:self
			withObject:[brewTimer fireDate]];
	}

	if (shouldBrew == YES)
	{
		//...
	}
}

Nifty, right? Yes, nifty. But wrong. What’s the problem? It’s that line where performSelector is called. If you have as many warnings turned on as you should, you’ll see something along the lines of “warning: assignment makes integer from pointer without a cast.” The reason? The performSelector method returns an “id”, not a “BOOL”. We’re expecting magic to happen here, and those of us who grew comfortable with the nuances of PowerPC-based calling conventions have seen magic happen here more often than is healthy.

By violating the function prototype for performSelector, we’re robbing the compiler of its ability to accurately produce assembly code that retrieves the BOOL return type correctly. That means we’ll get the wrong answer some percentage of the time, where that percentage is determined by the degree to which BOOL and id return types are handled differently on the platform.

My first instinct in addressing this problem was to go down a layer. Surely if performSelector is using an unsatisfactory prototype, I could just drop down to objc_msgSend and handle the messaging myself. But alas! The lower-level function also returns an id. At this level, there are some special functions such as objc_msgSend_stret, which messages an object and returns a structure, but there isn’t a handy objc_msgSend_boolret for our convenience.

So what’s a conscientous developer to do? I was lucky to discover a mailing-list thread, in which the answer to this question was beautifully outlined by Greg Parker of Apple. Credit also goes to Rosyna of Unsanity, for asking the question that led to Greg’s answer. Rosyna later expressed appreciation in a follow-up post.

So what’s the trick? In order to get the freedom of dynamic messaging combined with the complete cooperation of the compiler, we need to define a custom function pointer. This points to the same address in memory as the objc_msgSend function, but is defined with a differing prototype. This way we get the message delivery functionality of the Objective-C runtime, while letting the compiler in on the fact that the method being messaged will in fact return a BOOL typed response.

#import <objc/objc-runtime.h>

- (void) scheduledBrewTimerFired:(NSTimer*)brewTimer
{
	bool shouldBrew = YES;

	// Give the delegate a chance to reject
	SEL delSelector =
		@selector(coffeeMaker:shouldBrewForScheduledDate:);
	if ((mDelegate != nil) &&
		([mDelegate respondsToSelector:delSelector] == YES))
	{
		// Give the compiler a clue - courtesy of Greg Parker
		BOOL (*MyMagicSender)(id, SEL, id, id) =
			(BOOL (*)(id, SEL, id, id)) objc_msgSend;

		shouldBrew = MyMagicSender(mDelegate, delSelector,
			self, [brewTimer fireDate]);
	}

	if (shouldBrew == YES)
	{
		//...
	}
}

Nifty, right? And correct, too. Enjoy!

Update: Paul Kim via chat, and Jan Van Boghout in the comments below each noticed a flaw in my contrived example. Since I already know the selector I’m planning to call, I could just define it explicitly with a regular Objective-C method prototype. Then the compiler would know exactly how to generate the code if I called the delegate directly:

shouldBrew = [mDelegate coffeeMaker:self
	shouldBrewForScheduledDate:[brewTimer fireDate]];

That’s true, and it’s a fault in my overly-contrived example. But imagine a more dynamic scenario, where the prototype of the method is known, but not the selector. For instance, if the class offers clients the ability to specify a selector:

- (void) scheduleBrewingAtDate:(NSDate*)brewDate
	withBrewDelegate:(id)brewDelegate
	withDelegateSelector:(SEL)delSel;

But while I’m debugging the code that actually does the manipulation, I find myself stuck doing stupid stuff like:

(gdb) p/x ((char*)[imageData bytes])[14]
$1 = 0x28

Ugh! That’s no way to win the software wars. It occurred to me today that what I really want is something like Hex Fiend built right into the debugger. Why shouldn’t I be able to hex-dump my NSData objects directly from the console? It turns out I wasn’t alone in this wish, because Dan Wood recently published a category on NSData that allows just that.

By simply compiling the NSData category into a given application, you give NSData’s debugging description superpowers. For instance, here’s me at the gdb console, examining the contents of the favicon.ico response I just received from NSURLConnection:

(gdb) po imageData
NSData 350 bytes:
00 00 01 00 01 00 10 10 10 00 00 00 00 00 28 01 | ..............(.
00 00 16 00 00 00 28 00 00 00 10 00 00 00 20 00 | ......(....... .
00 00 01 00 04 00 00 00 00 00 C0 00 00 00 00 00 | ................
00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF | ................
FF 00 00 00 FF 00 00 00 EF 00 00 00 DE 00 00 00 | ................
CE 00 00 00 BD 00 00 00 AD 00 00 00 9C 00 00 00 | ................
8C 00 00 00 7B 00 00 00 52 00 00 00 42 00 00 00 | ....{...R...B...
29 00 00 00 10 00 00 00 00 00 00 00 00 00 11 11 | )...............
11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 | ................
11 11 11 11 11 11 13 31 11 11 12 55 21 11 1B B1 | .......1...U!...
13 D8 7F FF FB 31 1B B1 6F D4 FB 65 9F D2 1B DB | ....1..o..e....
FB 21 84 11 15 F5 1B FF FC 41 12 78 8D D1 1B B1 | .!.......A.x....
3C C1 2D FF FB 51 1B B1 1A D1 5F 71 11 11 1B C5 | < .-..Q...._q....
BF 81 1C C7 58 61 1A FF C6 11 12 BF FF 81 12 54 | ....Xa.........T
11 11 11 13 52 11 11 11 11 11 11 11 11 11 11 11 | ....R...........
11 11 11 11 11 11 11 11 11 11 11 11 11 11 00 00 | ................
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................
00 00 00 00 00 00 00 00 00 00 00 00 00 00       | ..............
Current language:  auto; currently objective-c
(gdb)

Dan’s code is pretty much perfect as-is, but I couldn’t resist tacking on some additional features. His category hardcodes the dumped data to 1024 bytes, but in my case there are times when I’m interested in seeing more. I added two category methods to the mix:

// startOffset may be negative, indicating offset from end of data
- (NSString *)descriptionFromOffset:(int)startOffset;
- (NSString *)descriptionFromOffset:(int)startOffset
				limitingToByteCount:(unsigned int)maxBytes;

Now I can peek at a specific subrange, or expand the default limit of 1024 bytes. I can even peek at the end of a chunk of data, by specifying a negative offset:

(gdb) po [mDocumentData descriptionFromOffset:-11]
NSData 109 bytes (showing bytes 98 through 109):
02 43 41 54 41 54 4F 4E 49 43 00                | .CATATONIC.
(gdb)

Wow! This is a pretty huge addition to my debugging and development toolbelt. Many thanks to Dan Wood for providing the ready-made code to speed up my implementation.

NSData+RSHexDump is freely available to you, under an MIT license.

For some dumb reason, I’ve been living without such conveniences for several years now. I know there are many 3rd party products that add an epic amount of functionality to the standard copy and paste of the system, but I’m not really interested in running a separate application for this purpose.

It occurred to me that this would be a perfect use of Xcode’s Menu Scripts. Xcode not only supports the addition of custom scripts to the menu bar, but supports a unique format by which the scripts can advertise keyboard shortcuts, and integrate seamlessly with Xcode’s text editor. For instance, you can use a script to process the selected text in Xcode and spit back out something else in its place.

Append To Pasteboard is a simple python script that takes advantage of the “pbcopy” and “pbpaste” commands to tack whatever you’ve selected in Xcode on to the end of the existing pasteboard. You stick this within your (horribly located) user scripts folder, where you must name the folders and files with numeric prefixes to inform Xcode where they belong. For example, the script lives in my home directory:

/Users/daniel/Library/Application Support/
	Apple/Developer Tools/Scripts/
	10-User Scripts/1-DCJ/

Unfortunately Xcode doesn’t handle the situation where some scripts come from your home directory, and some come from the /Library installation directory. So I put everything in my home directory. The “10-User Scripts” is how I tell it to name the menu bar item “User Scripts.” The “1-DCJ” folder is the folder with all my custom scripts in it, and since it is “1,” it comes before all of Apple’s standard scripts that I copied in (10-Open, 20-Search, etc). The process of providing scripts to Xcode is ugly but when you finally get it all put together, this is what you end up with:

Now it’s a snap to cruise through a .m and accumulate method declarations, for pasting into a corresponding .h. Note that the script always appends a newline to the existing pasteboard, which could be annoying depending on what you want to use it for. Since I envision myself almost always double-clicking a function or method declaration and appending it to a list, I find this behavior to be most convenient.

Thanks to Jon Wight for helping with Python.

Update: Any productivity gained by using this macro was certainly lost as I tried desperately to debug Xcode’s latest propensity to “beachball” on launch. Finally, I attached with gdb and found a telling backtrace. Hmm? Yep, when I “zipped” the script for upload to the blog, I left a zipped copy in the scripts folder. Next time I launched Xcode, it choked big time on trying to treat that zip file as a script.