Using the ColdFusion Debugger-Developing guide

After you enabled the debugger in the ColdFusion Administrator and configure Eclipse, you can debug ColdFusion pages that are in an Eclipse project.

You can use the ColdFusion Debugger to do the following tasks:

• Setting a breakpoint
• Executing code line by line
• Inspecting variables

Begin debugging a ColdFusion application

1. Open the file in the Eclipse project to debug.You do not have to create an Eclipse project in the same folder as CFML source. You can create a project in a different folder, create a folder under that project, and then link it to the folder where CFML sources reside.
2. Click Debug in the upper-right corner of the Eclipse workbench to go to the Debug perspective.
3. Select Window > Show View > Debug Output Buffer to see the output from your application and how your application appears in a browser.
4. Select Window > Preferences and specify the home page for your debugging session, the extensions of the file types that you can debug, and the variable scopes of the variables to show in the Variables pane. Click OK.The home page is the page that appears in the Debug Output Buffer pane when you click the Home button in the Debug Output Buffer pane.
5. To begin debugging the file whose source appears in the Edit pane, click the Debug icon in the Eclipse toolbar.
6. Click New to create a new debugging configuration.
7. Specify the home page for the active debug session. This is the page that appears in the Debug Output Buffer pane when you click the Debug Session Home button in the Debug Output Buffer pane.
8. Click Debug to start the debug session.

Setting a breakpoint

You can set breakpoints in your CFML file to stop execution of the page at particular points. When you set a breakpoint on a line, execution of the CFML stops just before that line. For example, if you set a breakpoint on the third line in the following CFML page, execution stops before <cfset myName = "Wilson">.

Run the page that you want to debug before setting any breakpoints to compile it before debugging it. This improves performance during debugging. You cannot set a breakpoint in a file that is not part of a project.

1. In Eclipse, open the file in which you want to set a breakpoint.
2. While highlighting the line where you want to set the breakpoint, do one of the following:
   • Double-click in the marker bar that appears to the left of the editor area.
   • Right click, and then select Toggle Breakpoint.
   • Press Alt+Shift+B.
     A blue dot appears before the line on which you set the breakpoint. Also, you can view a list of breakpoints set in the current Eclipse project in the Breakpoints panel.ColdFusion breakpoints have four states in the Eclipse debugger:
   • Enabled and Valid - This is a breakpoint at a valid location. It is represented by a solid blue circle and stops code execution when encountered.
   • Unresolved - ColdFusion sets the breakpoint for the page that is loaded in its memory. If you modify the page and do not execute it, the source is not in sync with the page that ColdFusion sees on the server. In this situation, ColdFusion may consider the line where you want to set breakpoint to be invalid. However, you have not yet executed the page; when you do so, that line may be valid. This type of breakpoint is represented by a question mark (?) icon.For performance reasons, ColdFusion does not try to resolve unresolved breakpoints every time you execute the page. It tries to resolve them when you modify the page and execute it. If you think that the line at which ColdFusion shows an unresolved breakpoint is valid, delete the breakpoint and set it again.
   • Invalid - If ColdFusion determines that the CFML that you edit in Eclipse is the same as the CFML in its memory, and that the breakpoint you have set is at an invalid line, the breakpoint appears as a red X.
   • Disabled.

Executing code line by line

You can use the Step Into, Step Over, and Step Return buttons to proceed through your CFML application line by line. Use Step Into to proceed into included files, such as UDFs or CFCs. Use the Step Over button to proceed through your CFML application, bypassing included files, such as UDFs or CFCs. Use the Step Return button to return to the original page from which you entered the included file, such as UDFs or CFCs.
For the stepping process to work properly, clear the cache of compiled classes. To do so, recompile all CFML pages compiled with an earlier version of ColdFusion. In large files, you might find that stepping and breakpoints are slow. To improve performance, in Eclipse, select Windows > Preferences > ColdFusion > Debug Settings and deselect all scopes for which you do not require information.
Avoid using Step In on CFML instructions such as the cfset tag. Step In is more performance intensive than Step Over. You can use Step In for UDFs, CFCs, custom tags, and included files.
When stepping into functions, tags, and files, Eclipse expects the file to be displayed in one of the open projects. The file that you are stepping in must be in an open Eclipse project. 
Sometimes Eclipse 3.2.1 does not show the stack trace, and step buttons are disabled, even though the debugger has stopped at a line. To enable the step buttons, click the debugger server instance in the Debug window. To see the stack trace, click either Step In or Step Out.

Inspecting variables

As you observe execution of your code, you can see the values and scope of variables in the Variables panel. The Variables panel displays the scope and value of variables as the CFML code executes. Only variables whose scopes are those you selected in the Preferences dialog box appear in the Variables pane.