// TODO: make sure file exists before opening!
fooBar = [[FooBar alloc] initWithFile:path];

This is a reasonable thing to do, because sometimes you just want to get something working right now and aren’t in the mood to write all the required error checking code. But, you also know that you cannot trust your soft human brain to remember to add the check later, so you write a comment to remind yourself to do it.

Xcode recognizes the TODO: keyword in your comments and helpfully adds items to the function popup menu so that you can quickly navigate to them. In addition to TODO:, Xcode will also recognize FIXME: (when you know the code is broken), ???: (when you don’t know what it does), and !!!: (when you wish you didn’t know).

That’s helpful when you’re editing a file, but what about a TODO tucked away in some dark corner of your source code that you haven’t visited in a while? You’re likely to forget about it, and how can you keep a promise you forgot that you made?

The answer, of course, is to have somebody nag you. Fortunately, there’s a way to have Xcode fill that role. All you have to do is add a simple Run Script Build Phase which turns them into Build Warnings.

Select Project > New Build Phase > New Run Script Build Phase from the menu bar. Then, copy and paste this into the script window:

1
2
3
4

KEYWORDS="TODO:|FIXME:|\?\?\?:|\!\!\!:"
find ${SRCROOT} \( -name "*.h" -or -name "*.m" \) -print0 | \
    xargs -0 egrep --with-filename --line-number --only-matching "($KEYWORDS).*\$" | \
    perl -p -e "s/($KEYWORDS)/ warning: \$1/"

What does it mean?

Line 1 defines the keywords we want to search for. If you want to exclude a keyword or include a different one, edit this line.

Line 2 uses the find command to generate a list of all files in your project directory (SRCROOT) having an .h or .m extension. If you want to search more files, you will need to edit this line.

Line 3 uses xargs to pass those file names along to egrep, which searches inside the files for lines containing one of the keywords. If any are found, it outputs the file name, line number, and the matching part of the line.

Line 4 uses Perl to format the lines as warnings.

The output of the script will look like this:

/Users/benzado/Projects/FooBart/Baz.m:42: warning: TODO: make sure file exists before opening!

Xcode will recognize lines in this format and treat them as first class build warnings. You can see them in the Build Results panel and, just like a warning from the compiler, a double click will open an editor window and take you directly to the offending line.

An Exercise For The Enterprising Reader: modify the script so that no warnings or errors are reported during Debug builds, but TODOs are flagged as errors in Release builds.

Your iPhone app includes a Settings bundle, so that you can keep your application simple and leave the settings in the settings app. Specifically, you allow the user to customize the FooColor setting, with a default value of Red.

Initially, the user defaults database doesn’t contain a value for FooColor. Although you defined a default value in the Settings bundle, only the Settings app pays any attention to it.

Take Note: Cocoa uses the term “user defaults” to refer to application settings in general. Don’t confuse that with the notion of a default value, which is the initial value of a setting before it has been changed through user action.

The proper way to load default values at runtime is to use NSUserDefaults’s registerDefaults: method. It takes a single NSDictionary object and merges it into the user defaults registration domain. (The user defaults database is divided into domains, or layers.) Values in the registration domain are only used if they are not defined anywhere else, so you don’t need to worry about overwriting a user’s preference.

You create a property list file named Defaults.plist, define an entry giving “FooColor” the value “Red”, and load it:

NSString *path = [[NSBundle mainBundle] pathForResource:@"Defaults" ofType:@"plist"];
NSDictionary *dict = [NSDictionary dictionaryWithContentsOfFile:path];
[[NSUserDefaults standardUserDefaults] registerDefaults:dict];

The only problem with this set up is that you must keep your Settings bundle and Defaults.plist files in sync. If you change the default FooColor from Red to Blue, you must change both. If you add a new setting, you must add it to both. If you’ve been programming for more than a month, you know that eventually you will make a mistake which will lead to a bug that will take forever to track down and take years off your life.

Therefore, a better solution is to dynamically generate Defaults.plist from the data that is already in the Settings bundle. You can do so with ExtractDefaults.xsl, a simple stylesheet which creates an XML property list from a Settings bundle definition, and xsltproc, which is fortunately already installed on your Mac.

First, if you really did create a Defaults.plist, remove it from your project and delete the file. It’s graduating from a source file to a build product!

Then, select your target in Xcode. Go to the menu bar and select Project | New Build Phase | New Run Script Build Phase. A window appears. In the Script area, enter the following shell script:

SETTINGS_PLIST=$SRCROOT/Settings/Root.plist
XSL=$SRCROOT/ExtractDefaults.xsl
DEFAULTS_PLIST=${BUILT_PRODUCTS_DIR}/${WRAPPER_NAME}/Defaults.plist
xsltproc -o $DEFAULTS_PLIST $XSL $SETTINGS_PLIST
plutil -convert binary1 $DEFAULTS_PLIST

You may need to edit the first three lines, depending on the path to your Settings page file and where you saved ExtractDefaults.xsl. It’s also recommended that you fill in the Input Files and Output Files lists, so that Xcode can intelligently determine when the script needs to be run (when input files are newer than output files). Following the script above, Input Files should contain:

$(SRCROOT)/Settings/Root.plist
$(SRCROOT)/ExtractDefaults.xsl

Output Files should contain:

$(BUILT_PRODUCTS_DIR)/$(WRAPPER_NAME)/Defaults.plist

Note that Xcode needs round parenthesis around variable names, unlike the shell script, which uses nothing or curly braces. There’s a good reason for this, but I don’t know what it is.

That’s it! Now, when you build your app, the script will generate a Defaults.plist file inside of your app bundle, so it can be loaded by your code. And you won’t have to worry about your app defaults mismatching your Settings bundle defaults, because it is being handled by a machine, and machines never fail!

Mini-FAQ

Where do I get ExtractDefaults.xsl? Click here to download the file. It’s free to use for whatever you want to do with it. If you improve on it in some way, kindly let me know.

What if I have also default values not defined in my Settings bundle? You can manually enter them into another property list file, and load both. It’s totally cool to call registerDefaults: several times with different dictionaries. Totally cool!

What if my Settings bundle contains multiple page files? In that case you could run the script over each one, generating several Defaults.plist files, and load them all at runtime. Or, if you’re really clever, figure out some way to merge them all into a single property list at build time. I can’t do everything for you.

1. sudo -s
2. cd /usr/lib
3. tar cvf oldapr+svnlib.tar libapr* libsvn*
4. bzip2 oldapr+svnlib.tar
5. rm libapr* libsvn*
6. cd /opt/local/lib
7. for NAME in libapr*.dylib; do ln -s /opt/local/lib/$NAME /usr/lib/$NAME; done
8. for NAME in libsvn*.dylib; do ln -s /opt/local/lib/$NAME /usr/lib/$NAME; done
9. exit

Line 5 removes the existing subversion libraries and lines 6-8 put symlinks in /usr/lib that point to /opt/local/lib.  Note that the set of libraries may not match exactly.  (In my case, some libraries for Python and Ruby bindings didn’t appear in /opt/local/lib.)  However, I figure it’s better to keep the set consistent than to piece together possibly incompatible parts.