Design

LLDB was developed using object-oriented design practices, including data encapsulation (no global variables) and a plug-in based architecture that facilitates modularity and extensibility. The next few paragraphs provide an overview of the libraries that comprise LLDB and examine in more detail a few of its significant design elements.

LLDB Commands

LLDB includes a comprehensive set of debugging commands that can be used with both Xcode and the command-line tool. The following are several of the commonly used LLDB debugger commands:

• apropos: Finds a list of debugger commands related to a particular word or subject.
• breakpoint: A set of commands that perform operations on breakpoints (set, clear, enable, disable, etc.). A breakpoint pauses execution of a target program, thereby enabling you to examine its current state. LLDB supports line breakpoints (set on a line of source code), symbolic breakpoints (set on a symbol [e.g., function/method name] in a program), and exception breakpoints (set when an exception is thrown or caught).
• disassemble: Disassemble bytes in a function, an address, and so forth.
• expression: Evaluates a C/C++/Objective-C expression in the current target using both user-defined variables and variables currently in scope.
• frame: A set of commands for operating on the current thread’s stack frame (info, select, variable).
• help: Shows a list of all debugger commands.
• log: A set of commands for operating on logs.
• memory: A set of commands that performs operations on memory (e.g., read from, write to).
• process: A set of commands for operating on a process (launch, kill, attach, detach, connect, etc.).
• register: A set of commands used to access thread registers (read, write, etc.).
• thread:A set of commands used to operate on one or more threads (single step, step over, continue, etc.). This enables you to control execution of a target program being debugged.
• watchpoint: A set of commands for operating on watchpoints (set, clear, enable, disable, etc.). A watchpoint is a form of conditional breakpoints set on a variable. It causes the target to stop execution whenever the value of the watched variable is changed.

LLDB implements a structured command syntax that facilitates its use and provides a mechanism to construct aliases for commonly used commands. The command-line tool also supports command completion for source file names, symbol names, and so forth with the Tab key. The general syntax for LLDB CLI commands is as follows:

<noun> <verb> [-options [option-value]] [argument [argument...]]

Each command has a subcommand (i.e., the verb) along with its applicable options and arguments. Listing C-1 depicts an example of an LLDB debugging session of the application named FirstProject (recall that you developed this application in Chapter 1) using the command-line tool.

Listing C-1.  Example LLDB Debug Session Using the Command-Line Tool:

% xcrun lldb
(lldb) target create FirstProject
(lldb) breakpoint set --name main
(lldb) process launch
(lldb) thread step-over
(lldb) breakpoint set --line 42
(lldb) thread continue
(lldb) expression (void)NSLog(@"Date = %@", dateTime)
(lldb) quit

As shown in Listing C-1, xcrun is an Xcode command that loads a binary contained within an Xcode bundle. This enables you to run LLDB from the command line. Next, the target create command loads the FirstProject application as a target for the debugger. The breakpoint set command sets a breakpoint at the main method. The expression (void)NSLog(@"Date = %@", dateTime) command evaluates an Objective-C expression that displays the current value for the dateTime object. The quit command ends the debugging session.

Xcode LLDB Integration

LLDB is the default debugger in Xcode, which augments the standard functionality of LLDB with a variety of features that can make you more efficient at debugging your code. Figure C-2 depicts an example debugging session in Xcode. In the following paragraphs, you will examine these features in more detail.

Using LLDB in Xcode

Now that you have received an overview of LLDB and debugging with Xcode, you will debug a program using Xcode. In Xcode, create a new project by selecting New Project . . . from the Xcode File menu. In the New Project Assistant pane, create a command-line application by selecting the Command Line Tool icon (from the Application selection under OS X template groups). In the Project Options window, specify BrokenCalculator for the Product Name, choose Foundation for the Project Type, and select ARC memory management by selecting the Use Automatic Reference Countingcheck box. Specify the location in your file system where you want the project to be created (if necessary, select New Folder and enter the name and location for the folder) and uncheck the Source Control check box.

Now create the calculator class. Select New File . . . from the Xcode File menu, select the Objective-C class template, and name the class Calculator. Select the BrokenCalculator folder for the files location and the BrokenCalculator project as the target, and then click the Create button. Next, in the project navigator pane, select the Calculator.h file and update the class interface as shown in Listing C-2.

Listing C-2.  Calculator Class Interface

#import <Foundation/Foundation.h>

@interface Calculator : NSObject

- (NSNumber *) sumAddend1:(NSNumber *)adder1 addend2:(NSNumber *)adder2;

@end

The class declares a single instance method for returning the sum of two numbers. Next, use the Xcode project navigator to select the Calculator.m file and code the implementation as shown in Listing C-3.

Listing C-3.  Calculator Class Implementation

#import "Calculator.h"

@implementation Calculator

