Quickies for Xcode

General

Adding AppleHelp [permalink]

Create a "AppName Help" directory in your English.lproj.

Add an index.html Put in these headers:

<head>
  <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
  <title>AppName Help</title>
  <meta name="AppleTitle" content="AppName Help">
  <meta name="AppleIcon" content="AppName%20Help/images/icon-name.png">
  <meta name="AppleFont" content="Lucida Grande,Helvetica,Arial">
  <meta name="AppleSearchResultsFont" content="Lucida Grande,Geneva,Arial">
  <meta name="robots" content="noindex">
</head>

Along with your actual help content.

Drag the AppName Help directory into your XCode project. When Adding, make sure "Copy items into destination group's folder" is unchecked, and select "Create Folder References for any add folders". You wnat XCode to preserve your AppName Help directory.

Add these to your Info.plist:

<key>CFBundleHelpBookFolder</key>
<string>AppName Help</string>
<key>CFBundleHelpBookName</key>
<string>AppName Help</string>

Build, run, and cross your fingers. If Help.app is already running, you may want to exit it.

Adding credits to your about box [permalink]
If you have a file called "Credits.html" or "Credits.rtf", the contents of that file will be added to your about box. If your project doesn't have one already, you can use Xcode to add an empty file and put it in your English.lproj folder. Make sure you add it to your project.
Apple-Generic Versioning [permalink]
You can use agvtool do to apple-style generic versioning, which has two version numbers - one's a float that's monotonically increasing, and the other is a "marketing" version, that can be things like "1.0.4b34". Courtesy of Chris Hanson from a mailing list posting:
Set your Versioning System (VERSIONING_SYSTEM) to "apple-generic".
Set your Current Project Version (CURRENT_PROJECT_VERSION) to some floating point value that you'll increment every build. You could just start at 1, unless you already have builds out there with other numbers.
This will generate and build a source file automatically that defines two globals whenever you build your project. One is a double corresponding to CURRENT_PROJECT_VERSION, the other is a string. The file is a derived source file; it won't be added to your project, but it will be built with it.
If you're building a framework, there are other build settings you'll probably want to set as well, such as Current Version (DYLIB_CURRENT_VERSION), Compatibility Version (DYLIB_COMPATIBILITY_VERSION), and VERSION_INFO_PREFIX.
To update the version number, you can use agvtool next-version or agvtool new-version.
Changing extension for a bundle [permalink]
The default extension for a CocoaBundle is ".bundle". To change it to something else, use the WrapperExtension target property. Select the top-most item in the groups and files list, show the Info panel, choose Styles, and look for Wrapper Extension. Set that to what you want (such as "service"). Don't include the dot.
Changing the default Project Builder projects [permalink]
Don't like something about the default project that Xcode gives you? Look in /Library/Application Support/Apple/Developer Tools/Project Templates/ and edit the projects there.
(For Project Builder, go to /Developer/ProjectBuilder Extras/Project Templates/ and edit the projects there. The changes will take effect next time you create a new project.)
Command-line building from xcode [permalink]
xcodebuild is the pbxbuild equivalent. To get a development build, you'll need to specify the style:
% xcodebuild -buildstyle Development
Debugging unit tests from the command-line [permalink]
First, find the .octest file of interest:
```
% find . -name "*.octest" -print
./build/Debug/Tests.octest
```
Then gdb Tools/otest:
```
% gdb /Developer/Tools/otest
```
Then run it with the name of the bundle:
```
(gdb) run ./build/Debug/Tests.octest
```
Enabling "control reaches end of non-void function" [permalink]
One nice gcc warning that's not enabled by default is one that complains if you exit from a function (by falling off the end) without returning anything. This is an easy error to make, and can be hard to track down (especially if you do it in an objective-C init method). To enable this warning, add "-Wreturn-type" to the "Other C Flags" setting in your favorite build style.
Fixing undefined symbols when building plugins [permalink]
If you have a plugin defined as a "Cocoa Bundle" target in Xcode, and your plug-in inherits from a class that's defined in the application, you may get a build error like:
```
ld: Undefined symbols:
.objc_class_name_BWTrackerPlugin
```
You can fix this by adding -undefined dynamic_lookup to the "Other Linker Flags" of the Build Tab of the Target Settings for your plugin (whew!). You also need to make sure that the "Mac OS X Deployment Target" is 10.2 or later before using this flag.
Hiding TOC bar in xcode permanently [permalink]
Thanks to Jens Bauer who sent this my way. "When I option-double-click an object in my source-code, I got a surprise with newer Xcodes. There's a huge TOC bar in the left side, forcing me to have a large window, that overlaps my source-code, so I can't look at the documentation and type at the same time. Furthermore it makes the sentences very 'tall', which I can't get used to. So I dropped my coding, went for a hunt. I wanted to go and get rid of that annoying demon. I found it and cast it out (By hand!)"
Here's how Jens cast out that demon. It's two different edits:
To make the TOC section (left side bar) of the developer documentation default to be hidden, do as follows:
Before you begin, make the two files and their parent-folders writable.
In the file....
/Developer/Documentation/DocSets/com.apple.ADC_Reference_Library.CoreReference.docset/Contents/Resources/Documents/documentation/Resources/CSS/frameset_styles.css
...change the line...
#bodyText { margin-left: 210px; }
...to read...
#bodyText { /* margin-left: 210px; */ margin-left:10px; /* TOC-FIX */ }
...And in the file...
/Developer/Documentation/DocSets/com.apple.ADC_Reference_Library.CoreReference.docset/Contents/Resources/Documents/documentation/Resources/JavaScript/page.js

