656 ❘ CHAPTER 23 CUSTOMIZING XCODE PROPERTY DEFAULT DESCRIPTION PreColonSpacing "" Whitespace before a colon in an Objective- C method name or message expression. PostColonSpacing "" Whitespace after a colon in an Objective-C method name or message expression. MessageArgSpacing "" Whitespace between the parenthesized type and argument name in an Objective-C method declaration. CaseStatementSpacing "\t" Relative indentation of a case keyword inside a switch block. A tab (‘\t’) character indents by the tab indentation width. For example, if you want all code blocks inserted by Xcode text macros to place the opening curly brace on the next line of code, redefi ne the BlockSeparator property to " \n " . The following command accomplishes this from the command line: defaults write com.apple.Xcode XCCodeSenseFormattingOptions -dict BlockSeparator '\n' This command creates a dictionary in the Xcode user properties with a single key/value pair of BlockSeparator = ‘ \n' . Note that this also replaces any previous dictionary that might have been set, another reason why using the Properties List Editor is a better idea. EXPERT PREFERENCES Expert Preferences are additional, often obscure, preferences for which there is no direct user interface for changing it. You set expert preferences by directly altering the settings in the preferences fi le for the Xcode application. This fi le is com.apple.Xcode.plist , located in your ~/Library/Preferences folder. There are two simple ways of changing these settings. However you alter them, remember that the Xcode application should not be running when you do. Changing some values while Xcode is running may have unpredictable consequences. It ’ s best to fi rst quit the Xcode application, make your changes, and then launch Xcode again. The fi rst method is to use the defaults command from a Terminal window. The syntax for setting a value in the Xcode preferences is as follows: defaults write com.apple.Xcode key -type value The write command tells the defaults command to set a value in the fi le. The last three arguments specify the symbol, the type of the value, and the value it will be set to. (Refer to the man page for the defaults command for more options.) For example, the drag - and - drop delay used by Xcode ’ s text editor can be adjusted by setting the value for the NSDragAndDropTextDelay key. The command to set this value to 500 (milliseconds) is as follows: defaults write com.apple.Xcode NSDragAndDropTextDelay -integer 500 (continued) c23.indd 656c23.indd 656 1/22/10 1:28:55 PM1/22/10 1:28:55 PM Download at getcoolebook.com To avoid any ambiguity in how the value is interpreted, it ’ s recommended that you include a - type option that casts the value to a specifi c property list value type. The types that are most useful are: - string (the default) - int or - integer - float - bool or - boolean When setting Boolean values, the defaults tool is very fl exible. It will accept 0 , 1 , false , true , NO , and YES . If you ever need to delete a preference value, returning it to its default value, use the delete command, like this: defaults delete com.apple.Xcode key The second method is to use the Property List Editor application included with the Xcode development tools. Figure 23 - 7 shows setting the same value by editing the com.apple.Xcode. plist property list fi le. Remember not to open the fi le until after you have quit the Xcode application. The Property List Editor makes setting complex values, like dictionaries and numeric types, much easier. Remember that the com.apple.Xcode.plist fi le contains all of Xcode ’ s preferences and state settings; be mindful not to alter other internal settings indiscriminately, because it may affect Xcode ’ s stability. ➤ ➤ ➤ ➤ FIGURE 23 - 7 The following sections list some of the more useful expert preferences settings, grouped by subject. Apple has documented most of these in the Xcode User Defaults document. Search for it in the documentation, or read it online at http://developer.apple.com/mac/library/ documentation/DeveloperTools/Reference/XcodeUserDefaultRef/ . These hidden settings change from one version of Xcode to the next, so consult this list or the release notes if you can ’ t fi nd what you ’ re looking for here. Expert Preferences ❘ 657 c23.indd 657c23.indd 657 1/22/10 1:28:56 PM1/22/10 1:28:56 PM Download at getcoolebook.com 658 ❘ CHAPTER 23 CUSTOMIZING XCODE Projects and Files The following table lists the projects and fi les settings: SETTING DEFAULT DESCRIPTION PBXCustomTemplateMacroDefinitions (none) A dictionary of values used to replace variables in project and fi le templates. The canonical example is the (now obsolete) __MyCompanyName__ value. PBXDontWarnIfProjectSaveFails NO Setting this to YES suppresses Xcode ’ s warning that there were problems saving the project documents. Project documents are constantly being updated, and Xcode warns you if the fi le cannot be written. This occurs repeatedly if you have no write access to the document, such as a project on a CD - ROM. PBXPreservePosixPermissionsOnSave YES If set to YES , Xcode tries to restore the POSIX fi le permissions whenever it saves a fi le. You may want to change this to NO if you are writing project fi les to a non - native or networked fi le system. NSRecentDocumentsLimit 10 The maximum number of projects to keep in the File ➪ Open Recent File and File ➪ Open Recent Project menu. XCOpenProjectFilesInsideFolders NO Setting this to YES lets you open a project document by opening its project folder. In the Open dialog, open a project folder and Xcode will fi nd the fi rst project document and open it instead. Useful if you open a lot of projects that have lots of fi les in the project folder. This option is known to cause problems with keyboard navigation of the Open dialog. c23.indd 658c23.indd 658 1/22/10 1:28:56 PM1/22/10 1:28:56 PM Download at getcoolebook.com Editing The following table lists the editing settings: SETTING DEFAULT DESCRIPTION NSDragAndDropTextDelay 500 The delay, in milliseconds, that you must hold the mouse button down without moving it before a click in a text selection becomes a text drag. If you are constantly selecting instead of dragging text, reduce this delay. Increase it if you fi nd yourself dragging text when you wanted to select it. Set the delay to 0 (or a negative number) to disable text dragging altogether. PBXIndentOnPaste YES Normally, when you ’ re pasting text into a syntax - aware editor pane, Xcode automatically re - indents the text. If you fi nd this annoying, change this setting to NO and pasted text will be inserted literally. You can always manually re - indent the text using the Format ➪ Re - Indent command. PBXBeepOnNoMatchingBrace YES Set this to NO to suppress Xcode ’ s habit of playing the system “ beep ” sound when it can ’ t fi nd a matching brace. The editor looks for matching braces whenever you type a closing brace or parenthesis, or if you double - click a brace or parenthesis. XCShowUndoPastSaveWarning YES Xcode warns you whenever you are about to undo a change that occurred before the fi le was last saved. If you fi nd this warning annoying, change this setting to NO . XCColorUnknownLanguages NO The Xcode editor normally provides syntax coloring only for languages that it understands. Setting this to YES will cause text that appears to be comments (lines beginning with # , text between /* … */ , and so on), URLs, and string literals to be colored in any text fi le. XCCodeSenseAllowAuto CompletionInPlainFiles NO Normally, auto - completion is only active in fi les that Xcode understands. Setting this option to YES enables auto - completion for all fi le types. Auto - completion will consist of language keywords and text macros. continues Expert Preferences ❘ 659 c23.indd 659c23.indd 659 1/22/10 1:28:56 PM1/22/10 1:28:56 PM Download at getcoolebook.com 660 ❘ CHAPTER 23 CUSTOMIZING XCODE SETTING DEFAULT DESCRIPTION XCScrollToEndOfMatching Brace YES When you double - click a quote, brace, or parenthesis, Xcode scrolls so that the matching brace is visible in the editor pane. Set this to NO to leave the scroll position alone. XCMatchIndentWithLineAbove YES When Syntax - Aware Indenting is disabled, or when you ’ re editing a non - syntax - aware source fi le type, this setting still causes auto - indenting of a new line to the same tab position as the previous line. Setting the value to NO disables auto - indenting of new lines, in the editor ’ s Insert Newline action. XCSmartInsertDeleteEnabled NO Set this to YES and Xcode will try to be “ smarter ” about how it inserts and deletes spaces around words when inserting and deleting within a source fi le. XCCodeSenseFormatting Options (none) A dictionary of text macro property values that override those defi ned by the text macro defi nition fi les ( .xctxtmacro ). See the “ Sanctioned Text Macro Customization ” section for a description of the values in the dictionary. XCShowNonBreakingSpace YES Xcode normally displays a non - breaking space (Unicode 0x00A0) as a dot ( • ). Change this setting to NO and non - breaking spaces will display as whitespace. XCShowControlCharacters YES Xcode normally displays control characters that it fi nds in text fi les as an inverted question mark ( ¿ ). Change this setting to NO and control characters in source fi les will be invisible. Functions Menu The following settings control what kinds of items are included in the Functions menu of the editor ’ s navigation bar. The Show Declarations setting in the Code Sense tab of the Xcode Preferences controls the inclusion of function and method defi nitions. To include, or exclude, other types of items from the menu change these settings to YES or NO as desired. (continued) c23.indd 660c23.indd 660 1/22/10 1:28:57 PM1/22/10 1:28:57 PM Download at getcoolebook.com SETTING DEFAULT PBXMethodPopupIncludeMarksDefault YES PBXMethodPopupIncludeClassDeclarationsDefault YES PBXMethodPopupIncludeClassDefinitionsDefault YES PBXMethodPopupIncludeMethodDeclarationsDefault YES PBXMethodPopupIncludeMethodDefinitionsDefault YES PBXMethodPopupIncludeFunctionDeclarationsDefault YES PBXMethodPopupIncludeFunctionDefinitionsDefault YES PBXMethodPopupIncludeTypesDefault YES PBXMethodPopupIncludeDefinesDefault YES PBXMethodPopupIncludeWarningsDefault NO Building The following table lists the building settings: SETTING DEFAULT DESCRIPTION BuildSystemCacheSize InMegabytes 1024 The “trim” size of the precompiled headers cache. Precompiled headers are cached and reused whenever possible. If the size of the cache is larger than this value in megabytes, Xcode deletes the oldest precompiled headers to recover disk space. Note that this happens only once, when the Xcode application is fi rst launched. Setting this value to 0 disables this check, allowing the cache to grow unabated. Also see the BuildSystemCacheMinimumRemovalAgeInHours setting. BuildSystemCacheMinimum RemovalAgeInHours 24 This is the number of hours a precompiled header must have been in the cache before it can be removed. Even if the BuildSystemCacheSizeInMegabytes setting tells Xcode it’s time to delete old headers in the cache, headers that are younger than this setting will never be removed, even if it means not trimming the cache down to the requested size. continues Expert Preferences ❘ 661 c23.indd 661c23.indd 661 1/22/10 1:28:57 PM1/22/10 1:28:57 PM Download at getcoolebook.com 662 ❘ CHAPTER 23 CUSTOMIZING XCODE SETTING DEFAULT DESCRIPTION PBXBuildSuccessSound (none) Set this to the path of a sound fi le you want played when a build is successful. PBXBuildFailureSound (none) Set this to the path of a sound fi le you want played whenever a build fails. PBXNumberOfParallelBuildS ubtasks (none) The number of parallel tasks the build system will try to keep running while building. If not set, the build system uses the number of processors installed in your computer. Set this to a number greater than the number of processors if your builds are I/O bound. Reduce the number to keep Xcode from using all available CPU resources. PredictiveCompilationDelay 30 The number of seconds before a predictive compile is performed. If a source fi le in an editor pane hasn’t been modifi ed for a while, Xcode attempts to compile it in the background. Increase this delay if background compilation is using too many resources, or reduce it to be more aggressive. This feature requires that predictive compilation is enabled in the Xcode Preferences. Xcode ignores this setting if you try to set it to 10 or less. UsePerConfigurationBuild Locations YES Build locations are normally separated into subfolders by build confi guration. This avoids the need to rebuild the entire project when switching build confi gurations, but uses considerably more disk space. Set this to NO, and the build products of di erent build confi gurations will be written to the same folder. (continued) Distributed Builds The following table lists the distributed builds settings: c23.indd 662c23.indd 662 1/22/10 1:28:58 PM1/22/10 1:28:58 PM Download at getcoolebook.com SETTING DEFAULT DESCRIPTION XCMaxNumberOfDistributedTasks 25 The maximum number of tasks to distribute to other computers when you ’ re using distributed builds. XCDistributedBuildsVerboseLogging NO Change this setting to YES to enable diagnostic messages from the distcc tool. If you are having problems with distributed builds, these messages may provide some insight as to why. DistributedBuildsLogLevel 0 Controls the amount of detail produced by Xcode ’ s distributed build manager. This is useful for debugging distributed build problems. The value must be 0 , 1 , or 2 . Debugging The following table lists the debugging settings: SETTING DEFAULT DESCRIPTION XCAutoClearRunDebugStdIOLogs NO Set this to YES and Xcode will clear the run, debug, and standard I/O windows at the beginning of each debugging or run session. Normally, Xcode preserves the results of the previous run or debug session, allowing the output of those to accumulate until you quit Xcode or manually clear the log windows with the Debug ➪ Clear Logs command. PBXGDBPath / Developer /usr/bin/gdb The path to the gdb debugger. Change this setting to use an alternate version of the gdb debugger. Note that for remote debugging, Xcode ’ s default is /usr/bin/ssh . continues Expert Preferences ❘ 663 c23.indd 663c23.indd 663 1/22/10 1:28:58 PM1/22/10 1:28:58 PM Download at getcoolebook.com 664 ❘ CHAPTER 23 CUSTOMIZING XCODE SETTING DEFAULT DESCRIPTION PBXGDBDebuggerLogToFile NO If you think you need to debug the communications between Xcode and the debugger, change this setting to YES . This causes Xcode to log all communications between Xcode and the gdb tool to a fi le in /var/tmp/folders. < uid > / Temporary Items . The name of the fi le is determined by the PBXGDBDebuggerLogFileName setting. If you are having problems with the debugger, Apple requests that you include this log fi le in any bug reports. PBXGDBDebuggerLogFileName (none) If left undefi ned, the name of the debugger log fi le will be XCGDB - name - pid , where name is the name of the executable and pid is its process ID. Setting this to a fi xed value causes the log to be written to the same fi le for every debug session, overwriting any previous fi le. This setting requires that PBXGDBDebuggerLogToFile is set to YES to have any e ect. Snapshots This single setting determines where snapshots are stored. If you have a scratch drive you may want to direct the snapshot repository to there. If you ’ ve previously taken snapshots, remember to relocate the SnapshotRepository.sparseimage fi le to its new location before launching Xcode, or else Xcode will forget all of your snapshots. SETTING DEFAULT DESCRIPTION XCSnapshotDiskImagePath ~/Library/Application Support/Developer/ Shared/ SnapshotRepository. sparseimage Path to the sparse disk image document that Xcode uses to store snapshots. (continued) c23.indd 664c23.indd 664 1/22/10 1:28:58 PM1/22/10 1:28:58 PM Download at getcoolebook.com 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 . remote debugging, Xcode ’ s default is /usr/bin/ssh . continues Expert Preferences ❘ 6 63 c 23. indd 663c 23. indd 6 63 1/22/10 1:28:58 PM1/22/10 1:28:58 PM Download at getcoolebook.com 664 ❘ CHAPTER 23 CUSTOMIZING. XCCodeSenseFormatting Options (none) A dictionary of text macro property values that override those defi ned by the text macro defi nition fi les ( .xctxtmacro ). See the “ Sanctioned Text Macro Customization ” section. affect Xcode ’ s stability. ➤ ➤ ➤ ➤ FIGURE 23 - 7 The following sections list some of the more useful expert preferences settings, grouped by subject. Apple has documented most of these in the Xcode