xcodetemplate spec

xcodetemplates are another area of Objective-C development that are a complete bitch to work with (see iOS-Framework). This doc is an attempt to bring some sanity to the process.

This document is a WIP and may never be finished. This file is the result of building the Xcode templates for NimbusKit and is mostly being used as a reference as those templates are being built.

Finding the Xcode Templates Directories

There are three directories you'll want to care about when building Xcode templates:

Objective-C and Mac templates

open "$(xcode-select -p)Library/Xcode/Templates"

iPhone templates

open "$(xcode-select -p)Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates"

User templates (where yours will go)

mkdir -p $HOME/Library/Developer/Xcode/Templates
open $HOME/Library/Developer/Xcode/Templates

How to Create a Template

The easiest way to create a new template is to clone one of the existing Apple ones and hack away at it.

Top-Level Nodes

Key	Type	Description	Example
Identifier	string	The unique identifier by which you can refer to a given template.	com.nimbuskit.template.nimbuskitBase
Kind	string	The kind of template this is. Always seems to be Xcode.Xcode3.ProjectTemplateUnitKind.	Xcode.Xcode3.ProjectTemplateUnitKind
Options	array	An array of dictionaries specifying UI options for configuring the project.	Options
Ancestors	array	An array of strings specifying template Identifiers that this template should inherit from.	<string>com.apple.dt.unit.bundleBase</string>

Options

Each element in an options node is a <dict> that may have the following fields:

Key	Type	Description	Example
Identifier	string	The unique identifier for this UI element. There is a list of built-in option identifiers that Xcode uses.	<string>productName</string>
Required	bool	Whether or not the user must fill in this field.	<true/>
Name	string	The displayed label identifying this field in the UI.	<string>Product Name</string>
NotPersisted	bool	If true, the field will not be persisted between creating new files/projects.	<true/>
Description	string	The alt-text for the field, made visible by hovering over the field's label.	<string>Your new product&apos;s name</string>
EmptyReplacement	string	Effectively a default, but not meant to actually be used. Generally paired with Required being true.	<string>ProductName</string>
Type	string	What kind of element this field should be.	<string>text</string>, <string>static</string>

Option Identifiers

Key	Description	Usage
productName	The name of the new application/framework/library.	___PACKAGENAME___
bundleIdentifierPrefix	The bundle identifier prefix.	___VARIABLE_bundleIdentifierPrefix:bundleIdentifier___
organizationName	The organization name.	___ORGANIZATIONNAME___
bundleIdentifier	An automatically created bundle identifier based on the bundleIdentifierPrefix and product name.
classPrefix	A prefix to be used when creating new classes.	___VARIABLE_classPrefix:identifier___

Option Examples

Text Field

<dict>
	<key>Identifier</key>
	<string>productName</string>
	<key>Required</key>
	<true/>
	<key>Name</key>
	<string>Product Name</string>
	<key>NotPersisted</key>
	<true/>
	<key>Description</key>
	<string>Your new product&apos;s name</string>
	<key>EmptyReplacement</key>
	<string>ProductName</string>
	<key>Type</key>
	<string>text</string>
</dict>

Static Label

<dict>
	<key>Identifier</key>
	<string>bundleIdentifier</string>
	<key>Name</key>
	<string>Bundle Identifier</string>
	<key>NotPersisted</key>
	<true/>
	<key>Description</key>
	<string>Your new product&apos;s bundle identifier</string>
	<key>Default</key>
	<string>___VARIABLE_bundleIdentifierPrefix:bundleIdentifier___.___VARIABLE_productName:RFC1034Identifier___</string>
	<key>Type</key>
	<string>static</string>
</dict>

Template Variables

Key	Description
___PACKAGENAME___	The name provided by the user via the productName option.
___PACKAGENAMEASIDENTIFIER___	___PACKAGENAME___ sanitized in some way.

Existing Templates

Base Templates

These templates are inherited from but can not be created themselves.

Identifier	Description
com.apple.dt.unit.base	The root template for Objective-C projects. Defines standard UI fields (productName, rganizationName, bundleIdentifierPrefix, and bundleIdentifier). Defines the precompiled header. Specifies a Debug and Release build.
com.apple.dt.unit.bundleBase	Defines the necessary fields for building a bundle (unit testing or application).
com.apple.dt.unit.objectiveCApplication	Defines the main.m file and standard resources for an Objective-C application.
com.apple.dt.unit.objectiveCUnitTestBundle	Provides UI for determining which unit testing feature to use (XCTest or OCUnit). Provides an empty unit test class implementation.
com.apple.dt.unit.prefixable	Defines UI for specifying a class prefix.
com.apple.dt.unit.iPhoneBase	Requires the iphoneos SDK and provides default supported orientations in the project's Info.plist.

Creatable Templates

These templates are exposed via the Xcode New Project/File dialog.

Identifier	Description
com.apple.dt.unit.cocoaTouchStaticLibrary	A static library project with com.apple.dt.unit.cocoaTouchFrameworkUnitTestBundle as a sub-target.
com.apple.dt.unit.cocoaTouchFrameworkUnitTestBundle	A static library unit test bundle.

Inheritance Tree

• com.apple.dt.unit.prefixable

• com.apple.dt.unit.iPhoneBase

• com.apple.dt.unit.base

• com.apple.dt.unit.bundleBase

  • com.apple.dt.unit.base

• com.apple.dt.unit.objectiveCApplication

  • com.apple.dt.unit.bundleBase
    • com.apple.dt.unit.base

• com.apple.dt.unit.objectiveCUnitTestBundle

  • com.apple.dt.unit.bundleBase
    • com.apple.dt.unit.base

• com.apple.dt.unit.cocoaTouchStaticLibrary

  • com.apple.dt.unit.iPhoneBase
  • com.apple.dt.unit.base

• com.apple.dt.unit.cocoaTouchFrameworkUnitTestBundle

  • com.apple.dt.unit.iPhoneBase
  • com.apple.dt.unit.objectiveCUnitTestBundle
    • com.apple.dt.unit.bundleBase
      • com.apple.dt.unit.base