In this entry we'll actually see how things work. Fortunately, the guys at Intergral have done a great job creating plenty of screenshots and Captivate videos that help you readily see how it works. What I'd like to do is first use those to show how you use it and I will save how to configure it for the next entry. Entries beyond that will show some features that go beyond the basics.
A Challenge To Note
Some of you may have already used step debuggers before, while others will be new to them The challenge in presenting this topic is speaking to both audiences. Indeed, as has been discussed in the previous two entries (and in comments from other folks there), there's a degree to which those with prior debugging experience might sometimes even give FusionDebug short-shrift by their assumptions about what it can or can't do.
If you've not yet read those entries, please do go take a moment to do so now. It's one thing to appreciate how FusionDebug works--it's another to appreciate why you should care. :-)
So What is a Step Debugger?
If you've ever wished you could watch as your program executes from line to line, that's exactly what a step debugger does for you. In the case of FusionDebug, it's a commercial plug-in that's added to the free Eclipse editor. Again, even if you don't (and don't want to) use Eclipse (or the CFEclipse plug-in), that's ok. You only need to know a few things to use FusionDebug.
The FusionDebug User Guide does a great job of introducing how to download, install, and configure the product, as well as how to get started loading a file and setting a break point. Assuming you've followed those steps (which I'll go over later), you then have the opportunity to tell the tool that you want to stop execution on a given line of CFML code. This is called setting a breakpoint. You can just right-click on the line of code in the FusionDebug (Eclipse) editor, and choose Toggle Line Breakpoint.
Stopping on a Breakpoint
When that CFML template is requested and that line of code would be executed, the program will halt and the FusionDebug interface would reflect that execution has halted. It will open the file (if it's not already open) and show the line of code on which execution has stopped:
The blue dot to the left of the line shows where a breakpoint had been set, and the blue arrow and shading on the line indicates that control has halted on that line. (The browser in which the page had been requested will generally appear as if the request is just taking a long time.)
Indeed, a really cool thing about the way FusionDebug works is that it can intercept the request from any user, not just the user who has initiated the debugging session. This is a two-edged sword:
- it means that you can use it to intercept a request other than one you yourself initiated. How often have you tried to understand why a problem was happening to a user in production, but you couldn't recreate it locally? Or, as I noted in my last entry, it can also intercept a request via web services, or Flex, Flash, Flash Remoting, or Ajax.
- The problem, of course, is that it also means that anyone on that server being debugged will be affected when you set a breakpoint. This certainly speaks to taking caution about setting breakpoints in production. Still, it's nifty that can. With power comes responsibility.
Observing Program State Information (Variables)
Being able to stop the program in its tracks may seem only mildly interesting, but the real power comes in the fact that while you are stopped at a breakpoint in the debugger, you can learn a lot about what was going on in the program at the time. For instance, you can see all the variables that may have been set (either in the program or perhaps as set in other templates before this one executed).
FusionDebug provides a "Variables" view, which in the case of the code above would show the following:
You can see that a structure with a key and an array has been created. Note how you could expand both the local "variables" scope as well as any application, session, server, and other scopes. Indeed, if we were stopped within a method (CFFUNCTION or CFSCRIPT function), we could also see the local ("var") and "this" scopes. Isn't that a whole lot easier than putting in CFDUMPs, CFOUTPUTs, etc.? And having to remember to remove them? And as I talked about in the last entry, there are simply situations where you just can't use CFDUMP or CFOUTPUT.
If you had a large number of variables that would make it tedious to explore this Variables view, yet another option available is a set of "watched expressions". This is even more like using old-style outputs, except they never send output to the browser. Instead the results are shown inside the debugger. With this other "Expressions" panel, you can choose to watch any variable or expression. (An expression can be anything you might put on the right side of the "=" of a CFSET, or in a CFIF condition, including variables, functions, and so on.) Here's an example:
You can enter expressions by right-clicking in the Expressions View, selecting Add Watch Expression, and typing in the expression manually. Even nicer, you can highlight an expression in the code editor, and right-click and select Watch Expression:
Setting Variables On the Fly
Perhaps one of the most compelling things about step debuggers is that they permit you to do something you simply can't do in your code (once the program is running): you can alter the value of any variable while the program is running. All you need to do is right-click on the variable in the code editor and choose Set Variable. You then indicate the value to set, and (while at a breakpoint) that will take effect for the remainder of the request. Nifty!
Stepping Through Lines of Code
As useful as it is to stop at one point in the program and view all of the above, there's still much more to a step debugger. We're about out of time and space in this entry, but one of the most important remaining fundamental features is the ability to step through your code.
Consider the following code and the display showing it being stopped at the indicated breakpoint:
How do you tell it to proceed? Still another pane in the FusionDebug (Eclipse) interface is an available Stack Trace pane. In it, you will notice some icons at the top of the pane:
These represent the ability to tell the program to continue to the next line of code. Perhaps the most common one to use is the rightmost in the above screenshot, though others exist outside of what's visible in the screenshot. This is called Step Over, and it simply executes the next line of code.
Where all the examples so far have talked about things you can do while stopped at a breakpoint, they also of course apply while stepping through code as well.
Also available are options to indicate whether you'd want to follow the flow of execution into another file, such as a custom tag, CFC, included file, and so on. Note that the screenshot showing the breakpoint above indicates that the next line of code is a custom tag (cf_getEmployee). If we were to use Step Into, the icon left of Step Over, then FusionDebug would open the getemployee.cfm custom tag and stop at the first line of CFML within that. Assuming that was on line 1 of that template, the stack trace would look like the following:
If you didn't want to bother stepping any more within the nested file, you could use an available Step Return button. And if you didn't want to bother stepping any more in any of the files in the request, you can use the left-most of those icons (what looks like an green arrow) which is called Resume. It would let the request run to completion (unless it hit another breakpoint).
As I've said, there's a lot more to show, but this should be enough to whet the whistle of those who haven't explored a debugger before. You can read the docs, see additional features, view videos, and see additional screenshots on the FusionDebug site. Until next time.