— boreal-kiss.net

A minimal project template for Xcode 4

Introduction

Many people have their own project- and/or file-templates for practical or aesthetic reasons. For example I don’t like the naming convention provided by Apple such as XXXX-Info.plist, XXXX-Prefix.pch, and XXXXAppDelegate for the project XXXX. On Xcode 3.x. it was relatively easy to modify them. Since Xcode 4, however, Apple introduced a new template format that is no longer compatible with those of Xcode. 3.x. This has often become topics among Apple’s developer forums, since there is no official information provided. You can see how it changes from the Xcode 4 built-in templates. They are under

/Developer/Library/Xcode/Templates/

for Mac OS X stuffs and

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

for iOS. If you add your own templates, the place you should use is under the following path:

~/Library/Developer/Xcode/Templates/

The problem is that it is quite hard to create a custom template. For example, to copy and paste the built-in template to your place will not show up the template on Xcode 4 until you manually change its identifier in TemplateInfo.plist.

TemplateInfo.plist

TemplateInfo.plist is basically a setup file for a Xcode 4 project. When creating a project, Xcode 4 first reads this file to prepare all environment for you to get started. Each TemplateInfo.plist has own identifier for Xcode 4 to distinguish from others (and that’s why copy-and-pasting built-in template described above does not work as a user template). If you need your own templates, you should give them your own identifiers. For example, the Xcode 4 built-in template for window based iPhone application has the following identifier:

com.apple.dt.unit.windowBasedApplication

TemplateInfo.plist has something inheritance nature like classes of programming languages (and the identifier corresponds to the name of class). Xcode 4 reads a given TemplateInfo.plist and aggregates data from its ancestral files. For example, the following figure shows pedigree charts for the built-in window based iPhone application template.

com.apple.Templates

You can see that the TemplateInfo.plist for the window based iPhone application template is the sixth generation from the top-most base file (com.apple.dt.unit.base). This demonstrates that when you want to customize a given TemplateInfo.plist and the place you want to change within comes from the ancestral files, you have to manipulate multiple files, i.e., it could be error prone. Since TemplateInfo.plist is just an XML file, there is no compile errors. Moreover the inheritance nature of XML files has no readability at all. In fact it seems Apple creates them not by coding but by automatic generation tools.

A minimal project template

This was originally just for me but since it founds to be useful I will share this with someone who wants to have own templates on Xcode 4. This contains several templates within but only shows up one window based application template on Xcode 4 (the identifier is com.borealkiss.windowBasedApplication), because the others are not a concrete template (there are abstract templates not to be actually implemented). The following figure shows the contents (gray and orange ones are included):

om.borealkiss.Templates

This template enables you to manipulate in the old way as of Xcode 3.x, i.e., editing actual files and adding onto templates. Basically you only have to manipulate the TemplateInfo.plist of com.borealkiss.windowBasedApplication. You can add whatever files you want as long as you do the following edits. For example, if you want add a given file called SomeClass.m, you add the following two parts into the TemplateInfo.plist of com.borealkiss.windowBasedApplication:

These are the definition part of the file:

<key>Definitions</key>
<dict>
	<key>SomeClass.m</key>
	<dict>
		<key>Path</key>
		<string>SomeClass.m</string>
	</dict>
</dict>

and its actual implementation:

<key>Nodes</key>
<array>
	<string>SomeClass.m</string>
</array>

If you want to add the file but not for the target of Copy Bundle Resources (like Info.plist, Prefix.pch, and header files), change the definition as follows:

<key>Definitions</key>
<dict>
	<key>SomeClass.m</key>
	<dict>
		<key>Path</key>
		<string>SomeClass.m</string>
		<key>TargetIndices</key>
		<array/>
	</dict>
</dict>

You can add it inside a given folder. For example if you want to add the file inside a directory called MyClasses, change the definition as follows (note that the key name should be consistent with the actual file path, otherwise the file location in the project will be different from that seen in the Finder’s view):

<key>Definitions</key>
<dict>
	<key>MyClasses/SomeClass.m</key>
	<dict>
		<key>Group</key>
		<string>MyClasses</string>
		<key>Path</key>
		<string>MyClasses/SomeClass.m</string>
	</dict>
</dict>
<key>Nodes</key>
<array>
	<string>MyClasses/SomeClass.m</string>
</array>

[Update on 06.04.2011]

Some reader gave me a tip how to add files in a subgroup (i.e., the group inside a group). As an example consider the following situation; you are adding the SomeClass.m file that is in the location below and wanting to add it in the same directory.

