Xcode Breakpoint Actions

Xcode’s breakpoints pause your program so you can step through your code line by line and examine the values of your variables. But sometimes you don’t want to pause your program. You want to do something like print the value of a variable to the console. Xcode has breakpoint actions that let you do things like print a variable’s value, run debugger commands, and run scripts.

If you’re unfamiliar with Xcode breakpoints, read Introduction to Xcode’s Debugger.

Creating a Breakpoint Action

Right-click on a breakpoint in Xcode’s editor or Xcode’s breakpoint navigator (Press Cmd–8) and choose Edit Breakpoint. A popover opens to edit the breakpoint.

XcodeBreakpointEditor

Click the Add Action button to create a breakpoint action.

Breakpoint Actions

When you click the Add Action button, the popover looks similar to the following screenshot:

XcodeBreakpointActionEditor

Xcode provides the following breakpoint actions:

  • AppleScript
  • Capture GPU Frame
  • Debugger Command
  • Log Message
  • Shell Command
  • Sound

A breakpoint can have multiple actions. For example you can run a debugger command and play a sound when reaching a breakpoint.

AppleScript

The AppleScript breakpoint action runs an AppleScript script.

XcodeAppleScriptAction

Enter the script text in the text view. Most of you using the AppleScript action will write the script in a text editor and paste it into the text view. Click the Compile button to make sure the script works.

Capture GPU Frame

The Capture GPU Frame action captures a frame from the graphics card. This action helps most with apps that work with graphics, such as games, image editors, and video editing apps.

Debugger Command

The Debugger Command action runs an LLDB debugger command. The LLDB site has information on all the LLDB commands.

Enter the command in the text field.

Log Message

The Log Message breakpoint action logs a message to Xcode’s debug console. A common use of message logging is to write the value of a variable to the console. Use this action as an alternative to littering your code with print statements for debugging purposes.

Most text that you enter in the text field will appear that way in the console. Wrap variable names with the @ character. Suppose you have a game and want to display the player’s x position. The following log message:

Player X: @player.position.x@

Prints the following in the console if the x position is 12:

Player X: 12

Shell Command

The Shell Command action runs a shell script. You can use this action to run command-line programs as well as shell scripts.

XcodeShellCommandAction

Enter the command in the top text field, or click the Choose button to locate a shell script on your Mac. Enter any arguments in the bottom text field. Selecting the Wait until done checkbox tells Xcode to wait until the shell script finishes to continue.

Sound

The Sound action plays a sound. Playing a sound lets you know you hit the breakpoint. Normally you mix the Sound action with other breakpoint actions.

XcodeSoundAction

Choose a sound from the menu.

Automatically Continue

At the bottom of the breakpoint editor popover is a checkbox to automatically continue after running the breakpoint actions. If you’re using breakpoint actions, you should select the checkbox so you don’t have to click the Resume button to resume running your app.