UPDATED 2012: Apple broke it all AGAIN (again). New locations below
Xcode 4 is here – yay!
Apple’s templates for Xcode are still poor, inserting C-style comments and VERY annoying fake “copyright” messages in every file – boo!
Xcode 4 has a massively improved templates system – yay!
No-one knows how it works – … oh.
So, after a load of trial and error, here’s a step-by-step guide. If I find better docs from Apple on how to do this, I’ll add a link HERE. (not found them yet, though).
Before we start, some observations:
- Apple has changed the locations of EVERYTHING
- Apple has changed the format of EVERYTHING
- Whenever you upgrade Xcode, if you didn’t take precautions up-front, Apple will DELETE ALL your templates
- (this is a feature, not a bug – just happens to be a very annoying feature – it’s a pity Apple didn’t include a “WARNING: About to delete your custom settings! Are you sure?” dialog in the Xcode installer)
0. DO NOT blindly read the links on Google for this topic
- Apple has made incompatible changes to the Xcode 3 templates system, so all the “old” articles no longer work
- …but they also changed the Xcode 4 system just before launching, so that most of the “new” articles don’t work either!
Um…? Yeah. Apple always does this. It’s an improvement (reading the Google links, the Xcode 4 beta process was a bit harder to follow), but it’s still a PITA that all the tutorials are now broken.
1. Grab the existing templates, and “convert” them to “personal” templates
Why? Apple will NOT delete “personal” templates during Xcode upgrades
- 2012: Find your copy of Xcode 4 (the app itself – usually in Applications), and right click “Show Package Contents”
- 2012: Navigate in there until you find the “Templates” sub folder. There are two folders, one for Mac, the other for iPhone
- Mac location: [Xcode4.app]/Contents/Developer/Library/Xcode/Templates
- iPhone location: [Xcode4.app]/Contents/Developer/Platforms/iPhoneOS.Platform/Developer/Library/Xcode/Templates
- (previously: Go to /Developer/Library/Xcode )
- 2012: Un-hide your Library folder (google if you don’t know how, or else do this from Terminal)
- Go to ~/Library/Developer/Xcode
- Copy/Paste ONE OF the “Templates” folders into this folder
- Go into the “File Templates” folder, and RENAME EVERY SUB-FOLDER
- (if you do not do this, as of 2012, Apple will DELETE/IGNORE your templates. In previous versions, they’d at least honour the File Templates)
- 2012: … if you want *both* OS X *and* iOS custom templates, repeat the above with the other “Templates” folder
(REMOVED: all the text here about testing the above – Apple broke most of it, so it’s not worth using any more)
2. Re-categorize your templates so you can find them in Xcode GUI
We’ll start with File Templates…
- The File Templates are all stored in “File Templates/”
- When you do “new file” Xcode displays one entry in the sidebar for each sub-folder of “File Templates/”
- When you select a sidebar item, Xcode looks in that subfolder, and creates one icon for every sub-subfolder whose name ends in “.xctemplate”
- Pick a sub-folder you want to customize, and rename it
- 2012: you’ve already had to rename it … previous versions allowed you to keep the names the same, Apple now prevents this
- e.g. I renamed “Cocoa” to “Adam’s Cocoa”
- Try creating a new file in Xcode
- …notice that you have a new sidebar entry
- ……which contains all the normal templates from the Cocoa section
3. Edit your templates to your heart’s content
The new template system is a LOT better than the old one. The old one was a nice idea (it could be opened directly inside Xcode), but … it had a lot of bugs. Try changing the NIB files in Xcode3, for instance (as soon as you save one, Xcode screws up the auto-filename generation for that template).
There’s two things you have to edit, separately (and they SHOULD be separate! This is a good thing!)
- The “TemplateInfo.plist” file contains all the options for the template, and lets you build custom GUI questions that’ll appear in the New File wizard
- If your TemplateInfo.plist file lists “optional” versions of the template, with different sets of files, Xcode will look for subfolders named after the option that the user chose, and use ONLY the files in the one that matches
- ALL OTHER FILES in the .xctemplate folder will be copied directly across to the new project
So, to add a new file that applies to your template ALWAYS:
- place it inside the .xctemplate folder
To add files that only apply to your template SOMETIMES, depending on what options the user chose:
- invent an internal name for the option
- create a subfolder of .xctemplate folder, give it that internal name
- edit your TemplateInfo.plist file and add an Options section that allows the user to select this option (see below)
To add an Options section
- I’d recommend copy/pasting the one from : “File Templates/Cocoa/Objective-C class.xctemplate/TemplateInfo.plist
- note how there 5 options, and 5 subfolders with the same name