Xcode User Defaults

Xcode User Default Overview

Xcode lets you customize its behavior through the Xcode Preferences window, which includes settings to handle the most common customizations. However, Xcode also lets you perform customizations to settings that are not present in the user interface. Xcode uses user defaults to let you change the value of these settings. User defaults is an OS X subsystem that lets you customize the behavior of applications using the defaults command.

The defaults command takes a command and a domain. The user domain for Xcode is com.apple.Xcode. The most-used commands are write (to set the value of a user default) and read (to get the value of a user default). Here’s the format of the command invocation to set the value of an Xcode user default:

> defaults write com.apple.Xcode <key> <value>

This the invocation used to get the value of a user default:

> defaults read com.apple.Xcode <key>

The user-defaults system lets you override the built-in values of settings used in Xcode. The built-in default value of a setting is encoded in the application, not in the Xcode user-defaults domain. Therefore, when a particular setting is not present in the Xcode user-defaults domain, its default value may vary depending on the Xcode release you’re using.

The Xcode user-defaults domain applies to all instances of Xcode installed on your computer. Therefore, when setting user-default values, you must ensure that all the releases of Xcode you’re using support that user-default and its new value.

To learn about using multiple Xcode releases in one computer, see Xcode Installation Guide.

The following sections list and describe the Xcode user defaults.

General User Defaults

NSDragAndDropTextDelay

Description

Specifies the period (in milliseconds) after text is selected that a click-and-drag event on the selected text is processed as the beginning of a drag-and-drop operation.

Value

A positive value defines the drag-and-drop period.

A negative value or zero deactivates text drag and drop.

NSRecentDocumentsLimit

Description

Specifies the maximum number of items to show in the File > Recent Projects menu.

Value

Positive integer. Default: 10.

PBExtraPlugInFolders

Description

Specifies extra paths in which to look for Xcode plug-ins beyond the standard <domain>/Library/Application Support/Apple/Developer Tools/Plug-ins directories.

Value

Set of strings. Default: None.

PBXCustomTemplateMacroDefinitions

Description

Dictionary of extra macros for use in project and file templates.

Keys

ORGANIZATIONNAME: The name of your organization. Default: __MyCompanyName__.

PBXDontWarnIfProjectSaveFails

Description

Specifies whether Xcode displays a warning when it is unable to save a project package. Useful for developers using an SCM system that makes project packages nonwritable.

Value

YES to display the warning dialog. Default: NO.

XCAutoClearRunDebugStdIOLogs

Description

Specifies whether output in the Console window is cleared after each session.

Value

YES to clear the console automatically. Default: NO.

XCOpenProjectFilesInsideFolders

Description

Specifies whether Xcode opens the first Xcode project inside the selected folder in an Open panel when the user clicks the Open button. Using this feature may cause problems with keyboard-based navigation of Open panels.

Value

YES to automatically open the first Xcode project inside an opened folder. Default: NO.

Source Code Editing User Defaults

Encodings

Description

Specifies the list of encodings shown in Encodings menus. This list uses the same format as the encodings list in the TextEdit user defaults. You can copy that list from ~/Library/Preferences/com.apple.TextEdit.plist to ~/Library/Preferences/com.apple.Xcode.plist using a text editor.

Value

Array. Default: None.

PBXBeepOnNoMatchingBrace

Description

