Generating Debugging Information

Before you can take advantage of Xcode’s source-level debugger, the compiler must collect information for the debugger. To generate debugging symbols for a product, enable the Generate Debug Symbols (GCC_GENERATE_DEBUGGING_SYMBOLS) build setting and build the product. This setting is enabled by default in the Development build style provided by Xcode. If you use this build style as the active build style when you build your target, the compiler generates the necessary debugging information.

To view the build settings set in the Development build style:

1. In the project window select the project and bring up the inspector window.

2. Click Styles to bring up the Styles pane.

3. Choose Development from the Build Style pop-up menu at the top of the pane. You should see the Generate Debug Symbols setting in the table of build settings. Make sure that this setting is turned on; if it is, a checkmark appears in the Value column for this setting. Otherwise, turn on the setting by clicking the checkbox in the Value column.

You can use the Active Build Style pop-up menu to change the active build style. This menu is available by default in the toolbar of the Build Results window; otherwise, you can add it to the toolbar of other project windows by choosing View > Customize Toolbar and dragging the Active Build Style menu into the toolbar. For more information on build styles, see Build Styles.

Configuring Your Executable for Debugging

When you start your program in the debugger, Xcode launches it with the command-line arguments, environment variables, and other settings specified in the executable environment. The executable environment also contains a number of debugger-specific options that control which debugger Xcode uses, as well as how Xcode launches and communicates with the program. These options are set in the Debugging pane of the executable inspector, shown in Figure 32-1.

Here is what the Debugging pane contains:

1. When using. This pop-up menu lets you choose the debugger used when you debug the executable. The next several options below this menu pertain only to the selected debugger.

2. Use [device] for standard input/output. This pop-up menu lets you specify how standard input and output are handled when debugging the executable. By default, Xcode uses a pseudo terminal device to display stdin and stdout in the Standard I/O Log window, described in Debugging a Command-Line Program. You can also choose System Console from this menu to have Xcode redirect your program’s output to the system console (console.log).

3. Options for remote debugging. The “Debug executable remotely via SSH” option lets you set up the executable for remote debugging using GDB in the Xcode debugger window. The “Connect to” field specifies the host machine on which the executable is run. See Remote Debugging in Xcode.

4. Start executable after starting debugger. This option lets you control whether Xcode starts the executable running immediately after loading it in the debugger. If this option is enabled, Xcode loads the executable in the debugger but does not start it until you press “Restart.” This allows you to perform operations in the debugger—such as setting breakpoints—before the executable runs.

5. Break on Debugger() and DebugStr(). This option tells Xcode to set the USERBREAK environment variable, which suspends execution of your program on calls to the Core Services framework debugging functions Debugger or DebugStr.

6. Additional directories to find source files in. This table lets you specify additional folders in which Xcode can look for source files corresponding to the symbol information in the executable code. To add a directory, click the plus-sign button and type the path to the directory in the Source Directory field. You can also drag folders to the table from the Finder; Xcode will insert the path to the folder. To remove a directory, select it in the table and click the minus-sign button.

Starting Your Program in the Debugger

You can start a debugging session using the buttons available in the toolbar of most Xcode windows, or using the menu items in the Build and Debug menus. To build a development version of the active target’s product and start the debugger if the build succeeds, choose Build > Build and Debug, or click the Build and Debug button. To load an executable that has already been built, choose Debug > Debug Executable or click the Debug button.

When you start a debugging session, Xcode uses the active executable for the current project to determine which executable file to load. It loads that program in the debugger, sets any environment variables specified by the executable environment, and starts the program, passing any specified command-line arguments. You can debug only one executable in a project at a time. You can, however, have multiple projects open at once, each with its own instance of the debugger. In this way, you can debug multiple executables at a time. If, for example, you have a project that builds both client and server executables, you can debug them both at once by creating an empty project and adding a custom executable that points to the client or server product. You can then run the client executable under the debugger from one project and the server executable from the other. Creating a Custom Executable Environment describes how to create a custom environment.

To choose which debugger is used, edit the debugging settings for the executable, as described in Configuring Your Executable for Debugging.

The Debugger Window

Xcode automatically opens the Debugger window, if necessary, when you start a debug session. You can also display the debugger window at any time by choosing Debug > Debugger. Figure 32-2 shows the Debugger window.

Here’s what the debugger window contains:

