Running a program opens the Debugger Console window, shown in Figure 18-2. You can reopen this window at any time using the Run

Figure 18-2. FIGURE 18-2

You can modify these I/O connections, along with many other aspects of your program's execution environment. See the "Custom Executables" section later in this chapter for more details.

Whenever the executable is running, the Run/Debug button changes into a Stop button. You can unceremoniously terminate the running program (equivalent to a kill -KILL command or a Force Quit) using the Stop button or by choosing the Run

The active executable determines what program is launched when you choose any of the run or debug commands. You can change the active executable using the Project

In a number of circumstances this might not happen automatically. This is especially true when switching to or from an active target that does not produce an executable. Switching from an application target to an aggregate target (which produces nothing) or a framework target (that doesn't produce anything that can be executed on its own) does not change the active executable. In these circumstances, you'll need to choose the active executable yourself.

You may sometimes want to launch a different executable from the one produced by the target. Say you are working on the Server application, but need to test it using the Client application. Select the Server as the active target and then switch the active executable to the Client. When you Build and Run, the Server gets built, but it's the Client that gets launched.

For the vast majority of projects, the executable produced by your application target is the executable that you want to run or debug. If you have a special situation, you may need to modify the environment in which your executable runs or create a custom executable. Both are explained toward the end of this chapter in the "Custom Executables" section. For now, you'll concentrate on debugging simple executables produced by application and command-line targets. Everything here applies to custom executables as well.

Like most modern integrated development environments (IDEs), the Xcode application doesn't perform the actual debugging — or compilation, or linking, or profiling — of your application. Xcode simply provides an intelligent interface to the command-line tools that do the bulk of the work. In the case of debugging, the work is usually done by gdb, the GNU Debugger.

I say usually, because Xcode can also use other debuggers. It understands the JavaBug and AppleScript debuggers, but if you're doing Mac OS X or iPhone OS development, you'll be using gdb.

Xcode doesn't try to hide the debugger; there are plenty of places where you can interact with the debugger directly. What it tries to do is eliminate much of the tedium of using command-line debuggers by replacing the command line with an interactive, graphical user interface.

So while you're working your way through this chapter, keep this in mind:

Another great advantage to using an intermediate debugger is that your debugger interface remains largely the same regardless of the target application environment. Xcode can debug an application in any of the following environments:

Debugging an application running on the same computer system is the most common scenario, but by no means the only one. The section "Remote Debugging," later in this chapter, shows you how to debug a process interactively that is running on a different computer system.

iPhone application development would seem like it is worlds apart from desktop application development. While the design and implementation might be substantially different, the development tools remain almost identical.

You might have expected a substantial portion of this chapter to be dedicated to the iPhone simulator and iPhone native debugging, but there's really very little to say. Though there's some prerequisite configuration required before an iPhone or iPod Touch can debug applications (see Chapter 22), there is virtually no difference between debugging an iPhone application running on an iPod Touch and debugging a Cocoa application running on your development system. Almost everything in this chapter applies to both.

Breakpoints are described in detail in the "Breakpoints" section of this chapter, but here's the short lesson:

The red arrow in the gutter, shown in Figure 18-3, indicates the line of code containing the CPU's program counter. This is, essentially, where your program is executing — with some caveats that I'll get to in a moment.

Running and Stepping Through Code

In between the task and stack frame pop-up menus are the debugger actions. These are listed, from left to right, in the following table:

ACTION	COMMAND	SHORTCUT
(De)activate Breakpoints	Run	Control+Command+
Continue	Run	Option+Command+P
Step Over	Run	Shift+Command+O
Step Into	Run	Shift+Command+I
Step Out	Run	Shift+Command+T
Debugger Window	Run	Shift+Command+Y
Console Window	Run	Shift+Command+R

The first five actions are described in detail in the "Controlling the Debugger" section. The last two simply open the debugger window (see "The Debugger Window" section) or the debugging console window (already mentioned in the "Monitoring Your Process" section).

Hover Step Controls

If you hover your cursor over a line number in the gutter that corresponds to executable code, or over a function or method name in the code, one of a number of step controls appears.

Hovering the cursor over the currently executing code line reveals a tiny continue button, as shown underneath the cursor in Figure 18-7. If you carefully slide the cursor over to the button and click it, Xcode lets the program continue executing.

Figure 18-7. FIGURE 18-7

Hovering the cursor over any other executable line in the gutter reveals a continue to here button, as shown in Figure 18-8. The continue to here action sets a temporary breakpoint and then continues execution. Assuming the application doesn't encounter another breakpoint first, the process will run until it gets to the line over which you were hovering.

Figure 18-8. FIGURE 18-8

Note

The Continue to Here command can also be found in the contextual menu when you Right/Control-click a line the gutter. This can be faster than trying to use the hover controls.

Hovering over a function or method call, as shown in Figure 18-9, reveals a targeted step into button. Much like the continue to here action, it sets a temporary breakpoint at the beginning of the function you're hovering over and then lets the application continue execution. The program runs until it steps into the function you targeted.

Figure 18-9. FIGURE 18-9

Variables in your running application can be examined simply by hovering the cursor over the variable name. This displays a datatip, as shown in Figure 18-10, that reveals the type, name, and value of the variable.

Figure 18-10. FIGURE 18-10

Simple variables display a single row describing its type, name, and current value.

Complex variables, like objects and structures, include a disclosure triangle that expands to reveal its individual instance variables or fields. Complex instance variables can themselves be expanded, letting you "drill down" in search of the variables for which you're looking.

By default, the expansion of subvariables is automatic, but you can turn that off. Clicking the disclosure triangle of an expanded variable collapses it again.

A datatip row may contain one of two active controls. One is a value editor. Most mutable scalar values can be changed simply by clicking its value in the datatip, also shown in Figure 18-10.

The other control is a datatip menu, which appears as two arrows on the left-hand side of the datatip. Clicking the arrows pops up the a datatip menu, as shown in Figure 18-11.

Figure 18-11. FIGURE 18-11

From the datatip menu you can dump (print) the variable's value to the debugger console, open the variable in its own window, jump to the symbol's definition or documentation, enable/disable data formatters, control the order in which subvariables are displayed, and turn datatip auto-expansion on or off.

Variable windows, memory browser windows, types, and data formatters are all described later in the "Examining Data" section.

The threads pane displays the stack of the active thread, as shown in Figure 18-13. Each entry in the list represents a single stack frame, and the selected entry defines the active stack frame. A frame contains the return address of the caller and all of the function's automatic variables. If the address of the function can be translated into a name, the function's name is displayed. Otherwise the address of the function is listed.

Figure 18-13. FIGURE 18-13

When you stop an application in the debugger, the debugger stops all threads, but the pane displays the call stack of the thread that hit the breakpoint. The left column indicates the relative depth of each function in the call stack. The name of the function currently executing is displayed at the top of the list and always has a stack depth of 0. The name of the function that called the currently executing function is listed underneath that and has a stack depth of 1, and so on all the way back to the function that started the thread.

The contents of the variables pane and the initial contents of the editor pane are determined by the current selection in the threads pane. When you stop an application, the current (top) function in the call stack of the stopped thread is selected. Select another function in the call stack, and the variables and editor pane change to display the variables and execution location in that function. This allows you to examine not only the variables of the current function, but also the variables and calling address of the functions that called the current function.

You can view another call stack by selecting a different thread from the pop-up menu at the top of the pane, as shown in Figure 18-14.

Figure 18-14. FIGURE 18-14

You can also step through the threads in your application using these two commands:

Change to another thread, and you can examine the local variables and calling address of any frame on that thread's stack. Depending on the language and run time library used, threads may or may not have readable descriptions. If they do, the description will appear next to the thread's identifier.

The Run

The listing or editor pane displays the source code of your application, a disassembly listing, or both. The latter combination is shown in Figure 18-15. The debugger chooses a view automatically when it needs to display a breakpoint or calling location. If the debugger can correlate the program location with a source file, it displays the source code in an editor pane.

Figure 18-15. FIGURE 18-15

This is a full-featured editor pane, allowing you to edit your source code right in the debugger window. It also contains all of the breakpoints, hover step controls, and datatips described earlier in the "In-Editor Debugging" section. The only thing it doesn't have is the debugging strip, because all of those functions are provided elsewhere in the debugger window.

You can choose an alternate source code view using one of the following commands:

If the debugger cannot determine a source file that corresponds to the program's location, there is no source view; it displays only the disassembly of the machine codes and the disassembly display commands have no effect. Similarly, only languages that compile directly into assembly language have a disassembly view; Java and AppleScript programs do not show a disassembly view of their byte code or tokens.

Breakpoints and the current execution location are indicated in the gutter of the editor pane. Breakpoints appear as dark blue (enabled), light blue (disabled), or yellow (invalid) markers. The program counter (PC) indicator appears as a red arrow. The breakpoint and location indicators are so critical to the effective use of the debugger that the gutter display is turned on whenever you are in a debug session. If your Xcode Preferences are set not to display the gutter in the editor, the gutters disappear again at the end of your debug session.

The program-counter indicator always points to the current execution location for the selected thread and stack frame. In a source file, it points to the source line most closely associated with the program-counter position. In the disassembly listing, it points to the exact instruction. If the top (level 0) stack frame is selected, the arrow indicates where the current thread is executing. Select another stack frame in the list and it indicates the location where the stack frame above it was called.

The variables pane displays the known data variables for the selected stack frame. The key word here is known. The debugger must have debug symbol information that describes the structure for the selected stack frame. If there is no description available, it cannot interpret or display any data values on the stack and the pane is empty. You will encounter this most often when you stop an application in a system framework or library routine.

Value Summaries

The Summary field is an intelligent interpretation of the variable's contents. Using a system of data formatters, the field can display a more human-readable summary of the object or structure's contents. Xcode has numerous data formatters built in. A simple example is the NSCalendarDate object. Without data formatters, an NSCalendarDate reference would display as an object at a particular address. Exposing its member values would display several variables, shown on the left in Figure 18-16. The _formatString variable contains something cryptic, the _timeZone value contains a pointer to an opaque object, and the _timeIntervalSinceReferenceDate variable contains a big floating-point number. Unless you can convert seconds-since-the-epoch to a calendar date in your head, none of these values are particularly informative.

Figure 18-16. FIGURE 18-16

This is where data formatters come to the rescue. Xcode includes data formatters for strings, dates, and even the time zone object. Turn data formatters on and the display changes to something far more useful, shown on the right in Figure 18-16. The format string and time zone values are now easily readable, and the date object reference itself displays a practical representation of the date and time encapsulated by that object. You learn how to create your own data formatters, which is even more powerful, later in the "Data Formatters" section. You can enable and disable data formatters using the Debug

Variable Types

There is also an optional Type column that you can display using the Run

Note

Showing the Type column is probably the first thing I do after opening the debugger window for the first time. Alternatively, you can also Right/Control-click any variable and choose Show/Hide Type Column from the pop-up menu. Sadly, Xcode doesn't preserve this setting between Xcode sessions.

There's a lot more to examining data in the debugger. This brief overview should give you some idea of what you're looking at while you progress to the more practical topic of controlling the debugger and setting breakpoints. Until you can stop your application, there's no data to examine.

The Pause and Continue commands are immediate and self-explanatory. They share the same menu item, toolbar button, and keyboard shortcut. The Pause command is active whenever the process is executing, and the Continue command is active whenever it is suspended.

Generally, the Pause command isn't very useful for working GUI applications, because it tends to suspend the application in a run loop. You will probably find it most edifying when your application is stuck in an endless, or seemingly endless, loop. It can also be helpful to suspend your application while you think about your next move or contemplate where to set a breakpoint. You don't have to stop the program to set a breakpoint, but you don't necessarily want your application running amuck while you decide where it should go.

Step Over and Step Into are the two most commonly used debugger control commands. Step Over lets you walk through the logic of a single function, ignoring the details of other functions that it might call. Step Into traces the execution of the program one step at a time, regardless of where that leads.

The Step Over command is intelligent about recursive functions. Stepping over a function that calls itself does not stop until all nested iterations of the function have executed and returned, even if that entails executing the same code position that you are stepping over.

If the source line contains multiple calls, the Step Into command steps into the first function called. This is significant if a function passes parameters that are obtained by calling other functions. The example in Listing 18-2 illustrates this. If the debugger first stopped at this line and you issued the Step Into command, the debugger would step into getDefaultMode(), not setMode(). That's because the getDefaultMode function is called first to obtain the value of setMode's single argument.

setMode(getDefaultMode());     // reset the mode

After you return from getDefaultMode (see the Step Out command), the debugger again returns to this line of source code, but the CPU's program counter is now poised at the call to setMode. This time the Step Into command steps into the setMode function.

Step Into only steps into functions that have debug information and have local source files associated with them. You cannot step into library functions, framework APIs, or kernel code that was not compiled with full debug information. Attempting to step into such a function is treated like a Step Over.

Step Out is convenient for letting the current function complete its execution and return again to the point where it was called. It's common to step into a function simply to examine the values of its arguments. After you are satisfied the function is behaving correctly, you can then use Step Out to let the function finish and return to where it was called. The same issues about exceptional exits that apply to Step Over also apply here.

The special Step Into Instruction and Step Over Instruction perform the same actions as the Step Into and Step Over, but each only executes a single machine instruction. These functions work in either source or disassembly view, but are most useful when you're viewing both the source and disassembly of your program's code where the meaning of Step Into and Step Over becomes ambiguous.

Step Into Instruction is also away around the Step Into command's self-imposed limitation of never stepping into a function that doesn't have source information (like a library function). If the function being called has no source code available, Step Into Instruction still steps into it, automatically switching to a disassembly-only view, as required.

The continue to here command doesn't appear in the menu and has no keyboard shortcut. A continue to here button appears when you hover over an executable line number in the gutter. You can also use this, much quicker, shortcut:

The continue to here action creates a temporary breakpoint and starts your application running, just as if you had set a regular breakpoint and issued the Continue command. A breakpoint indicator is not visible in the gutter or anywhere else in Xcode, and the breakpoint is deleted as soon as it is hit. This makes it extremely easy to skip through blocks of code or around loops by simply clicking where you want to stop next. The same caveats about temporary breakpoints mentioned earlier apply here.

There are two kinds of breakpoints: source breakpoints and symbolic breakpoints. So far, this chapter has only dealt with source breakpoints. Source breakpoints are associated with a particular line in a source file. You set and see source breakpoints right in the gutter of the source file's editor pane.

Symbolic breakpoints are breakpoints that have been created for a particular symbol — that is, at the address of a symbol defined in the program. There are two important differences between a symbolic breakpoint and a breakpoint set at a line in a source file.

The most obvious is that you don't have to have the source file. Using symbolic breakpoints, you can set a breakpoint at the entry point of any library routine or framework API. For example, you could set a symbolic breakpoint at the free() function. Any code that calls the free(...) function would break into the debugger.

The other important difference is that the breakpoint address is not associated with a line in a source file. You could cut the function from one file and paste it into another, and the breakpoint would still work.

You find out how to create symbolic breakpoints shortly.

Breakpoint management gets far more interesting when you open the breakpoints window, shown in Figure 18-19. You can do this by choosing the Run

Figure 18-19. FIGURE 18-19

The Breakpoints window has two panes: a Groups & Files pane containing the Breakpoints smart group and a details pane listing the individual breakpoints. It should be noted that this is really just an abbreviated view of your project window, without the editor pane. Everything you can do in the Breakpoints window can be accomplished in the Breakpoints smart group and details pane of your project window.

You've seen breakpoints in editor panes more than a dozen times so far, but there's a somewhat obscure command for displaying some details about the breakpoint right in the editor pane, as shown in Figure 18-20.

Figure 18-20. FIGURE 18-20

The View

The enabled, auto-continue, and breakpoint condition can be edited right in the editor pane. This can be particularly handy when using the mini-debugger.

To delete one or more breakpoints in the breakpoints window, select the breakpoints in the window and press the Delete key. You can also select a group of breakpoints in the Groups & Files pane and choose the Delete command from the Right/Control-click contextual pop-up menu.

To delete a source breakpoint from within a source file editor, click and drag the breakpoint out of the gutter. You can also Right/Control-click the breakpoint and choose the Remove Breakpoint command.

The check mark column in the breakpoints list shows whether that breakpoint is enabled. You can enable or disable an individual breakpoint by ticking its check box. This is synonymous with clicking the breakpoint's indicator in the source file. Enabled breakpoints are dark blue; disabled breakpoints are light blue.

Selecting breakpoints in the Groups & Files pane lets you to enable and disable breakpoints en masse. Select any combination of breakpoints and breakpoint groups in the Groups & Files pane — these commands do not work in the details list. Right/Control-click one of the selected items and choose either the Enable Breakpoints or the Disable Breakpoints command from the contextual menu. Enabling or disabling a group sets the state of every breakpoint contained in that group.

Hold down the Option key and the Enable Breakpoints command turns into the Enable Only These Breakpoints command. This command enables the selected breakpoints, and then disables all other project breakpoints. This is a quick way of enabling a strategic group of breakpoints you want to focus on while simultaneously disabling all others.

To create a symbolic breakpoint, first select the Breakpoints group in which you want the breakpoint created. At the bottom of the details pane list is a special placeholder breakpoint with a border around the name Double-Click For Symbol. To create a new symbolic breakpoint, do just what it says, as shown in Figure 18-21.

Figure 18-21. FIGURE 18-21

The symbol can be any function name known to the linker. This can be a function in your own application or any system API or library to which your application is linked. For C function calls, just the name of the function is sufficient. If there is any ambiguity, Xcode prompts you to choose the specific symbol that you meant. In Figure 18-22, a breakpoint is set on the free symbol, and Xcode wants to know which "free" it's referring to.

Figure 18-22. FIGURE 18-22

Objective-C and C++ methods must be expressed in their complete form. To set a symbolic breakpoint at the isPrime: method of the SieveOfEratosthenes class, create a breakpoint for the -[SieveOfEratosthenes isPrime:] symbol. Note that the symbol must have a + or - sign indicating a class or member method. In this example, : indicates that the method takes a single parameter. Just like when you're using the @selector operator, isPrime and isPrime: are two different methods. If the method took a second BOOL parameter, the symbol would be something like -[SieveOfEratosthenes isPrime:ignoringMap:].

In C++, the symbol should be a complete, fully qualified, prototype of the method. If the NestOfBugs class contained a member function named catchMe that took a single integer as a parameter, the symbol to use would be NestOfBugs::catchMe( int i ). Unlike the Objective-C symbol, the name of the parameter is included exactly as it was declared in the class statement. gdb will not find the function without a complete copy of its declaration. The return type of a function is not part of its name.

Symbolic breakpoints do not appear as breakpoint indicators in the gutter of the source file editor pane, even if the symbol identifies a function in your source code. Other than the visual differences, symbolic breakpoints are just like source breakpoints and share all of the same capabilities and traits.

One of the first things you'll notice about breakpoints is that they always work. Although it might be gratifying to know that the technology is reliable, you may soon discover that it can be a curse as well. Setting a breakpoint in a function that gets called a million times is enough to wear out the button of any mouse if you have to click the Continue button 999,999 times. Furthermore, quite often the problem with a loop will be found at the end, not the beginning. Placing a breakpoint in the middle of a loop can be a study in tedium.

What you really want to do is break at the moment your application is doing something interesting or suspicious. For example, you want to break a loop on its last iteration or just when a parameter is NULL.

You can accomplish this by using a breakpoint conditional. In the Condition field of the breakpoint, enter any C Boolean expression. If the breakpoint is enabled and the conditional expression evaluates to true when the breakpoint is encountered, the breakpoint stops the program. Otherwise, the breakpoint is ignored and the program continues to run.

Conditional Breakpoint Example

The best explanation is an example. The following function calculates a factorial:

static long long int factorial( long long int n )
{
     if (n>=1)
         n *= factorial(n-1);
     return (n);
}

int main (int argc, const char * argv[])
{
     printf("20! = %lld
",factorial(20));
     return 0;
}

You build and run the application, and it produces the following output in the debugging console window:

20! = 0

Clearly, that's not the correct answer. You suspect that the problem is when n is small, so you set a breakpoint at the first line of the factorial() function (the line if (n>=1)). You start the program under the control of the debugger, and it immediately stops in the factorial function. The variable n has a value of 20.

You click Continue and the program recursively calls factorial again, causing the breakpoint to stop again; this time n equals 19.

You can see where this is leading. You'll have to restart the application another 18 times before you get to a value of n that's interesting. Though 18 isn't so bad, 180 would be, and 18,000 would be ridiculous in the extreme.

What you really want to know about is what happens when n is small (2 or less). To find out, you set a breakpoint condition, as shown in Figure 18-23. Now the breakpoint stops only when n is less than or equal to 2.

Figure 18-23. FIGURE 18-23

With a single breakpoint condition, you've skipped to the 19th invocation of the factorial function in a single debugging step. Now that you're here, you use the Step Over and Step Into commands to walk through the next few invocations of factorial and immediately see what the problem is: When n is 1, the if condition is still true, factorial(n-1) is called, which returns 0, and the multiplication zeros out the total.

The solution is change the conditional to if (i>1).

#if DEBUGGING
    int actualStrLen = strlen(str);
#endif
    strncpy(buffer,str,1024);

A common breakpoint condition is to simply ignore the next few hits. If you hit a breakpoint in a loop that's going to repeat 1,000 times and you want to know what happens toward the end of the loop, you just want to skip over the next 998 occurrences of that breakpoint. This is easily accomplished by setting a breakpoint's ignore count setting.

In the breakpoint window, find the Ignore Count column for the breakpoint and enter a non-zero integer. The next occurrences of that breakpoint will be ignored. To reactive the breakpoint, set the ignore count back to zero.

In addition to just stopping the program, breakpoints can also perform actions when they are encountered. When a breakpoint is taken, the program stops and control is passed to the debugger. If the breakpoint has breakpoint actions, the debugger immediately performs those actions.

To add or edit actions, expose the breakpoint's contents in the Breakpoints window. For source breakpoints, double-click the breakpoint in the gutter of the source file and Xcode takes you to that breakpoint in the Breakpoints window. Click the + button to add a new action. Click the − button to delete an action. You can't reorder actions, so when you're adding actions, use the + button above the point where you want to new action inserted.

After you've added an action, choose the type of action from the pop-up menu at the top. There are five kinds of breakpoint actions, as listed in the following table:

Log a Message

The Log command enables you to generate a message when the breakpoint occurs. How you receive this message is controlled by the two check boxes in the lower-right corner of the action, shown in Figure 18-24. Log outputs the message to the debugger console, and Speak uses the Macintosh text-to-speech technology to say the message out loud.

Figure 18-24. FIGURE 18-24

The message can contain any of the following special character sequences:

MESSAGE TOKEN	REPLACED WITH
%B	The name of the breakpoint
%H	The number of times this breakpoint has been tripped
%C	The comments attached to the breakpoint
@expression@	Any gdb expression

The open-ended @expression@ form permits you to include anything that the debugger can evaluate at that moment in the program. The example in Figure 18-24 shows a breakpoint that logs the following message:

testTimer fired, userInfo has 3 entries

The expression [[timer userInfo] count] is executed and the resulting value is inserted into the log message. Again, be very careful of side-effects when using expressions.

1 @interface QuickView : UIView {
 2     // ...
 3 }
 4 - (void)setValues:(id)info;
 5 @end
 6
 7 @implementation QuickView
 8
 9 ...
10
11 - (void)setValues:(id)info
12 {
13     // Configure view to display values...
14 }
15
16 @end

1 @class QuickView;
 2
 3 @interface ViewPool : NSObject {
 4     @private
 5     NSMutableArray *pool;
 6 }
 7 - (QuickView*)view;
 8 - (void)recycleView:(QuickView*)view;
 9 @end
10
11 @implementation ViewPool
12 ...
13 - (QuickView*)view
14 {
15     // Return an existing view from the pool, or load a new one.
16     QuickView *freshView;
17     if ([pool count]!=0) {
18         freshView = [[[pool lastObject] retain] autorelease];
19         [pool removeLastObject];
20     } else {
21         // Load the NIB and extract the single top-level object
22         freshView = [[[NSBundle mainBundle] loadNibNamed:@"QuickView"
23                                                    owner:nil
24                                                  options:nil]
25                      lastObject];
26     }

27     return (freshView);
28 }
29
30 - (void)recycleView:(QuickView*)staleView
31 {
32     [pool addObject:staleView];
33 }
34
35 @end

The earlier example of using breakpoints to set breakpoints glossed over a serious problem. The breakpoints with the actions will still break. After the breakpoint has been hit, and all of its actions have been executed, the debugger still stops your program and waits for instructions. In the example of trying to trap a call that occurs during a destructor, this defeats the purpose of having breakpoints created and deleted automatically. What you really want is for the breakpoint to execute its actions and immediately resume execution of your program. This is exactly what the continue option does.

The continue option is the CD-player-style "play" column in the breakpoints list, as shown in Figure 18-25. Checking this option for a breakpoint means that the breakpoint does not return control to you. The actions of the breakpoint are executed, and the program continues executing exactly as if you had clicked the Continue button.

Figure 18-25. FIGURE 18-25

The continue option makes all manner of debug automation and checking possible. There are, however, some hazards. Debug actions are executed asynchronously. That is, the debug action merely starts the action. The debugger does not normally hang around waiting for them to complete, so be careful about creating breakpoints that will start, or queue up, hundreds of breakpoint actions. This can be particularly annoying when you're using audio feedback.

The Shell Script breakpoint action has the Wait Until Done option that suspends the debugger and your program until the Shell Command completes. Breakpoint actions can be combined with a breakpoint condition. The breakpoint and all of its actions are executed only if the condition evaluates to true.

Pretend that you are working on a project with another programmer. You've isolated a problem using a complex set of breakpoints. How do you send those breakpoints to your team members so that they can reproduce the problem and fix it? Project breakpoints are saved on a per-user basis in the project, so you can't just give them a copy of the project document. When they load the project, they won't see any of the project breakpoints you've set. And scrawling breakpoint descriptions on napkins doesn't sound particularly efficient either.

The solution is to export the breakpoints to a file using the Export Breakpoints command. Select any set of breakpoints or breakpoint groups in the Groups & Files pane and Right/Control-click the selection. Choose the Export Breakpoints command to export the selected breakpoints to a text file.

The Import Breakpoints command creates a new subgroup with the name of the breakpoint export file and populates it with its contents. Rename and reorganize the imported breakpoints as you see fit.

As a single developer, you can use these commands to archive a collection of breakpoints for some future purpose or move some breakpoints between projects without resorting to making them global breakpoints.

Xcode provides a number of preconfigured breakpoints that you can insert by Right/Control-clicking a line in your source code and then selecting any of the breakpoint templates from the Built-In Breakpoints menu. You can also create your own breakpoint templates, which will appear in the same menu.

To create a reusable breakpoint, create and configure a breakpoint. Once you are happy with it, create a breakpoint group in the Groups & Files pane named Template Breakpoints (Right/Control-click and choose Add

Any breakpoints that appear in the Template Breakpoints group also appear in the Right/Control-click contextual menu in any source file's gutter. Creating a breakpoint from one of the templates inserts a breakpoint that's a copy of the breakpoint in the template. The only thing that is different is its location.

The Value column displays the primitive value of each variable. For scalar values, this is a numeric value. For structures and pointers to structures, it is the address of the structure or the value of the pointer. The default display format for scalar values is Natural. For signed integers and floating-point numbers, the column displays a signed decimal value. Unsigned integers display an unsigned decimal number. Character types display both the decimal and Unicode representations of the value. Pointers and structures are shown as hexadecimal memory addresses. The natural format is usually sufficient, but you can manually choose a different representation. The choices are as follows:

You can find these formats in the Run

You can also choose to examine the contents of a value or structure in a separate window. Double-click the variable name, choose the Run

If a variable type isn't even close to the type of data it represents, you can use the Run

Figure 18-27. FIGURE 18-27

Xcode then attempts to interpret the value of that variable using the type cast. This is particularly useful for generic types such as void*. As shown in Figure 18-27, the pointer to a string was assigned to a void* variable. By using the View Value As command, you can coerce the debugger to interpret the void* value as if it was a char* variable, shown on the right.

Sometimes you just need to look at memory. Using the Debug

Figure 18-28. FIGURE 18-28

The browser displays a block of memory in hexadecimal and ASCII formats, much like the hexdump command. The Address field determines the starting address of the display. Initially, this is the address of the selected scalar, structure, or object in the variables pane. If the selected variable is a pointer or object reference, the address is the value of that pointer (a dump of what the pointer points to, not a dump of the pointer's value). The Bytes menu lets you select how much memory is disassembled in the window. Choose one of the preset values or enter your own. Use the up and down arrows between the Address and Bytes field to move one page of memory forward or backward. The Word Size and Columns menus control the number of bytes in each column of hexadecimal values, and the number of columns in each line, respectively.

There is only one memory browser window. Selecting a new address using the View As Memory command simply changes the address in the Address field. The Address field has a pop-up menu that keeps a short history of previously viewed addresses. If you need to follow a pointer to another address that you find in a block of memory, simply copy the address from the hexadecimal listing and paste it into the Address field (prefixing it with 0x).

If you try to view memory that is outside the address space of your application, the memory browser displays A's for the bytes it can't access.

The Globals group in the variables pane contains a selected set of global variables that you want to examine. Normally, this group has nothing. It's impractical for this group to contain every global variable in your application's process space. The group could contain hundreds of variables, be impossible to navigate, and place a huge burden on the debugger display.

Instead, the group starts out empty. Use the global variables window, shown in Figure 18-29, to add variables to this group or merely browse the global variables in your application. You can open this window using the Run

Figure 18-29. FIGURE 18-29

The global variables window is divided between a list of modules on the left and the list of global variables in each module on the right. Select a module, and Xcode lists all of the global variables that your application has access to on the right. To search for a particular variable name, enter some fragment of the variable's name in the search field at the top of the window.

Figure 18-29 examines the global variables declared in a program named DataBlock. The listing tells you the filename the variable is declared in, its current value, and its type. By selecting the box in the View column, this variable is added to the Globals group in the variables pane. The viewed global variables are recorded in the user preferences of the project document. After these variables are added, they will always appear in the Globals group of your variables pane until they are removed or until the variable itself no longer exists.

Another way to view variables is through expressions. Expressions appear in the Expressions window, shown in Figure 18-30. You can open this window using the Run

Figure 18-30. FIGURE 18-30

These are debugger expressions and are subject to all of the limitations and caveats of breakpoint conditions. In the Expressions window, each expression acts like a variable. You can alter its display format or open it in a separate window. You can also add type casts to an expression to coerce the interpretation of the expression's value.

Expressions are interpreted within the context of the currently selected stack frame, and those expressions retain that context. In the example previously shown in Figure 18-30, there are two expressions that resolve to value of the integer i, but these two variables are from different stack frames. Each was added to the window and a different stack frame was selected in the threads pane. The first one was added while a function was executing, but that function has now returned. Therefore, the context that defined that variable no longer exists and the expression is marked as "out of scope."

To delete an expression, select it in the Expressions window and press the Delete key.

Expressions are very useful for examining the contents of array values. An expression like stack[1] examines the second element in the stack array. The expression buffer[index] examines whichever element the variable index refers to.

Creating your own data formatters is very easy. It is really nothing more than a format string with placeholders for values or expressions derived from the variable being summarized. Any regular text in the data formatter is displayed verbatim. There are two kinds of placeholders: references and expressions.

References are delimited by two percent characters (%reference%). A reference can refer to a single member variable by name. If the variable is contained in a substructure, use the appropriate period (.) separated variable name. You cannot use operators such as pointer dereferences or array indexes. For that, you need to use an expression. Taking the class that's defined in Listing 18-3, the reference to the integer record_no of DataBlock class would be %header.record_no%.

typedef struct {
    int record_no;
    unsigned long checksum;
} BlockHeader;

@interface DataBlock : NSObject
{
    @public
        BlockHeader     header;
        NSMutableData*  data;
}

An expression is any debugger expression; the same kind of expression that you can add to the Expressions window. In fact, it's good to think of an expression in a data formatter as an expression in the Expressions window, as you'll see in moment.

Expressions are contained between matching braces ({expression}). Unlike references, expressions do not assume the context of the value being examined. To refer to the object being examined, use the $VAR macro in the expression. $VAR will be replaced with the name of the variable when the data formatter is evaluated. Using the previous class as an example again, the expression to access the record_no value would be {$VAR.header.record_no}. If you're now guessing that you can refer to other variables in the context of the current stack frame, you're correct. However, this isn't a good idea, which is explained later. Limit your evaluation to the structure or object being examined.

The advantage of expressions over references is that they are more expressive. You can perform math, include conditionals, and even call member functions. Again using the class defined in Listing 18-3, here are some valid expressions:

Combining these two techniques, you can now create a data formatter for the DataBlock object type. Start by running the program and stopping the debugger with an instance of the DataBlock class in scope. Make sure that Run

Figure 18-31. FIGURE 18-31

After it has been entered, this text becomes the data formatter used for every instance of the DataBlock class. The debugger resolves the references and expressions for each instance, creating the more informative summary shown in Figure 18-32.

Figure 18-32. FIGURE 18-32

The syntax used for references and expressions can be extended to obtain other information about the value or expression. The final display value can be something different from the value to which the expression evaluates. The other types of information that can be extracted from an expression are chosen using one of the column selectors listed in the following table. The "column" you are selecting is one of the columns in the variables pane or the Expressions window. In essence, the result of a reference or expression is treated as if it had been entered into the Expressions window. The column selector lets you choose which column in the window will be used as the result of the expression. You can think of an expression result as an object with four properties (value, name, type, and summary) — the column selector lets you choose which property to display.

The type column (:t) can be useful for displaying the type or class of a member value. For example, if you have a class that manages a collection of homogenous objects, a data formatter of collection of {[$VAR lastObject]}:t would tell you what kind of objects your collection contains.

The summary column selector is the most useful. You can use it to construct data formatters from other data formatters.

To get a feel for creating your own data formatters, look at the following example. Let's assume you have a project with the DataBlock class shown in Listing 18-3, and a subclass named StampedDatablock, shown in Listing 18-4.

@interface StampedDataBlock : DataBlock
{
    @private
        NSCalendarDate*    createdDate;
        NSCalendarDate*    modifiedDate;
}

To create a custom data formatter for these two classes, follow these steps:

Figure 18-33. FIGURE 18-33

The first data formatter created for the DataBlock class summarizes its contents by accessing its record_no and data instance variables. The debugger now presents a much friendlier summary of the object's state.

The StampedDataBlock formatter is a little trickier. The StampedDataBlock class does not inherit the data formatter for DataBlock. Data formatters for each type are independent of one another.

Two problems are inherent in creating a data formatter for the new subclass. First, you don't want to repeat everything you wrote for the DataBlock formatter. Secondly, you don't want to write a formatter for the NSCalendarDate member object. The summary column selector lets you avoid both of these problems by setting the data formatter for the StampedDataBlock class to {(DataBlock*)$VAR}:s, created %createdDate%:s. The first expression casts the object to an instance of its superclass and obtains text that would appear in its Summary column, effectively calling the data formatter you created for the DataBlock class. The second reference obtains the value of createdDate and inserts what would appear in its Summary column, essentially using Xcode's built-in data formatter. The final result, shown in Figure 18-34, is a data formatter that extends the data formatter of its superclass using a built-in data formatter supplied by Xcode.

Figure 18-34. FIGURE 18-34

Data formatters can be very useful during debugging. You can create data formatters that quickly summarize the state of complex objects. This allows you to concentrate on the high-level logic of your application, rather than spending all of your time digging through the member variables of objects trying to decode their content. Writing data formatters, however, can be a frustrating experience. If there is anything the debugger doesn't like about your data formatter, it won't use it. The following table lists some of the more common problems you can encounter while creating data formatters:

If you are having problems getting a formatter to work, break it down into its individual components and subexpressions and try each one at a time. Slowly build up the expression until you get it working or find the element that thwarts your efforts. Try expressions without the column selector. Cast return values liberally. Replace macros and function calls with constants. Turn off ZeroLink. Add the same function call to your code and try debugging it.

Data formatters you define are stored in the ~/Library/Application Support/Apple/Developer Tools/CustomDataViews/CustomDataViews.plist file. Data formatters are global to all projects and are not stored in the project document. Sharing data formatters with other developers will require some copying and pasting, or you may just want to exchange CustomDataViews.plist files.

Although data formatters can do a lot, they are limited to what can be expressed in a format string. If you need a data formatter that exceeds these capabilities, you can develop your own data formatter plug-in. The descriptions for doing so are in the DataFormatterPlugin.h file, buried inside the Xcode application itself at /Developer/Applications/Xcode.app/Contents/PlugIns/GDBMIDebugging.xcplugin/Contents/Headers/DataFormatterPlugin.h. This file contains detailed information about formatter strings, the format of CustomDataViews.plist, and how to create a data formatter plug-in, among other topics.

In brief, you create a data formatter plug-in by creating a bundle. The bundle contains its own CustomDataViews.plist file. Unlike data formatter strings that you type into the debugger window, the data formatter strings in the bundle's CustomDataViews.plist file can call any of the functions defined in the plug-in bundle. The sample ManagedObjectDataFormatter project produces a data formatter plug-in for managed objects. You can find it by searching the Xcode documentation for ManagedObjectDataFormatter. Use this project as a template for creating your own data formatter plug-ins.

Like data formatters, many object-oriented languages have adopted conventions for converting any object into a textual representation. In Java, this is the toString() function. Objective-C uses the -[NSObject description] method. If you are using an object that supports one of these standards, you can use the Run

It's simple enough to poke a new value into a variable and continue executing, but what if the code itself is incorrect? Xcode allows you to fix that too.

This bit of magic — and it really is something close to magic — is a feature called Fix & Continue. As the name implies, it enables you to recompile code in your application and continue debugging it without restarting your program. Use of this feature depends on some prerequisites. The debug version of your application must be built with the following:

If, for any reason, the debugger can't use Fix & Continue, the Fix command will be disabled while debugging.

Using this feature is deceptively simple. Say, for example, you discover a bug in your source code while you're debugging. Listing 18-5 shows a common programming mistake: a loop with a missing increment statement.

Token findOneToken( const char* s )
{
    while ( *s!='' && isspace(*s) )
          s++;

Token token;
    token.word = s;
    token.length = 0;
    while ( *s!='' )
        {
        char c = *s;
        if (isspace(c))
            break;
        token.length++;
        }

    return (token);
}

After stepping through the second loop a few times, it becomes obvious that it gets stuck because the statement c = *s should have been c = *s++.

To correct this code, simply edit the statement so that it reads c = *s++ and choose Run

If that was all that needed to be done, you could continue debugging the application. Replacing the buggy code has, unfortunately, created another situation. Before you added the increment operator, the s variable wasn't being incremented — but token.length was. The length value now has a non-zero value and won't agree with the length of the string when the function returns.

Can you continue debugging your application without having to restart it? You have two ways of addressing this. The first would be to use the variables pane and simply edit the value of token .length, setting it back to 0. Another way is to alter the program counter so that the program continues executing at a different location in the code. Here the PC indicator is being dragged back up to the token.length = 0 statement so that the entire second loop starts over from the beginning, as shown in Figure 18-36.

Figure 18-36. FIGURE 18-36

When the execution is continued, the program starts again at the top of the (now bug-free) loop, reinitializes token.length to 0, and executes correctly.

Fix & Continue does have some limitations. Here are a few:

In short, you can make any change that alters only the executable code of one or more functions. You can't make a fix that alters the data types or linkages that are, or could be, used anywhere else in the application.

You should be aware of a couple other caveats about how Fix & Continue works. Fix & Continue replaces the code of a function that was executing and changes the current program counter so that execution continues in the new code. However, it does not change the program counter in any other stack frame. Say that Function A calls Function B. If you stop the program in Function B and fix Function A, when Function B returns it will return to the old Function A, not the corrected one. The corrected Function A won't be called until something else calls Function A again.

Fix & Continue only compiles and replaces the in-memory image of a single file. If you make changes in several files, you will need to perform a Fix & Continue on each one.

Also note that Fix & Continue only patches the memory image of the running application. It does not alter the original executable file that was produced by the last build. If you restart your application the old (bug-ridden) version is executed. Worse, the executable code is now out of sync with the modified source files. Make sure you follow each debugging session where you use Fix & Continue with a new build to incorporate the changes you made into the final product.

Open the Info window for an existing executable, or choose the Project

Figure 18-39. FIGURE 18-39

The Path option is the path, relative to the build product's directory, to the program that will be launched when the executable is started. Normally this is the binary application produced by your target. Change this if you want a different program executed instead. An example would be a UNIX program that is started by a shell script that checks the state of the program, gathers configuration information, and so on, before launching the binary program. If your product is started by such a script, enter the path to the script here.

At the bottom of the window is the current or working directory that will be set before the executable is launched. This is important to some executables that expect to find resources or perform work on files relative to the current directory. Normally this is set to the build directory for the product. That is, the current directory will be the same directory that contains the executable. The build product directory will change depending on which build configuration is active. You can alternatively choose the project directory or a custom directory. Enter the custom directory path, or click the Choose button to browse for a folder.

The Use Suffix When Loading Frameworks option passes a special flag to the dynamic linker. It tells the system's run time library loader to search for alternate versions of framework libraries. Many libraries are provided in alternate versions designed to aid in debugging or profiling. They may include additional integrity checks or log informational messages to the system log that are useful during development. When set to No, the loader links your application to the standard system libraries.

The Use For Standard Input/Output option determines where the stdout, stdin, and stderr file descriptors will be connected when the executable is launched. The Pseudo Terminal connects your application to the run or debugging console you've been using throughout this chapter. The Pipe choice is only useful for remote debugging, as described later. The System Console choice directs the program's output to the system console. Macintosh applications launched by the user, and command-line programs launched without a shell, normally have their output redirected to the system console log. You can review the system console log using the Console utility provided with Mac OS X. When set to the System Console choice, stdin is connected to null.

Use the Arguments pane to pass additional arguments and environment variables to your program. This can be extremely useful for testing command-line applications or setting special features of the run time system.

To add an argument, click the + button beneath the Arguments pane and type in the argument value, as shown in Figure 18-40. You can later edit arguments by double-clicking their values and reorder them by dragging. The check box in the left column is an enabled setting. Only arguments that are enabled are passed to the executable. This makes it easy to keep several commonly used arguments in the list and quickly select just the ones you want. Select an argument and click the − button to delete it entirely.

The environment variables pane works exactly the same way as the arguments, except that this pane defines named variables that are defined in the environment of the process. The values of environment variables can also reference any of the following build settings: SYMROOT, SRCROOT, OBJROOT, BUILT_PRODUCTS_DIR, and TARGET_TEMP_DIR. Chapter 17 covers referencing build settings in general and the meaning of these build settings in particular.

Figure 18-40. FIGURE 18-40

The Debugging pane, shown in Figure 18-41, controls additional settings that affect the execution environment of your program when you launch it under the control of the debugger. The When Using option controls which debugger Xcode will start to debug your application. The debugger chosen must be capable of debugging the kind of application that the executable produces. The Java debugger cannot debug a binary executable. Xcode sets this appropriately for executable products produced from targets. For custom executables, you need to tell Xcode which debugger is appropriate.

Figure 18-41. FIGURE 18-41

The Use For Standard Input/Output option controls the connections to the program's I/O. You may want to set this to System Console if the output of the program is obscuring the output of the debugger itself in the Debugger Console window. It is also possible to distinguish between the output of the debugger and your program by coloring their text differently in the Debugger Console window. (See the Debugger pane settings in the Xcode preferences.) If you are doing remote debugging, this option must be set to Pipe.

The next two options configure the gdb debugger for remote execution. The "Remote Debugging" section in this chapter explains how to configure a program for remote debugging.

The Start Executable After Starting Debugger option automatically starts your application running as soon as the debugger is loaded. Normally this is checked, but you may not want this to happen. Turning this option off launches the debugger, but performs no further action. This permits you the opportunity of making special adjustments in the debugging environment, such as setting breakpoints or editing static variables, before the program starts running. You can even use the debugger command to attach to an already running instance of your application, rather than launching a new one.

The Break on Debugger() And DebugStr() option sets the USERBREAK environment variable before your application is started. The presence of this environment variable causes the Debugger() and DebugStr() functions defined in Core Services to send a SIGINT signal to your program if either of these functions are called. Without this setting, these functions do nothing or just log a message to the console. When running under the debugger, a SIGINT signal suspends your program just as if it hit a breakpoint. This option sets this environment variable only when the executable is launched for debugging. To have it set all of the time, set the USERBREAK environment variable to 1 in the Arguments pane.

The Auto-Attach Debugger on Crash option causes the debugger to attach to the executable's process should it crash. This is equivalent to stopping your executable immediately after it crashes, but before the process is terminated, and issuing the Run

The Additional Directories to Find Source File In pane lists the paths to where the debugger can find the source file used to build the executable being debugged. Normally you don't need to add anything here because Xcode automatically searches all of the source directories in your project. However, if you have included source files outside your project or the executable was built from source files that Xcode doesn't know about — files in an externally built target, for instance — add those directories here. You can click the + button and type in the path, or drag a folder from the Finder and drop it into the list.

The active executable that you select using the Project

When you switch targets, Xcode examines the active executable. If the active executable is the one created for the product produced by the current target, and the target you are switching to produces an executable product, the active executable is changed to match the new active target. For most projects, this means that the active executable will "follow" the active target as you change between them. However, if you have targets that don't produce an executable, or have created and made custom executables active, changing the target may not change the executable. You need to be especially watchful if you have created aggregate targets. An aggregate target that builds both a client and server application will not select an active executable when you make that target active. You must specify which executable, the client or the server, needs to be launched when you choose Run or Debug.

The command Run

The Run

A very useful debugging feature for C programmers is the Guard Malloc library. Choosing the Run

It should be noted that Guard Malloc can significantly slow down your application, but the additional execution time is usually worth it, because out-of-bounds memory accesses are particularly difficult to debug.

Debug variables are either environment variables or preference property values that invoke special behavior in the libraries and frameworks and are useful for debugging.

Environment variables can be set using the Arguments pane of the executable's Info window. Preference values can be set using the defaults command-line tool. You can read the man page on the defaults tool for the details of setting user default values, but here's a simple example:

defaults write com.my.SimpleApp NSShowAllViews YES

The com.my.SimpleApp file is the user preferences file associated with the application. By default, this is the Identifier set in the target's Properties pane. The command sets the NSShowAllViews property to YES, which causes the AppKit framework to draw a colored border around every NSView. Setting property values only works for Carbon and Cocoa applications that use the user defaults framework.

The following table describes a few environment variables useful for C programming:

If you think you have a problem with loading dynamic libraries, try some of the environment variables described in the following table:

If you're debugging memory leak or retain/release problems in Cocoa, consider setting some of the environment variables described in the following table:

The two preference settings described in the following table are useful when you're debugging an AppKit application that is having drawing or layout problems. You must set preferences in the preference file of the application before you launch it.

This is just the tip of the iceberg. There are literally hundreds of variables, system calls, and development tools to help you track down and debug your application. Most are collected and maintained in Apple Technical Note #2124, Mac OS X Debugging Magic, which you can find in the Xcode documentation or read online at http://developer.apple.com/mac/library/technotes/tn2004/tn2124.html.