Making custom templates for Xcode 4 – March 2011

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:

  1. Apple has changed the locations of EVERYTHING
  2. Apple has changed the format of EVERYTHING
  3. 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

Why?

  1. Apple has made incompatible changes to the Xcode 3 templates system, so all the “old” articles no longer work
  2. …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

How?

  1. 2012: Find your copy of Xcode 4 (the app itself – usually in Applications), and right click “Show Package Contents”
  2. 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
  3. (previously: Go to /Developer/Library/Xcode )
  4. 2012: Un-hide your Library folder (google if you don’t know how, or else do this from Terminal)
  5. Go to ~/Library/Developer/Xcode
  6. Copy/Paste ONE OF the “Templates” folders into this folder
  7. 2012:
    • 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)
  8. 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…

  1. The File Templates are all stored in “File Templates/”
  2. When you do “new file” Xcode displays one entry in the sidebar for each sub-folder of “File Templates/”
  3. When you select a sidebar item, Xcode looks in that subfolder, and creates one icon for every sub-subfolder whose name ends in “.xctemplate”

How?

  1. Pick a sub-folder you want to customize, and rename it
  2. 2012: you’ve already had to rename it … previous versions allowed you to keep the names the same, Apple now prevents this
  3. e.g. I renamed “Cocoa” to “Adam’s Cocoa”

Test?

  1. Try creating a new file in Xcode
  2. …notice that you have a new sidebar entry
  3. ……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!)

How?

  1. 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
  2. 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
  3. 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:

  1. place it inside the .xctemplate folder

To add files that only apply to your template SOMETIMES, depending on what options the user chose:

  1. invent an internal name for the option
  2. create a subfolder of .xctemplate folder, give it that internal name
  3. 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

  1. I’d recommend copy/pasting the one from : “File Templates/Cocoa/Objective-C class.xctemplate/TemplateInfo.plist
    1. note how there 5 options, and 5 subfolders with the same name

15 thoughts on “Making custom templates for Xcode 4 – March 2011

  1. Thanks for this. Is there any more information on how to control the GUI prompts? Specifically, I’d like to add a “description” field, where I can type some documentation for the class, and have it replace a keyword as a string within the class as well as a documentation comment for doxygen…

  2. @Ethan – I’ve only briefly experimented with that part so far, nothing useful to report yet. If/when I find stuff that works, I’ll post again

  3. The old «FILENAME» «PROJECTNAME», etc. identifiers don’t appear to work anymore, which is a shame. I’ll see if i can find an alternative if there isn’t one already

  4. Thank you for figuring out the new location! I had no trouble adopting the new macros, but I’d been flailing about all morning trying to figure out where to put them :(

  5. Huh. They put iOS templates elsewhere. Grr:

    ./Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates/

  6. Well, apple have removed the /Developer folder, so everyone’s tutorials are wrong AGAIN.

    I have no idea where the class templates are now :(

  7. (for people following by email)

    I’ve just updated the locations for Xcode 4.3, 4.4 and 4.5. Apple changed the locations completely, no documentation (as usual).

    Also, the process is MORE DIFFICULT than it used to be (again: thanks, Apple!)

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>