Specifies whether the text editor beeps when a closing brace (}) is typed or double-clicked without a corresponding opening brace ({).

Value

YES to activate beeping. Default: NO.

PBXEmacsPath

Description

Specifies the path to the emacs binary. Use only when you want to use a custom-built Emacs editor.

Value

Pathname. Default: <Xcode>/usr/bin/emacs.

PBXPipeShellPath

Description

Specifies the path to the shell editor to use in Worksheet windows (which combine a full-featured shell and a text editor).

Value

Pathname. Default: /bin/sh.

PBXXEmacsPath

Description

Specifies the path to the xemacs binary.

Value

Pathname. Default: <Xcode>/usr/bin/xemacs.

PBXMethodPopupIncludeClassDeclarationsDefault

Description

Specifies whether the declarations menu in the text editor shows class declarations.

Value

YES to show class declarations. Default: YES.

PBXMethodPopupIncludeClassDefinitionsDefault

Description

Specifies whether the declarations menu in the text editor shows class definitions.

Value

YES to show class definitions. Default: YES.

PBXMethodPopupIncludeDefinesDefault

Description

Specifies whether the declarations menu in the text editor shows #define statements.

Value

YES to show #define statements. Default: YES.

PBXMethodPopupIncludeFunctionDeclarationsDefault

Description

Specifies whether the declarations menu in the text editor shows function declarations.

Value

YES to show function declarations. Default: YES.

PBXMethodPopupIncludeFunctionDefinitionsDefault

Description

Specifies whether the declarations menu in the text editor shows function definitions.

Value

YES to show function definitions. Default: YES.

PBXMethodPopupIncludeMethodDeclarationsDefault

Description

Specifies whether the declarations menu in the text editor shows method declarations.

Value

YES to show method declarations. Default: YES.

PBXMethodPopupIncludeMethodDefinitionsDefault

Description

Specifies whether the declarations menu in the text editor shows method definitions.

Value

YES to show method definitions. Default: YES.

PBXMethodPopupIncludeTypesDefault

Description

Specifies whether the declarations menu in the text editor shows type definitions.

Value

YES to show type definitions. Default: YES.

PBXMethodPopupIncludeMarksDefault

Description

Specifies whether the declarations menu in the text editor shows ??<mark_label>?? marks.

Value

YES to show marks. Default: YES.

PBXMethodPopupIncludeWarningsDefault

Description

Specifies whether the declarations menu in the text editor shows ??<warning_label>?? warnings.

Value

YES to show warnings. Default: NO.

PBXPreservePosixPermissionsOnSave

Description

Specifies whether Xcode attempts to preserve POSIX file permissions when saving a file.

Value

YES to attempt permission preservation. Default: YES.

XCScrollToEndOfMatchingBrace

Description

Specifies whether double-clicking a quotation mark, brace, or parenthesis causes the text editor to scroll to the opposite end of the resulting selection.

Value

YES to scroll on brace double click. Default: YES.

PBXShowMatchingBrace

Description

Specifies whether the text editor highlights the corresponding scope delimiter (parentheses, bracket, or brace) as one is typed.

Value

YES to highlight corresponding delimiter after typing. Default: YES.

XCCodeSenseAllowAutoCompletionInPlainFiles

Description

Specifies whether the text editor uses code completion in plain text, nonsource files. When active in these files, code completion processes only the words present in the file, along with language keywords and text macros defined for the file’s type.

Value

YES to activate code completion in nonsource files. Default: NO.

XCSelectToInsideMatchingQuotes

Description

Specifies whether the text editor selects text inside quotation marks when double-clicking quotation marks (' or ").

Prerequisite

Selection to matching brace is active (Xcode Preferences > Text Editing).

Value

YES to select quoted text on quotation-mark double click. Default: YES.

XCShowUndoPastSaveWarning

Description

Specifies whether Xcode displays a warning when an undo operation on an open file would take it to a state prior to the file’s last save operation.

Value

YES to warn about past-save undo operations. Default: YES.

XCSmartInsertDeleteEnabled

Description

Specifies whether the text editor manages spaces when inserting and deleting spaces around words when text is inserted or deleted.

Value

YES to automanage spaces after insert or delete operations. Default: NO.

Source Code Formatting User Defaults

PBXIndentOnPaste

Description

Specifies whether the text editor reindents source code that is pasted when syntax-aware indenting (Xcode Preferences > Indentation) is active.

Value

YES to reindent pasted code. Default: YES.

XCCodeSenseFormattingOptions

This user default is a dictionary that specifies the whitespace Xcode applies in code completion and text-macro expansion.

To specify or add XCCodeSenseFormattingOptions keys to the Xcode user defaults database, use the -dict and -dict-add options of the defaults command. For example:

> defaults write com.apple.Xcode XCCodeSenseFormattingOptions -dict PreExpressionsSpacing  "" PreCommaSpacing " "

The following table describes the XCCodeSenseFormattingOptions keys you can define to override the default values.

Key

Value

PreExpressionsSpacing

Whitespace between an if, for, and while keyword and the opening parenthesis.

Default: " ".

InExpressionsSpacing

Whitespace inside a parenthesized expression—after the opening parenthesis and the closing parenthesis.

Default: "".

PreFunctionArgsSpacing

Whitespace between a function name and the opening parenthesis.

Default: "".

InFunctionArgsSpacing

Whitespace inside a parenthesized function argument list—after the opening parenthesis and the closing parenthesis.

Default value: "".

PreCommaSpacing

Whitespace before a comma inside a function argument list.

Default: "".

PostCommaSpacing

Whitespace after a comma inside a function argument list.

Default: " ".

PreMethodTypeSpacing

Whitespace before the parenthesized return type in an Objective-C method declaration.

Default: " ".

PreMethodDeclSpacing

Whitespace between the parenthesized return type and the method name in an Objective-C method declaration.

Default: " ".

InMessageSpacing

Whitespace inside an Objective-C message expression—after the opening bracket and before the closing bracket.

Default: "".

PreColonSpacing

Whitespace before a colon in an Objective-C method name or message expression.

Default: "".

PostColonSpacing

Whitespace after a colon in an Objective-C method name or message expression.

Default: "".

MessageArgSpacing

Whitespace between the parenthesized type and argument name in an Objective-C method declaration.

Default: "".

CaseStatementSpacing

Relative indentation of a case keyword inside a switch block. A tab ('\t') character indents by the tab indentation width.

Default: "\t".

BlockSeparator

Whitespace after the parenthesized expression of an if, for, or while statement and its opening brace.

Default: " ".

PostBlockSeparator

Whitespace after the closing brace of a block.

Default: "\n".

FunctionBlockSeparator

Whitespace after a method or function name and argument-list declarations and its body.

Default: "\n".

XCColorUnknownLanguages

Description

Specifies whether the text editor performs syntax coloring on files containing source code in languages unknown to Xcode.

Syntax coloring on unknown languages follows these rules:

  • Lines beginning with # are treated as comment lines.

  • Text within /* and */ is treated as a comment.

  • URLs inside comments are behave as hyperlinks.

  • Text within double quotation marks (") is treated as a string.

Value

YES to perform syntax coloring on unknown languages. Default: NO.

XCMatchIndentWithLineAbove

Description

Specifies whether the text editor aligns new lines (after pressing Return) with the previous line when syntax-aware indenting (Xcode Preferences > Indentation) is unavailable for the current file, either because it’s inactive or because the type of the current file doesn’t support it.

Value

YES to align new lines with their predecessors. Default: YES.

XCShowControlCharacters

Description

Specifies whether the text editor identifies control characters using an inverted question mark (¿).

Value

YES to identify control characters. Default: YES.

XCShowNonBreakingSpace

Description

Specifies whether the text editor identifies nonbreaking space characters (Unicode 0xA0) as a middle dot ().

Value

YES to identify nonbreaking space characters. Default: YES.

Source Code Indexing User Defaults

XCCodeSenseIndexBasePath

Description

Specifies the location at which to save the source code index, instead of the standard location.

Value

Pathname (absolute or relative to the project directory). Default: OBJROOT/<project_name>.pbxindex.

See

“OBJROOT (Intermediate Build Files Path)” in Xcode Build Setting Reference.

Building User Defaults

BuildSystemCacheSizeInMegabytes

Description

Specifies the desired maximum size (in megabytes) of the precompiled header (PCH) cache. Xcode obtains the size of the cache on launch and at the end of each build. If the cache size is greater than the desired maximum, Xcode attempts to bring the cache size below the maximum by removing the oldest precompiled-header files from the cache.

Value

Positive integer. Default: 1024.

See

“BuildSystemCacheMinimumRemovalAgeInHours”

BuildSystemCacheMinimumRemovalAgeInHours

Description

Specifies the minimum age (in hours) a precompiled-header file must be in order for it to be a candidate for removal during a cache-size reduction operation.

Value

Positive integer. Default: 24.

See

“BuildSystemCacheSizeInMegabytes”

PBXNumberOfParallelBuildSubtasks

Description

Specifies the desired number of parallel tasks Xcode uses during builds.

Value

Positive integer. Default: Number of CPU cores on the build host.

UsePerConfigurationBuildLocations

Description

Specifies whether the built products and intermediate build files are grouped by build configuration.

Value

YES to group build files by build configuration. Default: YES.

PredictiveCompilationDelay

Description

Specifies the period (in seconds) to wait after a source file is edited before Xcode starts a predictive compile.

Prerequisite

Predictive compilation is active (Xcode Preferences > Building).

Value

Positive integer greater than 10. Default: 30.

Important

When specified, Xcode enforces a minimum value of 10.

PBXBuildFailureSound

Description

Identifies the build failure sound.

Value

Pathname to a sound file. Default: None.

PBXBuildSuccessSound

Description

Identifies the build success sound. Pathname to a sound file.

Value

Pathname to a sound file. Default: None.

Shared Workgroup Builds User Defaults

DistributedBuildsLogLevel

Description

Specifies the log level of the shared-workgroup-build manager.

Value

0: No logging.

1: Partial logging.

2: Full logging.

Default: 0.

XCDistributedBuildsVerboseLogging

Description

Specifies whether shared workgroup builds produce verbose logging.

Value

YES to generate verbose shared-workgroup-builds logging. Default: NO.

XCMaxNumberOfDistributedTasks

Description

Specifies the maximum number of concurrent shared-workgroup-build tasks.

Value

Positive integer. Default: 25.

Debugging User Defaults

PBXGDBPath

Description

Identifies the gdb binary Xcode uses for debugging.

Value

Absolute pathname. Default: <Xcode>/usr/bin/gdb for local debugging and /usr/bin/ssh for remote debugging.

PBXGDBDebuggerLogToFile

Description

Specifies whether Xcode logs its communications with GDB to a file. This file can be sent to Apple when reporting problems with the debugger.

Value

YES to log interactions. Default: NO.

Important

Logging Xcode/GDB interactions reduces the debugger’s stepping performance.

See

“PBXGDBDebuggerLogFileName.”

PBXGDBDebuggerLogFileName

Description

Specifies the file to which Xcode/GDB communication is logged when Xcode/GDB–communication logging is active. This file is rewritten for every debugging session.

Value

Absolute pathname. Default: /var/tmp/folders.<uid>/Temporary Items/XCGDB-<program_name>-<Xcode_pid>.

See

“PBXGDBDebuggerLogToFile.”

SCM and Snapshots User Defaults

XCSnapshotDiskImagePath

Description

Specifies the location of the snapshot repository.

Value

Pathname. Default: ~Library/Application Support/Developer/Shared/SnapshotRepository.sparseimage.

XCSCMLogSize

Description

Specifies the maximum size (in kilobytes) of the SCM log.

Value

Positive integer. Default: 500.

PBXPerforceToolPath

Description

Identifies the p4 binary.

Value

Absolute pathname. Default: /usr/local/bin/p4.