...add the following somewhere in initialize_page() function, for instance at the bottom, right before the closing brace...
showHideTOC('hide'); // TOC-FIX
...now you have a much better view!!
Note that you'll need to apply this patch when the docs get upgraded.
How do I add a new folder to my Files view? [permalink]
Select the folder you want the new folder to be a child of. Select Project->New Group. Give it a name. Note that the hierarchy of files in Xcode is a fantasy of the project, and doesn't necessarily reflect what's actually in the file system.

IBOutlet collection syntax [permalink]

@property (strong, nonatomic) IBOutletCollection(XXLaneView) NSArray *laneViews;

Moving archived apps from one machine to another [permalink]
To move your archived apps from one machine to another (say you're upgrading to some shinier hardware or doing a nuke-and-pave install), you can find your old archived apps at:
```
~/Library/Developer/Xcode/Archives
```
Mysterious duplicated symbols [permalink]
This killed a big chunk of time, so I figured I better record it here. While building a C++ shared library, I was getting errors like:
ld: multiple definitions of symbol __ZN13CaptureWidgetD2Ev /Users/blah/blah/build/./capture.build/Debug/capture.build/Objects-normal/ppc/capturewidget-F17F43C0.o definition of __ZN13CaptureWidgetD2Ev in section (__TEXT,__text) /Users/blah/blah/build/./capture.build/Debug/capture.build/Objects-normal/ppc/capturewidget-F17F43C0.o definition of __ZN13CaptureWidgetD2Ev in section (__TEXT,__text)
This is especially annoying, because the same object file is listed as having a duplicated symbol. If you take out the file from being compiled, you get undefined symbols for that particular source file, and if you put it back in, you get duplicated symbols.
Turn out the problem is that Xcode (somehow) added the C++ file to the "Build Sources" phase of the target. It happily generated two identical object files, and proceded to link them (hence the error), but doesn't get the reporting information correct (hence saying that both symbols come from the same file)
Open documentation for a symbol [permalink]
Say you have "NSFishmonger" in your code, and you want to see the header. Option-double-click on NSFishmonger and it will bring up the header file.
Open header for a symbol [permalink]
Say you have "NSColor" in your code, and you want to see the header. Command-double-click on NSColor and it will bring up the header file.
Renaming "MyDocument" [permalink]
I find the default name "MyDocument" that Xcode uses for new document-based Cocoa apps to be annoying, sounding more appropriate for Fisher-Price toys than professional software. Renaming all of the moving pieces in Xcode can be a bit daunting, and I don't want to edit the project template, since those tend to get revised as time goes on. This is what I do:
1. make the new project
2. replace MyDocument with the newDocument name (BWGraphDocument here):
  perl -pi -e 's/MyDocument/BWGraphDocument/g' *.[hm] *.xcodeproj/* *.plist
3. rename the document files:
  mv MyDocument.h BWGraphDocument.h mv MyDocument.m BWGraphDocument.m
4. rename the nib file:
  mv MyDocument.nib BWGraphDocument.nib
5. open the nib file, drag in your document header and change the class of the File's Owner to the new class. Delete the MyDocument type.
Runing a unit test in ppc mode [permalink]
Say your xcode project happily runs unit tests in i386 mode. You're about to land something that does byte-swapping, and you want to make sure it's sane in PPC mode, and you haven't turned on your G5 in months. You can do this command-line styles on your ICBM (assuming your project doesn't already do ppc and i386 unit tests). Build your test, and use translate to run the powerPC side of the world:
```
% xcodebuild -configuration Release -target "Test All" -project Tests.xcodeproj NATIVE_ARCH="i386 ppc"

% /usr/libexec/oah/translate /Developer/Tools/otest build/Release/Tests.octest
```

Running a specific unit test from the command line [permalink]

% /Developer/Tools/otest -SenTest  ClassName ./build/Debug/TheUnitTest.octest

Running a unit-test from the command line [permalink]

% /Developer/Tools/otest path/to/build/Unittest/TheUnit Test.octest

Setting compiler flags on a per-file basis [permalink]
Sometimes you need to set compiler flags on a per-file basis, like you need to suppress a warning in one place or set a one-off #define, but not for the entire project. You can set these flags in the build tab of the Get Info window of the source file in the target's compile sources build phase. If you get info on the source file in other places in Xcode, there's no build tab, and you're left with that "Am I crazy? I know I've seen that setting somewhere before, but where is it? I better go back to listening to Finnish polkas 24/7 and give up this software thing" kind of feeling.
Silence Xcode's beep on an unmatched brace. [permalink]
Xcode likes to beep on an extra paren, brace, or bracket. That drives me nuts. You can turn it off via:
```
% defaults write com.apple.dt.Xcode DVTTextBeepOnNonMatchingBrace -bool NO
```
Toggle between the source file and its header file. [permalink]
comand-option-up arrow
Treat warnings as errors [permalink]
In Xcode, there's a handy "Treat Warnings as Errors" checkbox. I usually use the search dealie with "werr" to find the setting.
(In Project Builder, open the Targets tab, double-click the target, go to the "Build Settings" tab, scroll down to Build Settings, look for WARNING_CFLAGS. Edit that, and add -Werror to what's already there.)
Turning off Xcode's "Undo past save" warning [permalink]
For some reason, Xcode thinks that an undo past the last save is something horrible that you need to be warned about. After living with unstable software, cmd-S is a habit, and undoing past it is No Big Deal. Really. Here's how to turn it off:
```
% defaults write com.apple.Xcode XCShowUndoPastSaveWarning NO
```
Turning off ZeroLink in all of the project templates [permalink]
I loathe ZeroLink. It causes more problems than it fixes. The Xcode guys must love it dearly. The new .xcconfig files in Xcode 2.1 won't let you turn it off, rendering those files useless to me. The Official Apple suggestion is to edit all of your project templates (?). Here is a quick script that'll churn through all of the project templates (and also your own projects) and turn off ZeroLink.
```
% cd '/Library/Application Support/Apple/Developer Tools/Project Templates'
% find . -name "*.pbxproj" -exec perl -pi -e "s/ZERO_LINK = YES/ZERO_LINK = NO/g" {} \; -print
```
Using Objective C++ [permalink]
name your source file blah.M (upper case M), or name your source file blah.mm (two lower case Ms). It's best to use .mm because of the case-insensitive (yet case-preserving) nature of HFS+
XCode's default projects [permalink]
XCode looks in /Library/Application Support/Apple/Developer Tools/Project Templates/ for the templates for its projects. You can put your own project templates here, and tweak the existing templates (for instance, Xcode 1.1's Cocoa projects have a compiler warning in main.m, which is really annoying for those of use who treat warnings as errors. You can go into /Library/Application Support/Apple/Developer Tools/Project Templates/Application/Cocoa Application/ and fix that warning if you wish.

Hacks

Blanket Disabling of ZeroLink [permalink]
(see also ZeroLink Must Die.
This find will grovel around project files and turn off ZeroLink. You can start at the path here to turn it off in all of your Xcode templates, and you can also point the find at your own XCode projects. Make backups first if you're feeling squeamish or your stuff isn't under version control.
```
% cd '/Library/Application Support/Apple/Developer Tools/Project Templates'
% find . -name "*.pbxproj" -exec perl -pi -e "s/ZERO_LINK = YES/ZERO_LINK = NO/g" {} \; -print
```
Changing __MyCompanyName__ [permalink]
You've probably noticed that source files generated from within XCode include a comment block header:
```
//
//  TapDance.h
//  Groovilicous
//
//  Created by markd on 7/25/08.
//  Copyright 2008 __MyCompanyName__. All rights reserved.
//
```
With the __MyCompanyName__ placeholder. There is no UI to change this, for obvious reasons. (Why would anyone want to easily and conveniently change something they'll otherwise need to edit in each and every source file they create. That's unpossible). The obvious solution is to drop to the terminal and run the straightforward command:
```
% defaults write com.apple.Xcode PBXCustomTemplateMacroDefinitions '{"ORGANIZATIONNAME" = "Borkware";}'
```
Seemple, no? Zee trick, she is doone.
Could not open the application package [permalink]
If you get a mysterious Xcode hang, and then the alert "Could not open the application package", check the date and time on the device. For some reason iDevices eschew NTP and don't update their clocks, and can sometimes under conditions of battery drain revert to times in the past and stay there.
Installing unix tools with Xcode 5 [permalink]
Xcode 5 removed the unix tool download from the UI. It's also hidden fun things like /usr/include
Here's an easy way to fix this:
% xcode-select --install
This will kick off a download of the tools, and install them.
Making "edit all in scope" work [permalink]
Xcode's "Edit All in Scope" feature is inexplicably tied to visible syntax colorization (actually, only Edit All in Scope for object pointers is tied to this, scalar variables and pointers work fine otherwise). So if you're not getting the Edit All in Scope menu item to enable, make sure "Color indexed Symbols" is turned on in the Xcode "Fonts and Colors" preferences.
This advice brought to you by a DTS incident.
Quieting Xcode 8 log spew [permalink]
Xcode 8 logs an embarrassingly large amount of worthless information when running an app. (yes, multiple radars have been filed and subsequently duped into oblivion.)
You can work around it by setting this environment variable pair in your Run/Arguments scheme thing:
```
OS_ACTIVITY_MODE=disable
```
Suppressing static analyzer for a file [permalink]
Sometimes you have a crufty old file in your project that generates static analyzer warnings, but you're not in a place to fix them (like one of my old old projects has some zip/unzip code that causes compiler heartburn, but currently works). You can disable static analysis by passing these flags:
```
-Xanalyzer -analyzer-disable-all-checks
```
If you do this you should feel bad. I did this, and I feel bad.
Turn debugging on with Xcode's indexer [permalink]
Got weird problems with Xcode's indexer? You can crank up its debugging log level.
```
% defaults write com.apple.dt.xcode IDEIndexingClangInvocationLogLevel 3
```
Turn off Xcode project navigator modifying the filesystem [permalink]
One of the worst misfeatures of Xcode9 is "hey, you moved stuff in the project navigator, I'm a gonna screw with your file system with no way to opt out!" This seems to turn it off for now:
```
% defaults write com.apple.dt.Xcode IDEDisableStructureEditingCoordinator -bool YES
```
Turn off xcode's brace-matching animation [permalink]
```
% defaults write com.apple.dt.Xcode DVTTextShowMatchingBrace -bool NO
```
I <3 Zach Waldowski for this tidbit.

Tools

XCTest Macros [permalink]
Quick list of Xcode unit testing assert macros.

XCTAssertNil (expression, ...)
XCTAssertNotNil (expression, ...)

XCTAssert (expression, ...)
XCTAssertTrue (expression, ...)
XCTAssertFalse (expression, ...)

XCTAssertEqualObjects (expression1, expression2, ...)
XCTAssertNotEqualObjects (expression1, expression2, ...)

XCTAssertEqual (expression1, expression2, ...)
XCTAssertNotEqual (expression1, expression2, ...)

XCTAssertEqualWithAccuracy (expression1, expression2, accuracy, ...)
XCTAssertNotEqualWithAccuracy (expression1, expression2, accuracy, ...)

XCTAssertGreaterThan (expression1, expression2, ...)
XCTAssertGreaterThanOrEqual (expression1, expression2, ...)
XCTAssertLessThan (expression1, expression2, ...)
XCTAssertLessThanOrEqual (expression1, expression2, ...)

XCTAssertThrows (expression, ...)
XCTAssertThrowsSpecific (expression, exception_class, ...)
XCTAssertThrowsSpecificNamed (expression, exception_class, exception_name, ...)

XCTAssertNoThrow (expression, ...)
XCTAssertNoThrowSpecific (expression, exception_class, ...)
XCTAssertNoThrowSpecificNamed (expression, exception_class, exception_name, ...)