- (NSNumber *) sumAddend1:(NSNumber *)adder1 addend2:(NSNumber *)adder2
{
  return [NSNumber numberWithInteger:([adder1 integerValue] +
                                      [adder2 integerValue])];
}
@end

The method returns the sum of the integer values of the two input parameters. OK, that’s pretty straightforward, now let’s move on to the main() function. In the project navigator, select the main.m file and update the main() function as shown in Listing C-4.

Listing C-4.  BrokenCalculator main( ) Function

#import <Foundation/Foundation.h>
#import "Calculator.h"

int main(int argc, const char * argv[])
{
  @autoreleasepool
  {
    // Create instance and numbers to add
    Calculator *calculator = [[Calculator alloc] init];
    NSNumber *addend1 = [NSNumber numberWithInteger:10];
    NSNumber *addend2 = [NSNumber numberWithInteger:15];
    NSNumber *addend3 = [NSNumber numberWithInteger:-25];

    // Add numbers and validate correct sum returned
    NSNumber *sum1 = [calculator sumAddend1:addend1 addend2:addend2];
    NSCAssert(([sum1 intValue] == 25), @"Invalid sum computed");
     
    NSNumber *sum2 = [calculator sumAddend1:addend1 addend2:addend3];
    NSCAssert(([sum2 intValue] == 15),  @"Invalid sum computed");
  }
  return 0;
}

The method creates a Calculator instance and NSNumber instances, and then adds two numbers and validates that the correct sum is returned. When you compile and run the program, you should observe the messages in the output pane, as shown in Figure C-9.

Figure C-9 shows that an exception was thrown—specifically an assertion failed, indicating that the sum returned was not the expected value. Now you will use the debugger to determine the cause of the problem. In the breakpoint navigator, add an exception breakpoint by clicking the plus (+) symbol at the bottom left of the navigator pane and selecting Add Exception Breakpoint . . . from the pop-up menu (as shown in Figure C-10).

In the exception breakpoint dialog, there are several settings. For Exception, select All (set on all exceptions), and for Break, select On Throw (set breakpoint when exception is thrown). When you compile and run the program, you should observe that the program pauses in the main function at the following line:

NSCAssert(([sum2 intValue] == 15),  @"Invalid sum computed");

You can see that this assertion fails, causing the exception to be thrown. Now you will set some line breakpoints to troubleshoot the program. You set a line breakpoint in Xcode by clicking the gutter next to the corresponding line in your source code. In the project navigator, select the Calculator.m file and set a breakpoint at the line with the following statement:

return [NSNumber numberWithInteger:([adder1 integerValue] +
                                    [adder2 integerValue])];

Next, in the main() function, set a breakpoint at the line with the following statement:

NSCAssert(([sum1 intValue] == 25), @"Invalid sum computed");

Now edit this breakpoint to add a breakpoint action, as shown in Figure C-11.

This breakpoint action executes a debugger command that logs the value stored in variable sum1.

expr (void)NSLog(@"Sum 1 = %@", sum1)

Notice that the return type must be specified in debugger command expressions. In this case, the type is void, signifying that the NSLog function doesn’t return a value. Also note that the breakpoint option is set to automatically continue after executing. Effectively, this enables you to display the value of a program variable without having to write NSLog statements in your code, and hence avoid cluttering your code with debugging statements! When you compile and run the program, it pauses execution at the line breakpoint set for the sumAddend1:addend2: method, as shown in Figure C-12.

In the debug area content pane, you can see that the values for variables adder1 and adder2 are as expected. Now you would like to validate the return value from this method. This can be done with the step-out command (located in the debug bar). This command executes the remaining lines of a method/function in which the current execution point lies, and then displays the next statement following the method/function call. Select this button two times. After that is done, the return value is displayed in the content pane display area (Return Value), as shown in Figure C-13.

The return value of 25 (shown in Figure C-13) is correct. Next, select continue in the debug bar (you may have to click the button two or three times). The output console logs Sum 1 = 25, per the breakpoint action debugger command that you configured earlier. Now observe that the debugger has paused again at the line breakpoint set for the sumAddend1:addend2: method. This time, use the debugger po command in the debug area content pane to display the values for the two parameters:

po adder1
po adder2

The output of these commands is shown in Figure C-14.

These values (10, –25) are as expected, so select continue to advance the program. Next, the debugger pauses at the NSCAssert. Using the po command, the variable sum2 displays a value of –15 (as shown in Figure C-15).

This is the expected value, so why is the assertion failing? Looking at the assertion statement, you can see that the conditional expression is expecting a value of 15, when it should be –15!

NSCAssert(([sum2 intValue] == 15),  @"Invalid sum computed");

When you correct the assertion (by changing the value to –15) and run the program again, you will see that it runs successfully. Now even though this was a very contrived example, it illustrates a few of the capabilities of debugging in Xcode using LLDB. Apple provides a variety of documentation on Xcode debugging using LLDB, and the LLDB web site is an essential reference for more information.