Debugging your applications

Debugging is similar to running your applications. However, when you debug you control when the application stops at specific points in the code and whether you want it to monitor important variables, and you can test fixes to your code. Both running and debugging use a configuration to control how applications are launched. When you debug your application, you run the debug version of the application file.

For an overview of the debugging tools available in the Flash Debug perspective, see The Flash Debug perspective.

In some cases, you will be prompted to look at the Eclipse log file. For more information, see Eclipse environment errors in the log file.

Starting a debugging session

To begin a debugging session, you run the application launch configuration in the Flash Debug perspective.

Debug an application

  1. In the Flex Package Explorer, select the project to debug.

  2. Select the Debug button from the main workbench toolbar.

    Note: The Debug button has two elements: the main action button and a drop-down list that shows the application files in the project that can be run or debugged. When you click the main action button, the project’s default application file is debugged. You can alternatively click the drop-down list and select any of the application files in the project to debug. You can also access the launch configuration dialog box and create or edit a launch configuration by selecting the Debug command.

    If your project has not been built yet, Adobe® Flash® Builder™ builds and runs it in debug mode.

  3. Your application appears in your default web browser or the stand-alone Flash Player and you can then use the Flash Builder debugger to interact with it.

  4. When a breakpoint is reached, the Flash Debug perspective is activated in the workbench.

Start a debugging session in the plug-in configuration

The Debug command works differently in the plug-in configuration of Flash Builder. Instead of running the selected project, it debugs the most recently launched configuration. You can also select from a list of recently launched configurations.

Adding and removing breakpoints

You use breakpoints to suspend the execution of your application so you can inspect your code and use the Flash Builder debugging tools to explore options to fix errors. You add breakpoints in the code editor and then manage them in the Breakpoints view when you debug your applications.

You add breakpoints to executable lines of code. The debugger stops only at breakpoints set on lines that contain the following:

  • MXML tags that contain an ActionScript event handler, such as <mx:Button click="dofunction()" ...>

  • ActionScript lines such as those enclosed in an <mx:Script> tag or in an ActionScript file

  • Any executable line of code in an ActionScript file

You can set breakpoints as you write code or while you debug.

Set a breakpoint in the code editor

  1. Open a project file that contains ActionScript code.

  2. Locate the line of code on which you want to set a breakpoint, and double-click in the marker bar to add a breakpoint.

    The marker bar is along the left edge of the code editor.

    A breakpoint marker is added to the marker bar and to the list of breakpoints in the Breakpoints view of the Flash Debug perspective.

When the debugger encounters a breakpoint, the application is suspended, the Flash Debug perspective is displayed, and the line of code is marked with a breakpoint. The line of code is highlighted in the code editor. You then use the debugging commands to interact with the code. (See Managing the debugging session in the Debug view).

Remove a breakpoint in the code editor

 In the marker bar, double-click an existing breakpoint.

The breakpoint is removed from the marker bar and the Breakpoints view of the Flash Debug perspective.

You manage breakpoints in the Breakpoints view. You can remove one or all breakpoints in the list or disable them and re-enable them at a later time (see Managing breakpoints in the Breakpoints view).

Setting Conditional Breakpoints

You can specify conditions for breakpoints to stop the debugger from executing when specific conditions are met. When you set a conditional breakpoint, you specify an ActionScript expression that is evaluated during the debugging session. You configure the conditional breakpoint to halt execution for any of the following conditions:

  • The expression evaluates to true.

  • The value of the expression changes.

  • A specified Hit Count has been reached.

Setting a conditional breakpoint

  1. From the context menu for a breakpoint, select Breakpoint Properties.

  2. In the Breakpoint Properties dialog, specify any of the following:

    • Enabled

      Toggle to enable or disable the breakpoint.

    • Hit Count

      Select Hit Count to enable a counter for the breakpoint. Specify a number for the Hit Count.

      If you specify both Hit Count and Enable Condition, the Hit Count is the number of times that the specified condition is met (either evaluates to true or the value of the condition changes).

      If you specify Hit Count only, then Hit Count is the number of times the breakpoint has been reached.

    • Enable Condition

      Select Enable Condition and enter an ActionScript expression to evaluate. See Examples of expressions for information on types of expressions supported for evaluation.
      Note: Flash Builder checks the syntax of the expression and notifies you of syntax errors. If you have an assignment operator in the expression, Flash Builder displays a warning.
    • Suspend when:

      Specify when to halt execution, either when the expression for the condition evaluates to true or the value of the expression changes.

Managing breakpoints in the Breakpoints view

In the Breakpoints view you manage breakpoints during a debugging session. You can remove, disable and enable, or skip them.

The following commands are available from the Breakpoints view toolbar (as shown left to right):

Button/Command

Description

Remove Selected Breakpoints

