Advanced programming tips, tricks and hacks for Mac development in C/Objective-C and Cocoa.

Hidden Xcode build, debug and template settings

This is a collection of the most useful hidden and hard-to-find settings in Xcode related to building, debugging and file templates.

This post is about hard-to-find settings in Xcode that most programmers can't live without. I felt strange writing a post on this topic since most of this information is documented elsewhere. But I still find myself forgetting and needing to rediscover these tidbits (even though I've been using ProjectBuilder/Xcode for 7 years and should remember), so I think that it's probably information worth reinforcing.

I'll cover:

Custom compiler settings

The default compiler settings in Xcode projects are pretty good. Even so, it's a programmer's mission to play with everything and playing with the compiler settings is at the heart of a programming project.

Custom compile settings are buried pretty deep in Xcode. To access the custom compiler settings, you must:

  1. Have a project window or project-contained document window frontmost in Xcode.
  2. Select the menu item "Edit Project Settings" from the "Project" menu in the menubar
    Right-click the project icon in the "Groups & Files" tree-view of the Project window and select "Get Info" from the popup menu (the project's icon is a blue document icon located at the very top of this tree-view by default).
  3. Select the "Build" tab at the top of the Project Info window that appears.
  4. Set the "Configuration" to "Debug", "Release" or "All Configurations" from the popup menu at the top of the tab panel (compile settings will only be changed for the configuration that you select).
  5. Scroll down to the heading named "GCC 4.0 - Language".
  6. Each of these checkboxes allow customization of build settings. If you want to know what setting each will affect, click on the row and show the "Research Assistant" (Control-Command-?).

Completely custom command line settings can be passed to the compiler using the "Other C Flags" line (for C and Objective-C) or the "Other C++ Flags" (for C++).

More on Xcode's build settings can be found in the "Xcode Build Setting Reference".

Post or pre build scripts

Build phases are how Xcode performs the different steps in a build. If you expand one of the targets in the "Targets" node of the "Groups & Files" tree-view of the Project window, you can see the different steps in the build. For a normal "Cocoa Application", the steps will be "Copy Bundle Resources", "Compile Sources" and "Link Binary with Libraries".

You can add a new build stage to a target by right-clicking the target and selecting the build phase you want from the "Add" submenu of the popup menu.

You can also choose one of the options in the "New Build Phase" submenu of the "Project" menu in the menubar to add a build phase to the current target.

To add a "script" build stage, select "New Run Script Build Phase". This will add a new script as the last phase of the build. If you want the script to be a "pre-build" script, you must drag it to the top of the list of build phases shown for the target in the "Targets" node of the "Groups & Files" tree-view of the Project window. An "inter build" script would also be possible by dragging to a location between other stages.

Finally, you must enter the script itself. Select the build phase and choose "Get Info" from the "File" menu in the menubar. Select the "General" tab and you can enter the script in the "Script" field.

A list of variables you can use in your script is listed on the Run Script Build Phase page of the Xcode documentation.

Changing the built program's name

This can be a little tricky to find since the the built program's name ("" for example) does not exist in any complete form in Xcode.

  1. Have a project window or project-contained document window frontmost in Xcode with the "Active Target" set to the target whose product you'd like to rename.
  2. Select the menu item "Edit Active Target '...'" from the "Project" menu in the menubar
    Right-click the target's name under "Targets" in the "Groups & Files" tree-view of the Project window and select "Get Info" from the popup menu.
  3. Select the "Build" tab at the top of the Project Info window that appears.
  4. Set the "Configuration" to "Debug", "Release" or "All Configurations" from the popup menu at the top of the tab panel (compile settings will only be changed for the configuration that you select).
  5. Scroll down to the heading named "Packaging".

The name of the application will be a combination of the "Executable Prefix" (normally empty), the "Product Name" (initially the same as the Project's name), the "Executable Prefix", and the "Wrapper Extension" (normally ".app" for Applications).

In short, most of the time you will just need to change the "Product Name" field.

Replacing __MyCompanyName__ in the new file templates

Enter the following line:

defaults write PBXCustomTemplateMacroDefinitions '{ "ORGANIZATIONNAME" = "Your Company Name" ; }'

into a Terminal window, replacing "Your Company Name" with whatever you choose.

You can also open the file at ~/Library/Preferences/ in "Property List Editor" and insert your company name as a string value for the key "ORGANIZATIONNAME" under the dictionary "PBXCustomTemplateMacroDefinitions". You may need to create "PBXCustomTemplateMacroDefinitions" at the top level if it doesn't already exist.

Changing the new file templates

The complete set of file templates that Xcode uses for new files can be found at "/Developer/Library/Xcode/File Templates/", sorted by API (we love Cocoa the best).

You can add or modify them as you choose, although it's a good idea to backup changed files at a different location since "/Developer/Library/Xcode/File Templates/" may be lost if you move your account to a new computer or reinstall Xcode.

Text macros

The "Text macros" in Xcode are a great time saver. You can find them under "Insert Text Macro" in the "Edit" menu but they are most useful when you know their shortcuts. Type the shortcut in a document in Xcode when you're editing, hit "F5" to autocomplete and it expands the macro to its full form, complete with variable locations.

For a full list of the default text macros and their shortcuts, visit Apple's "Xcode User Guide: Repeating Code".

The first way to customize text macros are to create entries for "BlockSeparator", "IndentedBlockSeparator", "InExpressionsSpacing", "PostBlockSeparator" and "PreExpressionsSpacing" in the "XCCodeSenseFormattingOptions" dictionary in your "" preferences file.

As before, you can do that like this:

defaults write XCCodeSenseFormattingOptions '{ "BlockSeparator" = "\n" ; }'

or by editing the "~/Library/Preferences/" file directly.

You may also want to add completely new macros or customise more than these variables will allow. The best way to do this is to copy the "TextMacros.xctxtmacro" directory from:



~/Library/Application Support/Developer/Shared/Xcode/Specifications

and modify or add to the macros that Apple provide.

It is not advisable to edit the original "TextMacros.xctxtmacro" definitions contained inside directly. We copy them to our own Library since the versions will be replaced without warning every time you update Xcode.

Note: the destination path to which you should copy "TextMacros.xctxtmacro" is correct here but wrong in the Apple-provided "Repeating Code" documentation linked above (the documentation currently omits the "Xcode" directory between "Shared" and "Specifications").

Macros are sorted by programming language. I'll leave you to work out exactly how the macros are formatted. I'm not aware of any formal documentation for the xctxtmacro file format but it's plain text in a "Property List"-style format so you shouldn't find it too hard to decipher.

Environment Variables and Executable Arguments

With the desired Project and Target selected, choose "Edit Active Executable ..." from the "Project" menu in the menubar. The environment variables and executable arguments can be chosen on the "Arguments" tab.

The following environment variables are of particular importance when programming in Cocoa:

  • NSDebugEnabled set to value YES — turns on extra debug information in Foundation
  • NSZombieEnabled set to value YES — notifies when messages are incorrectly sent to deallocated objects allowing better debugging of this problem

For more debugging environment variables, check the "Technical Note TN2124: Mac OS X Debugging Magic" page from Apple.


Doing things in Cocoa with "nil"

"nil" is a pointer to nothing. Here are some useful things that you can do with that pointer to nothing in Objective-C and Cocoa.

A quick definition of "nil"

It is possible you don't know what "nil" means in Objective-C. Just so there's no confusion let me quickly explain:

nil is the value an object pointer has when it isn't pointing to anything

If you're familiar with other C derived languages, you might think: "doesn't 'NULL' do the same thing?"

The answer is: almost. Where "NULL" is used for C pointers in a general sense, "nil" in Objective-C is reserved exclusively for pointers to objects. If you right-click on "nil" in XCode though, you'll find that "nil", "NULL" and "__DARWIN_NULL" are all defined to have the same value: (void *)0.

Objective-C also defines the constant "Nil" (notice the capital 'N') with the same value as "nil" for use as a class pointer instead of an object pointer. In practice though, since classes are objects, "nil" is commonly used for both.

In the beginning, everything is zero

In Objective-C, instance variables (except isa) in a newly allocated object will be set to zero. This is the same behavior as a calloc in Standard C.

This means that all of your object's pointers to other objects are already "nil". Since this is the case, you should behave accordingly. Don't redundantly initialize variables to "nil", "NULL", 0, "false" or "NO".

In fact, you should consider choosing meanings for your booleans such that false is the appropriate state on object allocation. For example "isInitialized" instead of "needsInitialization".

You can send messages to "nil"

You can validly send any message to a "nil" pointer in Objective-C. This is very different to languages like C++ where invoking a method on a "NULL" pointer will likely crash your program.

Sending a message to "nil" will have only one effect: it will return a zero value. No other action will occur. This means that the following code:

if (myObject == nil || ![myObject isEqualTo:anotherObject])

can be shortened to:

if (![myObject isEqualTo:anotherObject])

which allows the false return value from sending a message to "nil" as one of potential code paths in the boolean expression.

Sending messages to "nil" does have some drawbacks:

  • The returned zero value will only work if the size of the expected return type from the method is less or equal to the size of a pointer, or if the return type is a long long, double or struct. Support for long long, double and struct is new in Mac OS X 10.5.
  • Sometimes code is clearer when you account for "nil" values as a separate case (acknowledging that you've considered and planned for it as an input case).
  • If the object is not supposed to be "nil", the fact that Objective-C will quietly continue can hide the misbehaviour. You should consider this when debugging.


NSNull is a placeholder that Cocoa uses to represent "nil" in the Foundation collection classes (NSArray, NSSet, NSDictionary, etc) since these classes can't contain "nil" values.

You can insert NSNull into your own collections to represent "nil" values but its real use is when Cocoa inserts it for you. Consider the following:

NSArray *namesOfObjects = [arrayOfObjects valueForKey:@"name"];

The valueForKey: fetches the "name" of each object in the array arrayOfObjects using key value coding and builds an NSArray of the results. If any of the "name" properties is "nil", we will get an NSNull value instead.

Some points to note about this: you must test for NSNull yourself. NSSet will not create NSNull entries when using key value coding (it simply omits them).

Setting NSMutableDictionary values with "nil"

Since you're not allowed to add a "nil" valued object to an NSMutableDictionary , the following:

[myMutable Dictionary setObject:nil forKey:@"key"];

will throw an exception.

What if you have a few objects that you want to insert into an NSMutableDictionary but you're not sure if any of them are "nil"?

You could test each one first, to see if it's "nil", like this:

NSMutableDictionary *newDictionary = [NSMutableDictionary dictionary];
id firstObject = [source getFirstObject];
if (firstObject)
    [newDictionary setObject:firstObject forKey:@"firstObjectKey"];
// ... and so on for all other objects

Or, assuming your keys are strings, you could take advantage of the key value coding methods on NSMutableDictionary and simply write:

NSMutableDictionary *newDictionary = [NSMutableDictionary dictionary];
[newDictionary setValue:[source getFirstObject] forKey:@"firstObjectKey"];
// ... and so on for all other objects

Notice the "setValue:forKey:" instead of "setObject:forKey:". The setValue:forKey: version tests the value first, to see if it's "nil". If it is, it treats the instruction as though you had called removeObjectForKey: instead — which will gracefully do nothing if the object isn't there.

Key value coding (the setValue:forKey: case) requires NSString keys, so if your NSDictionary is keyed by something other than strings, the approach shown in the second example would not be possible.

Other zero values

"nil" is a zero valued object pointer. Cocoa conveniently provides a few other zero values for different purposes. They include:

  • NSZeroPoint — an NSPoint at the origin
  • NSZeroSize — a zero width and height NSSize
  • NSZeroRect — a zero width and height NSRect at the origin

Speed test: NSManagedObject ObjC-2.0 accessors

A quick, relative-performance test of the 3 ways of accessing NSManagedObject properties in Leopard.

Mac OS X Snow Leopard? I'm still not up-to-date with 10.5!

If you've been in a coma all week, you might not have noticed that Apple announced the next major update to Mac OS X on Monday, Snow Leopard. It's scheduled for "sometime next year" which means that I really should finish updating my code for the current version of Mac OS X.

As part of this, I've been assessing whether or not I should refactor some of my old pre-Leopard code to use the new NSManagedObject accessors introduced in Leopard.

If you don't know what I'm talking about, let me show you this...

// The old way to set an NSManagedObject string value
[object setValue:value forKey:@"stringValue"];

// The custom accessor way to set an NSManagedObject string value
[object setStringValue:value];

// The new alternate syntax for setting an NSManagedObject string value
object.stringValue = value;

In the "old" approach, NSManagedObject had to perform string comparisons to work out which property in the NSManagedObject's entity description corresponded to the provided "key". It also had to work out if custom "getter" and "setter" methods existed and might need to be invoked.

The "custom accessor" approach eliminates the string comparison and method lookups but prior to Leopard, you had to explicitly write these methods yourself — something time consuming enough to discourage use. In Leopard, you only need to declare these methods and you get the implementation for free.

The "new" approach really just uses Leopard's automatically generated custom accessor methods through Objective-C 2.0 properties but only requires "property" declaration (slightly less work again than method declaration).

With "custom accessor" methods requiring extra development work under Tiger, most of my pre-Leopard code uses the old KVC approach. Do I care? Should I update my code?

Give me the numbers

The real question is: how much difference does it make? I have lots of code which uses the "old" approach. How much improvement will I see with one of the other two approaches?

Time for some test code:

    for (int i = 0; i < 10000; i++)
        for (NSManagedObject *object in objects)
            #if LEOPARD_OBJC_2_ACCESSORS
                NSString *value = object.stringValue;
                object.stringValue = value;
                NSString *value = [object stringValue];
                [object setStringValue:value];
            #else // Key Value Coding accessors
                NSString *value = [object valueForKey:@"stringValue"];
                [object setValue:value forKey:@"stringValue"];

My test data is a set of 1000 entities with "stringValue" set to "Entity number %d" (where "%d" is 0001 to 1000). All data is prefaulted. All I'm doing is accessing a string value and setting it back again to the same value 10 million times.

Performance looks like this:

Access approachTime taken
Objective-C 2.0 Accessors 16.6701 seconds
Custom Method Accessors 16.7978 seconds
Key Value Coding Accessors 31.6373 seconds

* results generated on a Dual 2Ghz PPC G5 (Intel-only Snow Leopard makes him cry)


The automatically generated Leopard accessors take half the time of the Key Value Coding approach — a substantial improvement. There is no practical difference between "Objective-C 2.0 Accessors" and "Custom Method Accessors" so that is merely a matter of stylistic preference and header declarations.

The old Key Value Coding approach still has its uses, particularly for runtime-selected key paths. It is also the only approach which requires no headers or declarations at all (although this can lead to runtime errors). But beyond that, I really should do some refactoring.


Five approaches to listening, observing and notifying in Cocoa.

Here are five different ways to implement the Observer design pattern (sometimes called Broadcaster/Listener, Publish/Subscribe or Notifications) in Objective-C and some reasons why each approach can be valuable.

This post will cover:

  • Manual broadcaster and listeners
  • Key Value Observing
  • Notification centers
  • Context notifications
  • Delegates used for observing

About Observer

The observer design pattern is one of the most powerful ways of maintaining abstraction between two modules. The observer design pattern involves one module that declares an event that has occurred and any number of other modules which then choose to respond to this event. It differs from the first module directly invoking the methods of a second module because the first module doesn't need to care about how many observers it has, allowing more complete abstraction between the observee and its observers.

Manual broadcaster and listeners

The manual approach is where the broadcaster maintains an NSArray or NSSet of listeners. When it is appropriate to notify the listeners of an event, the broadcaster invokes the relevant method directly on each listener.

You will need an NSMutableArray, NSSet or maybe an NSMutableDictionary on the broadcaster class. The latter is good if you want to "key" each of your listeners by some type of event identifier. You'll also need methods on the broadcaster so that listeners can register and unregister themselves.

Sending a message to every object in an NSArray or NSSet is as simple as:


See Collections Programming Topics for Cocoa for more.

Advantages: the broadcaster has complete control over its list of listeners. Disadvantages: manual work to add and remove listeners from the collection (especially if it is not already maintained for a different reason). More manual work if different types of message need to be broadcast.

Key Value Observing

The NSKeyValueObserving protocol goes a long way towards making the above process significantly automatic. In many cases, the broadcaster doesn't need to do anything.

Every object in Cocoa automatically handles addObserver:forKeyPath:options:context: which allows any object to be a broadcaster. If the "setter" methods on the broadcaster follow certain rules, the "setter" method will automatically trigger the observeValueForKeyPath:ofObject:change:context: method on any listener. For example:


will add an observer to the "source" object so that it will send an observeValueForKeyPath:ofObject:change:context: message to destination every time the setMyValue: method is invoked.

All you need to do is have every listener register themselves with the observee and have the listeners implement observeValueForKeyPath:ofObject:change:context:.

See NSKeyValueObserving Protocol Reference for more.

Advantages: built in and automatic. Observation can be of any key path. Supports dependent notifications. Disadvantages: not possible for the broadcaster to know who is listening. Methods must follow naming convention for automatic observation messages to work. Listeners must be removed as observers before they are deleted, otherwise subsequent notifications will result in crashing and failure — but this is true of all approaches listed in this post.

Notification centers

NSNotificationCenter provides an approach which is further decoupled. The typical approach used with NSNotificationCenter is that any object can send a notification to the center. At the same time, any object could be listening for notifications on that center.

Sending a notification looks like this:

[[NSNotificationCenter defaultCenter]

and registering for receiving looks like this:

[[NSNotificationCenter defaultCenter]

when registering for a notification, you can specify a specific broadcaster object but you don't have to do so. You may notice the defaultCenter. In reality, this is the only center you'll use. Notifications are intended to be open to the whole application, so there is only one center.

There is also an NSDistributedNotificationCenter. This is for communicating between applications. There is only one of these on the whole computer.

See Notification Programming Topics for Cocoa for more.

Advantages: neither the sender nor receiver of notifications needs to know about the other. Can specify the exact method to receive the notification. Notification name can be any string value. Disadvantages: slightly more code than Key Value Observing. You still need to remove listeners before they are deleted.

Context notifications

In the case where the property being observed is a declared property of an NSManagedObject, it is possible to listen to NSManagedObjectContextObjectsDidChangeNotification. Technically, this is still using the NSNotification approach but it is a slightly different approach because the NSManagedObject does not manually send the notifications.

Registering for this approach looks like this:

[[NSNotificationCenter defaultCenter]

And then in receivingMethodOnListener:, the NSInsertedObjectsKey, NSUpdatedObjectsKey and NSDeletedObjectsKey keys in the notification's userInfo will give the sets of objects which have changed.

See NSManagedObjectContext Class Reference for more.

Advantages: easiest way to track changes across an entire NSManagedObjectContext. Disadvantages: only works for Core Data and does not provide information more specific than the affected object.

Delegates used for observing

The final observer pattern Cocoa makes easy are delegates. In a broad sense delegates are intended to handle more than simply "observations" but they don't always need to do more.

For example, all of the notifications that NSApplication and NSWindow are also sent to their delegate and could be handled there instead. Some classes send notification-like message to their delegates that are never sent as notifications. For example NSMenu, sends menuWillOpen: to its delegate but does not send an equivalent NSNotification.

To connect a delegate, just invoke:

[object setDelegate:delegateObject];

on an object which supports a delegate. The delegateObject can then receive any of the delegate messages it wants.

See Cocoa Fundamentals Guide: Delegates and Data Sources for more.

Advantages: detailed and specific information from classes which support it. Disadvantages: the class must support a delegate. Only one delegate may be connected to an object at a time.