Classes/SomeClass/SomeClass.m

In this case you can do this by changing a definition part:

<key>Definitions</key>
<dict>
	<key>Classes/SomeClass/SomeClass.m</key>
	<dict>
		<key>Group</key>
		<array>
			<string>Classes</string>
			<string>SomeClass</string>
		</array>
		<key>Path</key>
		<string>Classes/SomeClass/SomeClass.m</string>
	</dict>
</dict>

and its nodes part:

<key>Nodes</key>
<array>
	<string>Classes/SomeClass/SomeClass.m</string>
</array>

I also added these examples on my templates (link listed at the bottom).

Caution before editing

Keep in mind that TemplateInfo.plist is a setup file for Xcode 4 and any invalid manipulation would cause unexpected actions. For example, the following figure shows a normal behaviour of Xcode 4 during a new project creation, showing a product name and company identifier input (other options such as unit testing are disabled). And pushing the next button asks you which directory to create the project (as expected).

Normal behaviour of Xcode 4

The following wizard pane is abnormal one after some ill manipulation. No product name input is found. Fortunately you cannot go further by pushing the next button.

Abnormal behaviour of Xcode 4

However the worst case happens when you could go further. Even if you meet the situation, do NOT push the next button; Xcode 4 creates a project inside the directory you intend to place the project. For example the directory you are placing your project folder is Desktop, Desktop will become the project folder and other irrelevant files will be gone. I had two times desktop-sweeping during the try-and-error manipulation. Be careful.

Downloads

License

This template is provided under the terms of the MIT license for the reason above, i.e., feel free to use it but at your own risk.

