Best. Template. Ever.
August 21st, 2006Something I’ve been meaning to do for a long, long time, is set up some custom project templates in Xcode. The problem is, it doesn’t really take that long to tweak all the little things in a new project, so when I’m in the mood to start something new, I usually just go through all the grunt steps.
Today I decided to put together a template that should cover at least 90% of the grunt work for typical applications I start work on. I started with a great example from Jon Wight of Toxic Software. His “CocoaApp” template did a lot of the things I wanted to do, but lacked a few whistles and bells. I thought I’d just work from his and it would be easy.
Instead it was amazingly, unbelievably difficult. The major complication comes from persuading Xcode’s template manager to actually do the substitutions it promises to do. See, at the root of the template system is this behavior where Xcode will replace certain tags in your files with appropriate values for the new project. The tags are surrounded by French quotes, chevrons, whatever … you know: «these». That’s fine, but depending on whether the file is in MacRoman, UTF-8, or UTF-16 format, the chevrons are a different value. Ugh, it’s infuriating the way they would sneak back and forth. I still don’t quite understand the logic applied by Xcode in deciding which encoding to look for, when. To make matters more complicated, I strived for (and accomplished) something truly amazing: an end to the “NewApplication” text in new project nib files. To achieve this I had to save the nib as XML format, but even then it was difficult to get the files into a suitable format that was still parseable as XML, yet would satisfy Xcode’s template system. This is so fragile that the nib files in the template are not even openable in Interface Builder – so unfortunately you won’t be able to tweak them without some serious hacking.
But the end result is nothing short of amazing, I’m proud to say. Download the Red Sweater Cocoa Application template and install it on your system. Then, when you go to create your next project, enjoy all the following frills right from the start:
- Automatically names all menu items in MainMenu.nib. No more “NewApplication”!
- Automatically instantiates a delegate class named [AppName]Delegate, connected as the delegate from NSApplication, and creates the supporting source files.
- Automatically creates an AppleScript scripting definition, pointed at by the Info.plist. The scripting definition contains a skeletal dictionary with a “[AppName] Suite”, ready for you to expose your model through.
- Automatically sets the CFBundleVersion to the subversion build number through a script build phase.
- Centralizes the marketing version in one build setting called “APPLICATION_VERSION.” Just change this build setting to easily update your release version.
- Presets the application icon name to [AppName]. Just pop in a [AppName].icns file.
I think that covers it. I have kindly left out the private framework references to my Red Sweater frameworks. You should be able to edit the “Cocoa Application.pbproj” to fine-tune things to your liking, but be sure to remove the “acct.pbuser” files from within it after you do so, these have a habit of bringing some nasty values into the template which won’t get replaced by the template system.
August 21st, 2006 at 4:50 pm
Just wanted to say thanks!
August 21st, 2006 at 5:33 pm
I have got to try that. Too bad I don’t have new applications to start ;-)
August 21st, 2006 at 5:34 pm
I forgot to add: thanks for sharing it!
August 21st, 2006 at 6:32 pm
Sounds like a great template, much better than mine.
Nit: setting CFBundleVersion to the subversion revision number is probably A Bad Idea. svn revision numbers *always* march forward in time, which means if you release a bug-fix 1.5.1 after you release 2.0, Launch Services will think 1.5.1 of your app is the latest+greatest. Dave wrote about it here: http://www.dribin.org/dave/blog/archives/2006/08/02/versioning_os_x_apps/
The svn revision is still ultra-handy, so probably stick it in your CFBundleShortVersionString, which can be pretty much anything (it’s not interpreted by Launch Services).
See also: my script for loss-lessly translating human version numbers (1.2.3b4) into Launch Services-happy CFBundleVersion numbers, based on Dave’s findings: http://svn.sourceforge.net/viewvc/redshed/trunk/human_version_to_cfbundle_version/human_version_to_cfbundle_version.rb?revision=138&view=markup
August 21st, 2006 at 8:07 pm
Thanks, rentzsch. I have had a sneaking fear that something was not quite right about the subversion revision numbers as CFBundleVersion. It seems obvious now that you point it out – I will have to read through that Dave Dribin article and re-evaluate.
August 21st, 2006 at 8:58 pm
[…] Best. Template. Ever.: […]
August 22nd, 2006 at 7:38 am
I couldn’t open your MainMenu.nib in IB. Then I realized that my project name had a space. In the file classes.nib, the old-style property-list does not understand values with spaces unless you double-quote them.
So inside MainMenu.nib, in the classes.nib file, I double-quoted “«PROJECTNAME»Delegate” and it works. I also discovered that if you save classes.nib in real XML format, IB can still read the nib file (in this case, you don’t need to quote strings).
August 22nd, 2006 at 7:54 am
Does it break if you don’t use subversion?
August 22nd, 2006 at 8:02 am
Romain: thanks for catching that! Indeed, all my testing had been with spaceless project names. I have fixed the template with the quoting you suggested and it works! The download has been updated so nobody else should run into this in the future.
Jon: yeah the resulting projects will probably break during build if there is no svn installed. You can just open up the “Cocoa Application.pbproj” and remove that “Set Version” build phase script. As I said above be sure to remove any Xcode user prefs that get stashed in there as a result of editing it.
August 22nd, 2006 at 8:13 am
Romain: Your “space in the name” case brings up some other issues where the template falls down. Naming the app delegate Delegate for instance. I guess at least these are relatively minor tweaks, but I wonder if there’s a way to get the template system to substitute “project name without spaces.”
August 29th, 2006 at 1:56 am
Don’t know, if this is a shortcoming of Xcode, but the InfoPlist.strings file shows up garbled, so you have to manually set the encoding to UTF-16 to use it, not sure if there is a fix for that?
August 29th, 2006 at 6:46 am
Hi Kusmi, I noticed that too. For some reason it seems to lose its encoding on the way from template to project. I’ll see if there’s anything I can do about that.