Xcode Project Template Expansion Macros

Earlier today, I lazy-tweeted to see if anyone had a definitive list of Xcode's project expansion macros. If you open up a project template and poke around, you'll see both in filenames and in file contents, these all-cap words surrounded by three underscores like ___PROJECTNAME___. These are replacement macros that get replaced with some other value when you create your project based on that template. ___PROJECTNAME___, for example, gets replaced with the name of the project as it was typed in by the user into the new project assistant.

I've assembled from a few different sources a list of all the known macros.

Token	Replaced By
___PROJECTNAMEASIDENTIFIER___	The project name with spaces and any filename-illegal characters replaced by underscores.
___PROJECTNAME___	The project name exactly as entered by the user when the project was created.
___PROJECTNAMEASXML___	The project name exactly as entered by the user when the project was created, but with converted using XML encoding so that it's legal XML.
___FULLUSERNAME___	The long user name of the developer who created the project pulled from the account information.
___USERNAME___	The short user name of the developer who created the project.
___TIME___	The time of the day at which the project was created.
___DATE___	The date on which the project was created.
___YEAR___	The four-digit year in which the project was created.
___ORGANIZATIONNAME___	The name of the company or organization for which the developer works (SEE SIDEBAR).
___UUID___	A generated unique identifier for your project.
___UUIDASIDENTIFIER___	The same unique identifier as ___UUID___, but with spaces and illegal characters converted to underscores.

One of the values in that table, however, doesn't belong there. I've included it (___ORGANIZATIONNAME___) because Apple uses it in most (all?) of their own Xcode templates, but it's not a built-in value like the others with a set meaning. It's a custom macro and (as you may know) you have to manually add it to Xcode's list of macros to get it to work. To make things more confusing, there's no place in Xcode where you can actually set this value (that I know of, at least).

To define the organization name that will be used in place of the ___ORGANIZATIONNAME___replacement token that's used in Apple's provided templates, you have to drop down to the terminal and type something like:

defaults write com.apple.Xcode PBXCustomTemplateMacroDefinitions '{ "ORGANIZATIONNAME" = "Naked Software, Inc.";}'

That's a pain, but the good news is, this mechanism is generic. It works for any replacement token you want to define. You could, for example, type this command in the terminal:

defaults write com.apple.Xcode PBXCustomTemplateMacroDefinitions '{ "MYTESTTOKEN" = "Hee Haw";}'

And anywhere in a project templates where you included ___MYTESTTOKEN___ in a filename or as part of a file's contents, Xcode would substitute Hee Haw for it.

If you want to find out what expansion macros you have defined, you can do this:

defaults read com.apple.Xcode PBXCustomTemplateMacroDefinitions

Now, in reality, there's a limit to just how useful this feature is. Apple's not likely to start using custom tokens other than ___ORGANIZATIONNAME___ and for your own templates, you can put whatever the hell you want in there, so unless you have machine- or user-specific data to insert into new projects, you'll probably never actually use this feature further than to define ___ORGANIZATIONNAME___, but it's nice to know it's there and understand what's going on a little better under the hood.

Matt Gemmell and two commenters reminded me that organization name IS now exposed in Xcode starting with 3.2 and that if it's not set, Xcode will pull it from your card in Address Book, so ___COMPANYNAME___ does belong in the list. The rest of the above is still true, however.