When new developers are looking to write APE modules for OS X, I see a common problem that I didn't even know existed. They often have no idea whatsoever how to debug them without using gdb in the terminal. It never occurred to me that this might be an issue. We don't seem to mention it in the APE SDK even though we most obviously should. Well, it's a really easy task to do and I'll describe the two different methods required to debug APEs (and other plugins) from within Xcode. This stuff also works with Preference Panes if you set the System Preferences as your executable.

First, make sure your APE project is open. Then choose "New Custom Executable" from the "Project" menu. If the host application is simply a Mach-O packaged application (Carbon or Cocoa), just click the choose button and choose the application that will be the Plugin's host.

However, if it is a Carbon CFM application (Packaged or non-Packaged), the procedure is a little bit more difficult. Again, start out by choosing "New Custom Executable" from the "Project" menu in Xcode. Set the Executable name to what you want to be executable and choose the executable using the Choose button.

Now, this is where it gets a teensy bit more difficult. In the project window, double-click on the new "Word 2004" executable to open the settings window for that executable.

It will show the below settings window. You need to copy the executable path from the text box that labeled "Executable Path" and then replace it with /System/Library/Frameworks/Carbon.framework/Versions/A/Support/LaunchCFMApp (this is the thing that launches CFM applications, after all).

After you edit the Executable path, you need to move to "Arguments" tab in the executable settings window.

Click the little "+" (plus) button underneath the arguments list and then paste in the path you had previously copied. In this example, "/Applications/Microsoft Office 2004/Microsoft Word". If the executable contains spaces or anything else out of the ordinary, you must enclose it in quotes or else you will get an executable not found error when debugging or trying to otherwise launch the executable from Xcode.

If you have a packaged CFM application (like Illustrator), you must enter the full path to the actual executable such as "/Applications/Adobe Illustrator CS/Illustrator CS.app/Contents/MacOSClassic/Illustrator CS". You might notice the lack of quotes in the arguments for Illustrator CS in the window below. That's because I got the path by dragging the application to the terminal which properly escapes the characters the default shell doesn't like.

After you've set up all the host applications in Xcode, you can debug your Plugins in Xcode by just running the application in debug mode (Choose "Debug Executable" from the "Debug" menu in Xcode). Any breakpoints you set up in Xcode will work assuming you have debug symbols turned on the in the Plugin. Only the settings for your plugin matter, debugging does not depend on the settings used to build the host application.

As a bonus, if you are debugging two plugins and have both projects open in Xcode, Xcode will break on the breakpoints set up in either plugin. Very good for when you are writing two plugins and think they are interfering with each other. Even if it does cure your canker sores.

Always turn off ZeroLink when using Xcode. Especially when writing full applications. It just sucks and is the number one cause of newbie confusion. It has its purposes, but should not be on by default.