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'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

NimbusKit/xcodetemplate-spec