• Toolbar buttons for stepping through code and displaying related windows.

  • The Build and Debug and the Debug buttons load the project’s active executable in the debugger. When a debugging session is active, the Terminate button is available; this button stops the active debugging session.

  • The Fix button compiles a single file fix and modifies your executable to run the changed code without stopping the current debugging session. For more information on how to use this feature, see Using Fix and Continue.

  • The Pause, Continue, and Restart buttons control execution of the program.

  • The Step Into, Step Over, and Step Out buttons step through lines of code.

  • The Breakpoints button opens the breakpoints window, which allows you to create and view breakpoints, described further in Breakpoints.

  • The Console button opens the debugger console.

• The status bar displays the current status of the debugging session. For example, in the window shown above, Xcode indicates that GDB has just finished loading symbols for a single shared library.

• The Thread view on the upper-left side of the debugger window displays the call stack of the current thread. The pop-up menu above this view lets you select different threads to view when debugging a multi-threaded application.

• The Variables view on the upper-right side of the debugger window shows the variables defined in the current scope and their values. This section also shows the current state of all processor registers when the disassembly view is enabled (see Viewing Disassembled Code and Processor Registers for more information).

• The editor displays the source code you are debugging. When execution of your program is paused, the debugger indicates the line at which execution is paused by displaying the PC indicator, which appears as a red arrow. The line of code is also highlighted. You can change the color used to highlight the currently executing statement by choosing Xcode > Preferences, selecting Debugging, and choosing a new color from the Instruction Pointer Highlighting color well.

You can change the layout of the debugger window by choosing Debug > Toggle Debugger Layout. In this alternate layout, the Variables view is on the left side of the debugger window, under the Thread view, and the editor is on the right side of the window.

Lazy Symbol Loading

Lazy symbol loading reduces the initial memory footprint for debugging large applications by reading debugging symbols only when they are needed. When the “Load symbols lazily” option is enabled—as it is by default in Xcode’s Debugger Preferences pane—the gdb debugger reads a minimal amount of symbol information to support symbolic breakpoints and calling functions in the debugger console. To set a file and line breakpoint Xcode gives hints to gdb about the symbols needed to set the breakpoint. When a stack trace is generated, gdb automatically reads the full debugging symbols as needed, providing line number and file information to Xcode. When lazy symbol loading is disabled, Xcode reads the full debugging symbols when the debugger starts up.

The Console Window

Xcode’s graphical interface for GDB, the GNU debugger, and for the Java debugger lets you perform most necessary debugging tasks. You may, however, encounter situations—such as working with watchpoints in GDB—that require you to interact directly with the debugger on the command line. Using the Console Log in Xcode, you can:

• View the commands that Xcode sends to gdb or the Java command-line debugger.

• Send commands directly to gdb or the Java command-line debugger.

• View the debugger output for those commands.

• See debugging messages printed to stderr by your program or by system frameworks.

To open the Console Log, click the Console button in the toolbar of Xcode’s Debugger window or choose Debug > Console Log. To enter commands, click in the console window and type at the gdb or JavaBug prompt. To get help with GDB and Java debugging commands, enter help at the console. To learn more about command-line debugging with GDB, see Debugging With GDB in Tools Compilers & Debuggers Documentation.

To make the Console Log easily readable, Xcode lets you choose the text colors and fonts used in the console window. You can use different fonts and colors for the text you type in the console, the text the debugger writes to the console, and the debug console’s prompt. To change the colors used for text in the Console window, choose Xcode > Preferences, click Debugging, and use the Fonts and Colors options. See Debugging Preferences for more information.

Debugging a Command-Line Program

If you are debugging a command-line program that requires input from stdin, you must use the Standard I/O Log to communicate with your program when it is running in the debugger. To open the Standard I/O Log window, choose Debug > Standard I/O Log. This window is only available when your program is running under the debugger.

Xcode and Mac OS X Debugging

Many of the subsystems in Mac OS X include debugging facilities that you can use to help you in your debugging tasks. You can use most of these debugging facilities along with Xcode. Many debugging facilities are enabled or disabled by setting an environment variable; you can modify the executable environment to set these environment variables from Xcode. Xcode also includes several options for enabling specific debugging options, such as libgmalloc (Guard Malloc), loading debug library variants, and stopping on Core Services debugging functions (described in Stopping on Core Services Debugging Functions). For more on the many debugging facilities available in Mac OS X, see TN2124: Mac OS X Debugging Magic.