Removes the selected breakpoints.

Remove All Breakpoints

Removes all breakpoints.

Show Breakpoints Supported by Selected Target

Displays breakpoints that are applicable to the select debug target.

Go to File for Breakpoint

Opens the file (if it is not already open) that contains the breakpoint in the code editor and highlights the line of code on which the breakpoint was set. You can also simply double-click the breakpoint to display it in the code editor.

Skip All Breakpoints

Skips all breakpoints.

Expand All

Expands all breakpoints.

Collapse All

Collapses all breakpoints.

Link With Debug View

Links to Debug view.

Remove breakpoints in the Breakpoints view

You can remove one, a few, or all of the breakpoints in the Breakpoints view from the Breakpoints toolbar

 Select one or more breakpoints from the list of breakpoints, and then click Remove Selected Breakpoints.

You can also remove all the breakpoints in the Breakpoints view in a single action.

Remove all breakpoints from the Breakpoints view

 In the Breakpoints view, click Remove All Breakpoints.

Managing the debugging session in the Debug view

The Debug view is the control center of the Flash Debug perspective. You use it to control the execution of the application, to suspend, resume, or terminate the application, or to step into or over code.

The Debug view provides the following debugging commands, which are available from the Debug view toolbar (as shown left to right):

Button/Command

Description

Remove All Terminated Launches

Clears all terminated debugging sessions.

Resume

Resumes the suspended application.

Suspend

Suspends the application so that you can inspect, step into the code, and so on.

Terminate

Terminates the debugging session.

Disconnect

Disconnects the debugger when debugging remotely.

Step Into

Steps into the called function and stops at the first line of the function.

Step Over

Executes the current line of the function and then stops at the next line of the function.

Step Return

Continues execution until the current function has returned to its caller.

Drop to Frame

This command is not supported in Flash Builder.

Use Step Filters

This command is not supported in Flash Builder.

Using the Console view

The Console view displays the output from trace statements placed in your ActionScript code and also feedback from the debugger itself (status, warnings, errors, and so on).

The Console view provides the following commands, which are available from the Console view toolbar (as shown left to right):

Button/Command

Description

Terminate

Terminates the debugging session.

Remove Launch

Clears all launched debugging sessions.

Remove All Terminated Launches

Clears all terminated debugging sessions.

Clear Console

Clears all content from the Console view.

Scroll Lock

Prevents the Console view from scrolling.

Show Console When Standard Out Changes

Displays the Console when writing to standard out

Show Console When Standard Error Changes

Displays the Console when writing to standard error

Pin Console

Prevents the console from refreshing its contents when another process is selected.

Display Selected Console

Displays the selected Consoles

Open Console

Opens new console and displays pop-up menu to select other console views.

Managing variables in the Variables view

The Variables view displays the variables that the currently selected stack frame defines (in the Debug view). Simple variables (name and value) are displayed on a single line. The icons displayed with the variables provide visual cues about the type of variable.

Complex variables can be expanded to display their members. You use the Variables view to watch variables by adding them to the Expressions view and to modify the value of variables during the debugging session. You can also set watchpoints in the Variables view, as described in Using Watchpoints.

All superclass members are grouped in a separate tree node; by default you see only the members of the current class. This helps reduce excess numbers of variables that are visible at one time in Variables view.

The Variables view provides the following actions, which are available from the Variables view toolbar (as shown left to right):

Command

Description

Show Type Names

Displays the type names of variables.

Show Logical Structure

This command is not supported in Flash Builder.

Collapse All

Collapses the Variables view.

Change the value of a variable

  1. Select the variable to modify.

  2. Right-click (Control-click on Macintosh) to display the context menu and select Change Value.

  3. Enter the new value and click OK.

    The variable contains the new value.

Modified variables are displayed in red.

Find variables

 To locate a variable or variable member in the Variables view, with the Variables view selected, begin entering the name of the variable you’re looking for. You can also use the wildcard character (*) to search for words that occur anywhere within a variable name (for example, “*color”).

Icons representing variables in the Variables view

The Variables view uses icons and overlays to provide visual cues to the types of variables that are being displayed. See Icons representing language elements for a list of icons and their meaning.

View full size graphic
The Variables view

Using the Expressions view

Use the Expressions view to watch variables you selected in the Variables view and to add and evaluate watch expressions while debugging your applications.

While debugging, you can inspect and modify the value of the variables that you selected to watch. You can also add watch expressions, which are code expressions that are evaluated whenever debugging is suspended. Watch expressions are useful for watching variables that may go out of scope when you step into a different function and are therefore not visible in the view.

The Expressions view provides the following commands, which are available from the Expressions view toolbar (as shown left to right):

Command

Description

Show Type Names

Shows the object types for items in the Expressions view.

Show Logical Structure