49 comments
  1. [...] A minimal project template for Xcode 4 [...]

  2. Jose Lobato says: March 13, 20117:10 am

    Hey!!
    Great Job. Thanks for taking the time to share this.

    I’m quite happy with the standard stuff but it is always good to know a bit more how it works.

    • borealkiss says: March 14, 20115:06 am

      Thanks Jose, I will dig it more.

  3. Luca says: March 14, 20114:59 am

    Hi, nice work!!

    Just wondering: do you think it’s possible to customize targets and run script phases in the project template? I had two custom targets and a run script phase which worked perfectly with previous template structure but I can’t figure out how to port them to this new structure, mainly because I can’t open the template itself with Xcode (the targets are somewhat complicated, it could become difficult to write them as direct xml…). Do you have any suggestions?

    Thanks!

    • borealkiss says: March 14, 20115:14 am

      Luca, I am afraid but I have no idea, since I inferred the data structure only from the Apple’s templates that don’t have such stuffs. If they have I could find something.

      • Luca says: March 14, 20116:36 am

        Thanks for the quick reply, that was my thought too… Perhaps I should try another way!

  4. Steven says: March 14, 20114:01 pm

    Funny to see that other people have found out the same lovely template bug to completely clear your desktop contents (thank Apple for TimeMachine :P )

    Hoping to see more of these tutorials around the web with more details of the new template structure.

    • borealkiss says: March 17, 20112:04 pm

      Steven, yeah It’s really sensitive and I think that is the reason why Apple don’t give us any information on templates.

  5. Andy Peters says: March 15, 20119:40 pm

    Thanks for the write up and the starting point. Honestly the diagrams you did were the best thing in the world. I’m sure at some point we will all think this new templating system makes sense but damn… it takes a lot of deciphering since there is nothing to help us along. Except posts like yours.

    Also, I agree.. i hate XXXXAppDelegate and prefer AppDelegate myself.

    • borealkiss says: March 17, 20112:10 pm

      Andy, it’s really nice to hear that. It might be also a good idea to look inside templates by the cocos2d team. They are really fast to evolve.

  6. Quentin says: March 17, 201112:49 pm

    Hi,

    Thank you for this post, it really helps me. I would like to go a little further, and I would like to know if someone has succeed to add a Target Dependencies.

    Regards,
    Quentin

    • borealkiss says: March 17, 20112:17 pm

      Quentin, sorry but I have no idea. The following link might be helpful for you.

      cocos2d-iphone – GitHub

  7. Random says: March 17, 201111:18 pm

    Do you know how to create file templates? (Not project templates.)

    • borealkiss says: March 18, 20112:02 am

      I haven’t tried them yet but must be the same.

  8. buddy says: April 5, 20113:46 am

    hi, thanks you for this post. i have tried this and success make a simple project template. i have a question about adding subgroup. let’s say we will add Children group under the Parent group, i tried many ways but the Children still in root level (equal level with Parent). can u help me with this problem?? i have searching in many article they’re not example about this..thanks

    *sorry for my english, :D

    • borealkiss says: April 5, 20117:08 am

      buddy, I haven’t found it yet. The easiest place to get answers might be apple’s forum. Good luck.

      • buddy says: April 5, 201111:16 pm

        Finally i found the solution, after many time i tried. here you are:

        Definition section:
        Definitions

        main.h

        Path
        main.h
        Group

        parent
        child

        in the node section:

        Nodes

        main.h

        • buddy says: April 5, 201111:18 pm

          @.@ ops..the tags isn’t show

        • borealkiss says: April 6, 20113:30 am

          buddy, great job. I added the tip in the post and also updated my template.

  9. mysticpopov says: April 6, 20119:47 am

    does anyone know how to include a .dylib file such as libsqlite3.0 ? i have managed to add Frameworks, but cannot figure out libraries. also, thanks for the nested group info, it was one of the headaches i was having.

    • Edouard Lavery Plante says: July 21, 201112:39 pm

      Did you find a solution to adding a .dylib file? I’ve even bought the Xcode 4 template documentation from cocos 2d and couldn’t find anything about that.

      Anyone has an idea?

      • borealkiss says: July 21, 201112:44 pm

        No, I didn’t.

      • Cabaalo says: July 6, 20125:08 am

        Push ;)

        I have the same problem. Everybody has an idea to adding a .dylib file?

    • Ankit Bhardwaj says: December 22, 20118:33 am

      add this tag into Targets —> Shared Settings

      -ObjC -all_load -weak_library /usr/lib/libz.dylib -weak_library /usr/lib/libxml2.dylib -weak_library /usr/lib/libsqlite3.dylib

      Cheers
      Ankit

      • Ankit Bhardwaj says: December 22, 20118:34 am

        put this with Key OTHER_LDFLAGS & above value

  10. [...] A minimal project template for Xcode 4 Published: 4月 9, 2011 Filed Under: 未分類 Tags: iPhone : Xcode Leave a Comment Name: Required [...]

  11. Doug says: April 11, 20113:03 pm

    Your blog got me interested in trying to make a “New File” template. It turns out to be quite simple (XCode 4). Simply copy one of the existing File Template directories (e.g. the one found at /Developer/Library/Xcode/Templates/File Templates/Cocoa called Objective-C class.xctemplate). Rename it to something (e.g. New Objective-C class.xctemplate). Now you have another choice in the “New File” dialog.

    To actually change the template, navigate down to the actual *.h and *.m files and open/edit/save them using XCode.

    Naturally all of this goes away if you re-install XCode. My next stop is to figure out where to put the modified file templates so that XCode will find them and a re-install won’t overwrite them.

  12. [...] Minimal Project Template with example [...]

  13. bl00dyg33k says: April 21, 20117:38 pm

    Great article! I’m trying to make a template for use with the Free Pascal Complier (I know it’s an old programming language and all – I’m just a beginner and it’s for school). I followed a post at http://bit.ly/fdUtKI, but couldn’t get a solution. I included the TemplateInfo.plist file and modified it according to instructions – all to no avail. Any suggestions?

    P.S. 日本語メイン、それとも英語メイン?英語の方に慣れてそうだけど:D

    • borealkiss says: April 22, 20111:52 am

      I don’t recommend creating templates from scratch, as any small mistake (even by single character) will cause a problem without giving you clues what the problem is. The better way might be the following;

      - Strip unnecessary part from a working template step by step.
      - After each small change, check it whether it works.

      By doing this you will have a good grasp what an Xcode 4 template is in order for you to create your own. I know it’s time consuming but steady. Also make sure you give your templates unique identifiers.

      最近は英語がメインですね。

  14. Guillermo Moral says: May 31, 201112:22 pm

    How can I work with code completion in Xcode 4 when I create a new project using a Template and have a static library.

    I created a new template that uses static library but when I create a new project the code completion doesn’t work for static library. I can build and run the new project well.

    This is an example how to add static library in a template with XCode 4.

    Configurations

    Debug

    HEADER_SEARCH_PATHS

    /Users/xxx/xxx/headers

    LIBRARY_SEARCH_PATHS

    /Users/xxx/xxx/lib/4.2/Debug-iphonesimulator

    OTHER_LDFLAGS

    -all_load -lxml2 -lMyLib

    Release

    HEADER_SEARCH_PATHS

    /Users/xxx/xxx/headers

    LIBRARY_SEARCH_PATHS

    /Users/xxx/xxx/lib/4.2/Debug-iphonesimulator

    VALIDATE_PRODUCT

    YES

    OTHER_LDFLAGS

    -all_load -lxml2 -lMyLib

    Thanking you in advance.

    • borealkiss says: May 31, 20111:42 pm

      Guillermo, it’s beyond the scope of the article. I’m not sure but static libraries are not compatible with auto completion but frameworks.

  15. dcolumbus says: July 4, 20114:13 pm

    So far I’m seeing that most people are just creating Templates for C and Obj-C … I’d love to be able to put together Templates for ColdFusion development. Is this possible?

    • borealkiss says: July 4, 20114:27 pm

      It could be possible. Just try it.

      • dcolumbus says: July 4, 20114:30 pm

        Well, I have… but certain parameters in the plist just don’t apply or make sense. The Template type will show up, but Xcode won’t show anything but .c and .h files.

  16. Willem says: August 1, 20117:33 am

    I really like you explanation and I’ve created my own templates.
    But I have problem creating groups.
    I would like a project templates which also creates a project structure. I’m able to create a group, but when I create a group a file with the same name is also created inside the group.

    Any ideas?

    • borealkiss says: August 1, 20118:57 am

      Confirm you don’t have such a file in the Definitions and Nodes part. Remove it if exists.

  17. olemoritz says: August 11, 20111:51 am

    Thanks for this article! I’ve built my own little set of templates based on this and a fair amount of experimentation.

    Although I don’t understand the system completely yet, I’ve had some success with configuring options like a popup for device family and a checkbox for Core Data.

    I also changed the bundle identifier in the Info.plist to be dynamic, based on the project name and company identifier, like in the built-in templates.

    In case anyone is interested, I’ve put my efforts on GitHub: https://github.com/omz/MinimalisticXcodeTemplates – A lot of this is just my personal preference, but the customization options might be useful to others as well.

  18. Automating Xcode 4 Template Generation says: August 16, 20115:36 am

    [...] obscure process. In order to understand a bit more, I followed the Boreal’s Kiss “A minimal project template for Xcode 4” article. After reading it, I realized that since our toolset was changing quite often, we [...]

  19. Glenn says: August 16, 20116:02 pm

    Anyone have any idea how to make the Definitions section define a folder reference?

  20. Mike says: August 29, 201111:16 am

    Is it possible to change the default Deployment target this way?

  21. Rei Vilo says: November 1, 20118:25 am

    Hi!

    I used Xcode 3 to program my Arduino using a template with the AVR tool-chain and the right Makefile.

    It worked fine. See http://bit.ly/s4uASG.

    But with Xcode 4, everything has changed for the template and I’m lost.

    Does any reader try and write a template for Arduino?

  22. [...] My project template for iOS working on Xcode 4 has been updated. I use a storyboard file (iOS 5 and later) rather than xib. If you are not familiar with storybords, the following guide will be helpful: [...]

  23. [...] Xcode 4 completely changed the (project) template system. There’s a lot more you can do now, but it comes at a price. Take a look in the TemplateInfo.plist files scattered around your /Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates/Project Templates/Application folder and you’ll quickly lose the perspective. The new setup is very hard to modify, even harder to re-create. The writer of boreal-kiss.net has a real good post about the new structure. [...]

  24. Custom XCode Project Templates | FishLamp says: September 12, 20126:27 pm

    [...] A recipe for creating a minimal project template  [...]

  25. bazz says: March 19, 201312:30 am

    I do not understand why there is not easier way of say importing a REAL Xcode project into a template form.. But anyways, I used your great article to make my own template. It was hours and it was not a party!!! haha but I finished it..

    Now apple, please make some sort of Project -> Template conversion!!!

    On a serious note!! -> I could not figure out how to reference a Framework located in /Library/Frameworks, so I instead used OTHER_LDFLAGS (Other Linker Flags) to do -framework bla instead… Do you know how to reference frameworks from that location or other locations??

    on a sidenote, I found it very helpful using the projectname.xcodeproj/projectname.pbxproj to see the codenames of various variables, that’s how i found OTHER_LDFLAGS for instance…

    Cheers!!! Please answer my question if you can!! Thanks!

  26. Matt Di Pasquale says: March 21, 20138:59 pm
  27. [...] A recipe for creating a minimal project template [...]

Submit comment

Get Adobe Flash player