Debugging Cappuccino Using Safari

Introduction

 

Jan 4, 2009 — Some differences between the WebKit debugger (aka Web Inspector) and Firebug are (taken from a listserv):

  • Profiles pane lets you view and work with profiles more effectively than a console dump, and offers both top-down and bottom-up views
  • Databases pane
  • Can view console and another pane at the same time.
  • Autocomplete in the console
  • Resources pane that lets you view all resources and sort by time, size and latency (Firebug's Net view is not really comparable)

You can read more about the Web Inspector at the WebKit page describing it. The documentation is not complete yet.

Setup

The latest released version of Safari (3.2) does not yet include the fully tricked-out Web Inspector, so download and install the latest developer build of WebKit instead.

Turn on the Develop menu in Preferences | Advanced:

 

In your source code, place the "debugger" command where you want to start stepping through the code. When WebKit (the name of the developer version of Safari) reaches this it will pause the program execution. Using the Hello World starter application that comes with Cappuccino as an example, I've placed it at the end of the AppController.j file, just before the [theWindow orderFront:]:

Open a new browser window pointing to any site you like (otherwise the following menu will be grayed out) and select Develop | Show Web Inspector. The bottom half of the screen will be replaced with a new pane. While you're here, select Develop | Disable Runaway JavaScript Timer so that WebKit does not alert you incessantly while you are pondering your code.

In the new pane, click on Scripts so that it looks like this:

Click "Enable Debugging" and the debugging pane will fill with information about the displayed page. More on this in a moment.

Launch the app using the debug framework by calling up index-debug.html in WebKit. You can call it through your local web server or as a local file ("file:///Volumes/Fleecy/Users/aangel/LocalDevelopment/Workspace/Starter/NewApplication/index-debug.html"). If you pull up the file locally using the file resource, WebKit will allow cross-domain requests.

The debugger will stop at the first debugger statement it finds.

Wait! What happened to all the lovely Objective-J code? Remember that Objective-J is a small addition to JavaScript and is parsed into pure JavaScript at startup.

In the debugger, the following line:

[label setStringValue:@"Hello World!"];

is parsed to:

objj_msgSend(label, "setStringValue:", "Hello world!");

In the stack trace, all method names are listed as their object name followed by the parameters but separated by underscores instead of colons. Thus in the strack trace you see this invocation:

[app applicationDidFinishLaunching:aNotification]

as:

$AppController__applicationDidFinishLaunching_

The right part of the debugger pane shows the current call stack. 

Viewing Program Variables

By scrolling down a bit in the right pane you'll see the variables in your program:

Click a horizontal triangle to see all of an object's properties.

Stepping Through Code

Also notice that there are four buttons that control program execution. They are, in order, "Continue/Pause," "Step over next function call," "Step into next function call" and "Step out of current function."

Stepping over a function means the debugger will call the function and stop at the next line in the current scope. Stepping into a function means that the debugger will follow the call and stop on the first line of the called function. Stepping out of the function means the debugger will continue executing the current function and stop at the next line in the parent function. Most times you will step over functions and step into them only when it contains code you need to debug or understand.

Setting Breakpoints

You can set a new breakpoint once program execution has begun by clicking on the row number in the left column. There is a bug in the debugger that displays "(program)" for every script in the project. When that is fixed, you will be able to select a script in the drop down box. In the meantime, type the name of the method in the search field. Wait a few moments and keep pressing Enter in the search field until you arrive at the method instance you want.

I have not found a way to retain breakpoints between launches. If you expect to debug a piece of code for a while, place "debugger" just before it and comment it out or delete it when it's no longer needed.

Using the Console

There are some interesting things you can do with the console at this point. Turn on the console by clicking the second button from the left:

The debugging pane will look something like this:

and the cursor will be flashing beside the angle bracket.

You can print the value of a variable just by typing its name in the console. Give a variable a new value with something like "theIndex = 15." Look inside objects using JavaScript dot notation:

Notice in the example above that the "alue" is grayed out; that's the debugger performing code completion for you. Use the cursor right key to accept the completion and press Enter:

Since JavaScript objects are sets of key-value pairs, you can examine an element of a JSON-style object by using either dot notation (person.city) or through an associative array (person["city"]). To see all properties of an object, use console.dir(nameOfObject).

Many of the commands from the Firebug console work here. See the Firebug Console documentation for more. The WebKit API defines the following commands:

console.log()
console.error()
console.warn()
console.info()
console.count()
console.debug()
console.profileEnd()
console.trace()
console.dir()
console.dirxml()
console.assert()
console.time()
console.profile()
console.timeEnd()
console.group()
console.groupEnd()

Sending Messages to the Console

Within your source code, you can sprinkle console.log commands where needed to print variables to the console, like this:

Cappuccino includes a logging object as well, which you can use like this:
Messages to CPLog are sent to the Cappuccino console. If you place the line:
/* Enable Logging (DEBUG) */
CPLogRegister(CPLogPopup);
early in your program execution, the Cappuccino console will turn on each time the program is launched, saving you a step. (Using CPLogRegister is entirely optional.) You can also ask Cappuccino to open the console immediately by adding #debug to the end of the URL.
The console looks like this:
In decreasing severity, the different possible CPLog message levels are:
  • fatal
  • error
  • warn
  • info
  • debug
  • trace

Conclusion

I haven't tested all of the debugger's features yet but the biggest win from using a debugger is being able to step through the code while examining (and occasionally changing) variables, which you now know how to do. :-)

 

Tutorial maintained by Andre Angelantoni.