This command is not supported in Flash Builder.

Collapse All

Collapses all expressions in view.

Remove Selected Expressions

Removes the selected variable or watch expression.

Remove All Expressions

Removes all variables and watch expressions from the Expressions view.

You can also hover the mouse pointer over an expression or variable in the source editor to see the value of that expression or variable as a tooltip. You can add the expression to the Expressions view by right-clicking and selecting Watch from the menu.

Examples of expressions

The Flash Builder Debugger supports a wide range of simple and complex expressions. The following table lists examples of expressions that can be evaluated during a debugging session. This is not the complete list of expressions supported, but just a sampling of what you can do.

Examples of supported expressions

Expression

Description

myString.length

Returns the length of a string.

myString.indexOf(‘@’)

Tracks the index of the ‘@’ character.

"constant string".charAt(0)

Tracks the character at a specific position in a string. String constants are supported.

employees.employee.@name

employees is an XML variable. This type of expression is useful for debugging E4X applications.

x == null

Reserved words representing values in expressions.

user1 === user2

Most ActionScript operators are supported.

MyClass.myStaticFunc()

Functions resolved to a class.

this.myMemberFunc()

Functions resolved using the keyword this.

String.fromCharCode(33)

String is actually a function, not a class, and String.fromCharCode is actually a dynamic member of that function.

myStaticFunc()

Can be valuated only if myStaticFunc is visible from the current scope chain

myMemberFunc()

Can be valuated only if myMemberFunc is visible from the current scope chain.

Math.max(1,2,3)

Math functions are supported.

mystring.search(/myregex/i)

Regular expressions are supported.

["my", "literal", "array"]

Creation of arrays.

new MyClass()

Instantiation of classes.

"string" + 3

Correctly handles string plus Integer.

x >>> 2

Logical shift operations supported.

3.5 + 2

Performs arithmetic operations correctly.

Limitations of expression evaluation

There are some limitations to expression evaluation.

  • Namespaces are not supported.

  • Inline objects are not supported.

  • The keyword super is not supported.

  • Fully qualified class names are not supported.

    For example, you cannot evaluate mx.controls.Button.

    You can refer to the unqualified class name. For example, you can specify Button to refer to mx.controls.Button.

    If a class name is ambiguous (two classes with the same name in different packages,) then you cannot control which class will be evaluated. However, you can specify:

    getDefinitionByName("mx.controls.Button")
  • Most E4X expressions can be evaluated, but E4X filter expressions are not supported.

    For example, you cannot evaluate myxml.(@id=='3')).

  • You cannot call functions that are defined as a variable.

Using Watchpoints

When debugging an application, you can set watchpoints on specific instances of variables to halt execution when the watched variable changes value. Because watchpoints are set on a specific instance of a variable, you cannot set the watchpoint in the code editor. Instead, you set a watchpoint from the Variables view during a debugging session.

When setting watchpoints, keep in mind the following:

  • When a debugging session ends, all watchpoints are removed.

  • You cannot set watchpoints on getters, but you can set them on the field of a getter.

    For example, you cannot set a watchpoint on width, but you can set a watchpoint on _width.

  • You cannot set watchpoints on local variables, but you can set watchpoints on members of local variables, as illustrated in the following code fragment.

    public class MyClass 
    { 
       // These are fields of a class, so you can set a watchpoint on 
       // 'memberInt', and on 'memberButton', and on 'memberButton._width': 
       private var memberInt:int = 0; 
       private var memberButton:Button = new Button(); 
     
       public function myFunction():void { 
          // You CANNOT set a watchpoint on 'i', because it is local: 
          var i:int = 0; 
     
          // You CANNOT set a watchpoint on 'someButton', because it is local; 
          // but you CAN set a watchpoint on 'someButton._width': 
          var someButton:Button = new Button(); 
     
    ... 
    }
  • Execution halts for a watchpoint when the original value of an object instance changes.

    This differs from using an expression in a conditional breakpoint to halt execution whenever a variable changes value.

Setting watchpoints

 In a debugging session, there are two ways to set a watchpoint:
  • In the Variables view, open the context menu for a variable, and select Toggle Watchpoint

  • From the Flash Builder Run menu, select Add Watchpoint.

    From the Add Watchpoint dialog, select the variable you want to watch.

The Variables view displays a “pencil icon” to indicate that a watchpoint has been set on that variable.
Note: If you attempt to set a watchpoint on a getter, Flash Builder opens a dialog suggesting a valid variable for the watchpoint. If you delete the suggested variable, the dialog lists all valid variables for the object.

Using Run to Line

Flash Builder provides the Run to Line command to break out of a loop during a debugging session.

While debugging, you might find that your code is executing a loop that repeats many times. To break out of this loop, use the Run to Line command, available from the Run menu.