Source Code Management The path setting specifi es the path to the Perforce source control client tool. The CVS and Subversion client tools are fi xed. SETTING DEFAULT DESCRIPTION PBXPerforceToolPath /usr/local/bin/p4 The default path to the Perforce client tool. XCSMLogSize 500 The maximum amount of text (in K) that will be kept in the SCM log, and that can be viewed in the SCM Results window. Documentation The following table lists the documentation setting: SETTING DEFAULT DESCRIPTION XCDocWindowSharesGlobal FindString YES When this is set to YES , the search fi eld for the help window automatically picks up the value of the global fi nd string. This is a system - wide resource shared by Xcode ’ s fi nd windows and other fi nd - savvy applications. If you make a search in Mail, for instance, switching to Xcode automatically picks up the last term you searched for. Change this setting to NO to suppress this behavior. TEMPLATES Although this is not offi cially documented, it ’ s also possible to customize Xcode by adding your own project and fi le templates. Templates are installed in the File Templates and Project Templates folders found in the /Developer/Library/Xcode folder. You can customize the existing one or add your own here. Like text macros, Xcode no longer searches the system (/Library ) or user ( ~/Library ) domains for templates, so if you want to customize them you ’ ll have to hack the set that comes installed with Xcode. The hierarchy and names of the subfolders within the templates folder determine the grouping and order of the templates that will appear in the New File or Project assistant. The easiest way to see this is to compare the fi le structure of a template folder with the new fi le assistant, shown in Figure 23 - 8. Templates ❘ 665 c23.indd 665c23.indd 665 1/22/10 1:28:59 PM1/22/10 1:28:59 PM Download at getcoolebook.com 666 ❘ CHAPTER 23 CUSTOMIZING XCODE You can group your templates however you want, simply by placing them into a subfolder of related templates, with one exception: some groups have a .plist fi le that defi nes additional information about the group, selection options, and so forth. If a folder contains a .plist fi le you will have to edit it to include your template defi nition or else Xcode will ignore it. If the folder doesn ’ t have a .plist fi le, just drop in your template and it will appear in Xcode. File Templates File templates can be a single fi le or a fi le template bundle. The simplest way to add a fi le template is to place a plain document fi le in the File Templates folder. The next time you start Xcode and use the File ➪ New File command, the name of the fi le appears in the list. Select it and Xcode reads the fi le and use its contents to fi ll in your new fi le. File template bundles are a little more sophisticated. File template bundles are not real bundles, but are folders that mimic the bundle structure. A fi le template bundle has an extension of .pbfiletemplate . The name of the folder is the name of the template, as it will appear in the New File assistant. Inside the folder is a TemplateInfo.plist fi le and one or two document fi les. TemplateInfo.plist contains a number of properties, described in the following table: PROPERTY DESCRIPTION MainTemplateFile This property is required. It is the name of the primary template fi le in the bundle. CounterpartTemplateFile This property is the name of a companion fi le that can be created by the template. This property is optional. If present, Xcode displays a check box option in the new fi le dialog box that asks if the user wants to create the companion fi le at the same time they create the main fi le. Description Text that describes the template. This description appears in the lower pane of the new fi le assistant when the user selects this template in the list. This property is optional, but highly recommended. If omitted, Xcode displays “ No description available. ” FIGURE 23 - 8 c23.indd 666c23.indd 666 1/22/10 1:28:59 PM1/22/10 1:28:59 PM Download at getcoolebook.com Create the template fi le or template bundle, name it appropriately, and place it in the File Templates folder or in a subfolder if you want it to be in a group of templates. Relaunch Xcode and your new template appears in the new fi le assistant. Template Macros Templates can contain variable names that are replaced with a value when the template is read. The macro names are surrounded by double - angle quotes ( « NAME » ). The following table lists the macro variables defi ned by Xcode when a fi le template is read. The double-angle quote characters, which are Unicode characters 0x00AB and 0x00BB, respectively, require that the fi le be encoded correctly — “Correctly” being defi ned as whatever Xcode expects the encoding to be. Open the template fi le in Xcode. If the double-angle quotes appear as one or two strange characters, then the encoding is mismatched. First note the current encoding. Now, try switching to a different encoding using the View ➪ Text ➪ File Encoding menu and choose the Reinterpret option. If the double-angle quote characters appear correctly, you’ve discovered their encoding. Switch back to the original encoding, this time choosing the Convert option, and save the fi le. You can type these characters using Option+\ and Option+Shift+\ on a U.S. Standard keyboard. If you are using a different keyboard layout, you may have a different key combination. Refer to the system’s Keyboard Viewer palette if you have diffi culty fi nding them, or use the system’s Character palette to insert the characters directly. MACRO EXAMPLE DESCRIPTION DATE 11/17/05 Today ’ s date, short format. YEAR 2006 The year. FILENAME My File.txt The complete name of the new fi le. FILEBASENAME My File The fi lename given to the fi le by the user, without its extension. FILEBASENAMEASIDENTIFIER My_File The base fi lename, suitable for use as a language identifi er. The same as FILEBASENAME , but with all non - alphanumeric characters replaced with underscores. FULLUSERNAME James Bucanek The current user ’ s full account name. PROJECTNAME Tom & Jerry The name of the project. continues Templates ❘ 667 c23.indd 667c23.indd 667 1/22/10 1:29:00 PM1/22/10 1:29:00 PM Download at getcoolebook.com 668 ❘ CHAPTER 23 CUSTOMIZING XCODE MACRO EXAMPLE DESCRIPTION PROJECTNAMEASIDENTIFIER Tom___Jerry The name of the project, suitable for use as a language identifi er. The same as PROJECTNAME , but with all non - alphanumeric characters replaced with underscores. PROJECTNAMEASXML Tom & amp; Jerry The name of the project encoded using XML entities to escape any special characters. USERNAME james The current user ’ s UNIX account name. UUID 89E2FBF6 - 9B88 - 40EB - BFCF - 4550CA9F54CA A Universally Unique Identifi er. This value will be di erent every time. ORGANIZATIONNAME Genius, Inc. A common macro defi ned in the expert preferences. The UUID value is interesting and might be useful if the documents you are creating need to be managed by a database or identifi ed in some fashion. The ORGANIZATIONNAME macro was described in the “ Who ’ s — MyCompanyName — ? ” section of Chapter 4. The PROJECTNAME and related macros are defi ned for project templates or if the fi le is being added to a project. If you create a new fi le using a template but select “ none ” as the project to add it to, these variables are replaced with nothing. In fact, any undefi ned or unrecognized macro name is replaced with nothing in the new fi le. Project Templates You can also create your own project templates. If you want to create a simple project template that gets duplicated verbatim when created, follow these steps: 1. Create a new project. Confi gure the project the way you want it: Add source fi les, frameworks, targets, special settings, and so on. 2. Close the project. Delete the build folder and any other intermediate fi les that might be in the project folder. 3. Rename the project folder to the name of the template as you want it to appear in the new project assistant. 4. Move the project folder to a location in the /Developer/Library/Xcode/Project Templates folder where you want it to appear in the new project assistant list. Like fi le tem- plates, some of these groups have .plist fi les that defi ne the templates for that group. Copy (continued) c23.indd 668c23.indd 668 1/22/10 1:29:03 PM1/22/10 1:29:03 PM Download at getcoolebook.com your template to a folder without a .plist fi le, such as the Other folder, or edit the .plist fi le to include the new template. 5. Quit Xcode. Relaunch Xcode and create a new project using your template. Project Templates with Macros Simple project templates are easy, but boring. What you really want are project templates like those that ship with Xcode. These include fi les, class names, and project settings that magically alter themselves to match the name of the project you just created. Making a project template that will customize itself is considerably trickier than what ’ s involved in making a fi le template. How much of your project gets dynamically confi gured depends on how much work you want to put into it. The key to confi guring a self - customizing project template is to create a TemplateInfo.plist fi le and embed that in your project document package. The TemplateInfo.plist fi le should contain three properties: Description , FilesToRename , and FilesToMacroExpand as described in the following table: PROPERTY TYPE DESCRIPTION Description String This optional property is a string that describes the template. This description appears in the lower pane of the new project assistant window when a user selects this template from the list. FilesToRename Dictionary This optional property is a list of key/value pairs. Each pair consists of the name of the original fi le in the project and the name it should be renamed to when the new project is created. FilesToMacroExpand Array This optional property is a list of fi le name paths, relative to the new project folder, of the fi les that should be scanned for replicable template macro names. You should defi nitely supply a description string. It makes the template more pleasant to use, and is useful for debugging (explained later). The FilesToRename property is a translation table that renames certain fi les in the project as the project template is being duplicated. The values in this dictionary can include template macros, which allow you to give fi les in your project dynamic names. In the example shown in Figure 23 - 9, the Template_Prefix.pch fi le in the project template will be renamed to « PROJECTNAME » _Prefix. pch . PROJECTNAME will be replaced with whatever fi lename was given to the new project by the user. You can use any of the template macros listed previously in the “ Template Macros ” section in the project document or in the source fi les of your project template. The fi les in the project document package are automatically scanned for template macro names. This is how the macro names in the TemplateInfo.plist fi le are expanded. Also scanned is the project.pbxproj document. Thus, Templates ❘ 669 c23.indd 669c23.indd 669 1/22/10 1:29:03 PM1/22/10 1:29:03 PM Download at getcoolebook.com 670 ❘ CHAPTER 23 CUSTOMIZING XCODE any build settings in the project that contains a template macro name will be replaced. This allows you, for example, to set the Prefi x Header build setting to « PROJECTNAME » _Prefix.pch so it will match the name of the renamed Template_Prefix.pch fi le in the new project. FIGURE 23 - 9 Other fi les in the project are not automatically scanned for template macro names. To replace template macro names in any other fi les requires that you add its path to the FilesToMacroExpand property. The names in the list are the fi les in the new project, not the template, so if you want to process a fi le that you ’ ve also renamed, use the name the fi le was changed to — which itself will probably involve template macros. In the example previously shown in Figure 23 - 9, the « PROJECTNAMEASIDENTIFIER » Helper.h fi les are scanned for template macros. The original fi le in the TemplateHelper.h template looks like this: TemplateHelper.h // // « PROJECTNAMEASIDENTIFIER » Helper.h // « PROJECTNAME » // // Created by « FULLUSERNAME » on « DATE » . // Copyright « YEAR » « ORGANIZATIONNAME » . All rights reserved. // #import < Cocoa/Cocoa.h > @interface « PROJECTNAMEASIDENTIFIER » Helper : NSObject { } @end Not only will the fi le be renamed to match the project, but the class it defi nes will also get a matching name. c23.indd 670c23.indd 670 1/22/10 1:29:04 PM1/22/10 1:29:04 PM Download at getcoolebook.com File References in Project Templates The FilesToRename property renames fi les in the project folder. The macro replacement can be used to generate names dynamically in fi les and project properties. Unfortunately, these two mechanisms don ’ t work closely with each other or with the project itself. The FilesToRename property just renames fi les. It doesn ’ t alter or fi x up any of the project references to those fi les. If nothing else is done, the project will contain bad references to the original fi les. To fi x this, you must manually insert template macros into the project.pbxproj fi le. You can do this in Xcode or the Property List Editor by temporarily giving the project.pbxproj fi le an extension of .xml or .plist , or you can use another text editor like BBEdit. If you edit template property fi les with BBEdit, make sure you use the correct encoding. Property list fi les typically have an encoding of UTF-8. If you open one of these fi les using ASCII encoding, the double-angle quote characters will not be encoded correctly. Use BBEdit’s File ➪ Reopen Using Encoding ➪ Unicode command to reinterpret the fi le as UTF-8. You ’ ll have to fi nd and replace the fi lename paths in the property fi les by hand, because there is no facility for entering these dynamic names in the Xcode interface. The format for the project document fi le is not intended to be “ user friendly. ” Nevertheless, it ’ s pretty safe to search for the fi le names you want to make dynamic and replace them with template macros. Just be careful not to make any other structural changes in the fi le, or you ’ ll likely end up with a corrupted project document. For example, here ’ s a fragment of a project.pbxproj fi le that contained references to the TemplateHelper.h , TemplateHelper.m , and main.c source fi les: 1AAE3664092E3E8c23412C87 /* TemplateHelper.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = « PROJECTNAMEASIDENTIFIER » Helper.h; sourceTree = " < group > "; }; 1AAE3665092E3E8c23412C87 /* TemplateHelper.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = « PROJECTNAMEASIDENTIFIER » Helper.m; sourceTree = " < group > "; }; 29B97316FDCFA39411CA2CEA /* main.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = main.m; sourceTree = " < group > "; }; The fi le has been edited so that the fi rst two source fi le names are now altered dynamically to match their renamed versions in the new project. Problems with Project Templates Template project problems can be diffi cult to isolate, because there are no overt errors or warnings produced by Xcode to tell you that something is wrong. Templates ❘ 671 c23.indd 671c23.indd 671 1/22/10 1:29:04 PM1/22/10 1:29:04 PM Download at getcoolebook.com 672 ❘ CHAPTER 23 CUSTOMIZING XCODE The fi rst thing to check in your new template is that its description appears in the new project assistant window when you choose your template in the list. If it does not, then Xcode didn ’ t read your TemplateInfo.plist fi le. Make sure the location, syntax, and encoding of the fi le is correct. You might fi nd that the easiest way of doing this is to open the fi le using the Property List Editor and forcing the fi le to be resaved. The Property List Editor usually corrects any inconsistencies when it writes a new fi le. If you have macros in source fi les that aren ’ t being expanded, make sure they have been written using the default encoding expected by Xcode for that fi le type. Follow the steps for fi xing the encoding in the earlier “ Template Macros ” section. Also double - check that you ’ ve added the fi le to the FilesToMacroExpand property. If the fi le is one that gets renamed, make sure you specifi ed its new name — not its original name — in the template. Look at the system console log. Some problems encountered during template processing are logged here and may give you some clue as to what is wrong. Last, but not least, study (or just copy) the Xcode templates that come preinstalled. They demonstrate a wide range of customizations. Learning how they work may illuminate what ’ s not working in yours. Project Template Portability If you are creating project templates for your own consumption, you ’ re pretty much done. However, if you want to create sophisticated templates to share with other developers, there are a couple of additional details you should consider. You ’ ll want to delete your user settings fi les from the project document package. These documents are stored inside the project document package and are named using your logged - in UNIX account name. Other users don ’ t need these documents in their projects. Target Templates You may also fi nd it useful to create custom target templates. These are the templates used by the new target assistant when you ’ re adding a new target to your project. Target templates are defi ned by the target template fi les found in the /Developer/Library/Xcode/Target Templates folder. A target template fi le is a property list fragment with an extension of .trgttmpl . Several properties must be set correctly for the target template to be functional. The important elements are the Class and ProductType properties. The easiest way to create a new target template is to copy a template fi le that creates the correct target type and edit its other properties. This listing shows the target template fi le for a Cocoa application target: { Class = Native; ProductType = "com.apple.product-type.application"; Description = "Target for building an application that uses Cocoa APIs."; CustomBuildSettings = { INSTALL_PATH = "$(USER_APPS_DIR)"; INFOPLIST_FILE = " « PRODUCTNAME » -Info.plist"; OTHER_LDFLAGS = "-framework Foundation -framework AppKit"; GCC_PREFIX_HEADER = "$(SYSTEM_LIBRARY_DIR)/Frameworks/ c23.indd 672c23.indd 672 1/22/10 1:29:07 PM1/22/10 1:29:07 PM Download at getcoolebook.com AppKit.framework/Headers/AppKit.h"; GCC_PRECOMPILE_PREFIX_HEADER = YES; PRODUCT_NAME = " « PRODUCTNAME » "; PREBINDING = NO; GCC_GENERATE_DEBUGGING_SYMBOLS = NO; GCC_MODEL_TUNING = G5; }; CustomProductSettings = { CFBundleExecutable = " « PRODUCTNAME » "; CFBundleInfoDictionaryVersion = "6.0"; CFBundleVersion = "1.0"; CFBundleIdentifier = "com.yourcompany. « TARGETNAMEASIDENTIFIER » "; CFBundleDevelopmentRegion = English; CFBundlePackageType = "APPL"; CFBundleSignature = "????"; NSMainNibFile = "MainMenu"; NSPrincipalClass = "NSApplication"; }; BuildPhases = ( { Class = Resources; }, { Class = Sources; }, { Class = Frameworks; }, ); } After you make a copy of the template fi le, edit the Description , CustomBuildSettings , CustomProductSettings , and BuildPhases properties. The CustomBuildSettings can defi ne any build settings you want and can refer to template macro values. The PRODUCTNAME and TARGETNAMEASIDENTIFIER template macros are defi ned while creating a new target and can be used to refer to the new target ’ s name. The CustomProductSettings are present for targets that produce an Info.plist fi le and contain a list of customized values that will appear in the Properties pane of the target ’ s Info window. The BuildPhases property lists the build phases for the new target. The possible BuildPhase types are Aggregate Application Bundle CopyFiles Frameworks Headers ➤ ➤ ➤ ➤ ➤ ➤ Templates ❘ 673 c23.indd 673c23.indd 673 1/22/10 1:29:08 PM1/22/10 1:29:08 PM Download at getcoolebook.com 674 ❘ CHAPTER 23 CUSTOMIZING XCODE JavaArchive Legacy Library Native Resources ShellScript Sources Tool Refer to other templates, or fi rst create a target of the desired type and add your desired phases to it, to ensure that the target can accept a particular build phase type. You should not include a build phase in a target type that does not normally accept that build phase type. Name your target template fi le and place it where you want it to reside inside the Target Templates folder. Relaunch Xcode to use the new template. USER SCRIPTS User scripts are custom actions that appear in the Xcode menu. Each script is an executable text fi le that can optionally interact with the content of your active editor pane, essentially allowing you to extend the editor with your own commands. You can write your scripts using a shell language, perl , python , ruby , awk , or any other interpreter you want. Although the script is in the form of an executable fi le, you cannot substitute a binary executable. The fi le must be a text fi le encoded using UTF-8. However, there is nothing stopping a script from launching another binary executable or script. For example, a custom script could start an AppleScript using the osascript tool. Xcode preprocesses script fi les before they are executed. Scripts contain additional properties and commands that enable them to communicate with the Xcode application — in a fashion. Because of the subtle differences between regular executable scripts and custom Xcode scripts, the following sections use the term “ custom script ” to indicate an executable script that employs special Xcode syntax. The StartupScript When Xcode starts, it looks for the custom script /Developer/Library/Xcode/StartupScript and executes it. This script is a custom script that can employ any of the special custom script extensions explained later — at least those that make sense in the absence of an editor context. You can modify this script to automatically perform any action you want every time Xcode starts. ➤ ➤ ➤ ➤ ➤ ➤ ➤ ➤ c23.indd 674c23.indd 674 1/22/10 1:29:08 PM1/22/10 1:29:08 PM Download at getcoolebook.com . the new target. The possible BuildPhase types are Aggregate Application Bundle CopyFiles Frameworks Headers ➤ ➤ ➤ ➤ ➤ ➤ Templates ❘ 6 73 c 23. indd 673c 23. indd 6 73 1/22/10 1:29:08 PM1/22/10. project. continues Templates ❘ 667 c 23. indd 667c 23. indd 667 1/22/10 1:29:00 PM1/22/10 1:29:00 PM Download at getcoolebook.com 668 ❘ CHAPTER 23 CUSTOMIZING XCODE MACRO EXAMPLE DESCRIPTION PROJECTNAMEASIDENTIFIER. 669c 23. indd 669 1/22/10 1:29: 03 PM1/22/10 1:29: 03 PM Download at getcoolebook.com 670 ❘ CHAPTER 23 CUSTOMIZING XCODE any build settings in the project that contains a template macro name will be replaced.