[Erlang Systems]

1 Debugger

1.1 Introduction

Debugger is a graphical tool which can be used for debugging and testing of Erlang programs. For example, breakpoints can be set, code can be single stepped and variable values can be displayed and changed.

Warning: Note that the debugger at some point might start tracing on the processes which execute the interpreted code. This means that a conflict will occur if tracing by other means is started on any of these processes.

1.2 Getting Started with Debugger

Start Debugger by calling debugger:start(). It will start the monitor window showing information about all debugged processes.

Initially there are normally no debugged processes. First, it must be specified which modules should be debugged, or interpreted as it is also called. This is done by chosing Module->Interpret... in the monitor window and then selecting the appropriate modules from the interpret dialog window.

Note!

Only modules compiled with the option debug_info set can be interpreted. Therefore, only modules for which such a beam file can be found in the same directory, or in an ebin directory next to it, are displayed in the interpret dialog window.

When a module is interpreted, it can be viewed in a view module window. This is done by selecting the module from the Module->module->View menu. The contents of the source file is shown and it is possible to set breakpoints.

Now the program that should be debugged can be started. This is done the normal way from the Erlang shell. All processes executing code in interpreted modules will be displayed in the monitor window. It is possible to attach to any of these processes, by selecting the process and then chosing Process->Attach.

Attaching to a process will result in a attach process window being opened for this process. From the attach process window, it is possible to control the process execution, inspect variable values, set breakpoints etc.

1.3 Breakpoints

Once the appropriate modules are interpreted, breakpoints can be set at relevant locations in the source code. Breakpoints are specified on a line basis. When a process reaches a breakpoint, it stops and waits for commands (step, skip, continue,...) from the user.

Note!

When a process reaches a breakpoint, only that process is stopped. Other processes are not affected.

Breakpoints are created and deleted using the Break menu of the monitor window, view module window and attach process window.

1.3.1 Executable Lines

To have effect, a breakpoint must be set at an executable line, which is a line of code containing an executable expression such as a matching or a function call. A blank line or a line containing a comment, function head or pattern in a case- or receive statement is not executable.

In the example below, lines number 2, 4, 6, 8 and 11 are executable lines:

1: is_loaded(Module,Compiled) ->
2:   case get_file(Module,Compiled) of
3:     {ok,File} ->
4:       case code:which(Module) of
5:         ?TAG ->
6:           {loaded,File};
7:         _ ->
8:           unloaded
9:       end;
10:    false ->
11:      false
12:  end.
      

1.3.2 Status and Trigger Action

A breakpoint can be either active or inactive. Inactive breakpoints are ignored.

Each breakpoint has a trigger action which specifies what should happen when a process has reached it (and stopped):

1.3.3 Line Breakpoints

A line breakpoint is created at a certain line in a module.

images/line_break_dialog
The Line Break Dialog Window.

1.3.4 Conditional Breakpoints

A conditional breakpoint is created at a certain line in the module, but a process reaching the breakpoint will stop only if a given condition is true.

The condition is specified by the user as a module name Module and a function name Function. When a process reaches the breakpoint, Module:Function(Bindings) will be evaluated. If and only if this function call returns true, the process will stop. If the function call returns false, the breakpoint will be silently ignored.

Bindings is a list of variable bindings. Use the function int:get_binding(Variable,Bindings) to retrieve the value of Variable (given as an atom). The function returns unbound or {value,Value}.

images/cond_break_dialog
The Conditional Break Dialog Window.

Example: A conditional breakpoint calling c_test:c_break/1 is added at line 8 in the module fac. Each time the breakpoint is reached, the function is called, and when N is equal to 3 it returns true, and the process stops.

Extract from fac.erl:

4.   fac(0) ->
5.      1;
6.
7.   fac(N) ->
8.      N * fac(N - 1).
      

Definition of c_test:c_break/1:

-module(c_test).
-export([c_break/1]).

c_break(Bindings) ->
    case int:get_binding('N', Bindings) of
        {value, 3} ->
            true;
        _ ->
            false
    end.
      

1.3.5 Function Breakpoints

A function breakpoint is a set of line breakpoints, one at the first line of each clause in the given function.

images/function_break_dialog
The Function Break Dialog Window.

1.4 The Monitor Window

The monitor window is the main window of Debugger and shows information about all debugged processes, that is all processes executing code in interpreted modules.

images/monitor
The Monitor Window.

Pid
The process identifier.
Initial Call
The first call to an interpreted function by this process. (Module:Function/Arity)
Name
The registered name, if any.
Status
The current status, one of the following:
idle
The interpreted function call has returned a value, and the process is no longer executing interpreted code.
running
The process is running.
waiting
The process is waiting in a receive statement.
break
The process is stopped at a breakpoint.
exit
The process has terminated.
no_conn
There is no connection to the node where the process is located.
Information
Additional information, if any. If the process is stopped at a breakpoint, the field contains information about the location {Module,Line}. If the process has terminated, the field contains the exit reason.

1.4.1 The File Menu

Load Settings...
Try to load and restore Debugger settings from a file previously saved using Save Settings..., see below. Any errors are silently ignored.
Save Settings...
Save Debugger settings to a file. The settings include the set of interpreted files, breakpoints, and the selected options. The settings can be restored in a later Debugger session using Load Settings..., see above. Any errors are silently ignored.
Exit
Stop Debugger.

1.4.2 The Edit Menu

Clear
Remove information about all terminated processes from the window.
Kill All
Terminate all processes listed in the window using exit(Pid,kill).

1.4.3 The Module Menu

Interpret...
Open the interpret dialog window where new modules to be interpreted can be specified.
Delete All
Stop interpreting all modules. Processes executing in interpreted modules will terminate.

For each interpreted module, a corresponding entry is added to the Module menu, with the following submenu:

Delete
Stop interpreting the selected module. Processes executing in this module will terminate.
View
Open a view module window showing the contents of the selected module.

1.4.4 The Process Menu

The following menu items apply to the currently selected process, provided it is stopped at a breakpoint. See the chapter about the attach process window for more information.

Step
Next
Continue
Finish

The following menu items apply to the currently selected process.

Attach
Attach to the process and open a attach process window.
Kill
Terminate the process using exit(Pid,kill).

1.4.5 The Break Menu

The items in this menu are used to create and delete breakpoints. See the Breakpoints chapter for more information.

Line Break...
Set a line breakpoint.
Conditional Break...
Set a conditional breakpoint.
Function Break...
Set a function breakpoint.
Delete All
Remove all breakpoints.

For each breakpoint, a corresponding entry is added to the Break menu, from which it is possible to disable/enable or delete the breakpoint, and to change its trigger action.

1.4.6 The Options Menu

Trace Window
Set which areas should be visible in the attach process window. Does not affect already existing windows.
Auto Attach
Set at which events a debugged process should be automatically attached to. Also affects existing processes.
  • First Call - the first time a process calls a function in an interpreted module.

  • On Exit - at process termination.

  • On Break - when a process reaches a breakpoint.

Stack Trace
Stack On, Tail
Save call frames in the stack during evaluation.
Stack On, No Tail
Save call frames during evaluation, except for tail recursive calls.
This option consumes less memory than the previous option and may be necessary to use for processes with long lifetimes and many tail recursive calls.
Stack Off
Do not save call frames.
Does not affect already existing processes.
Back Trace Size...
Set how many call frames should be fetched when inspecting the back trace (from the attach process window). Does not affect already existing windows.

1.4.7 The Windows Menu

Contains a menu item for each open Debugger window. Selecting one of the items will raise the corresponding window.

1.4.8 The Help Menu

Help
View the Debugger documentation. Currently this function requires Netscape to be up and running.

1.5 The Interpret Dialog Window

The interpret dialog module is used for selecting which modules to interpret. Initially, the window shows the modules (erl files) and subdirectories of the current working directory.

Only modules compiled with the option debug_info set can be debugged. Therefore, only modules for which such a BEAM file can be found in the same directory, or in an ebin directory next to it, are displayed.

The debug_info option causes debug information or abstract code to be added to the BEAM file. This will increase the size of the file, and also makes it possible to reconstruct the source code. It is therefore recommended not to include debug information in code aimed for target systems.

An example of how to compile code with debug information using erlc:
% erlc +debug_info module.erl

An example of how to compile code with debug information from the Erlang shell:
4> c(module, debug_info).

images/interpret
The Interpret Dialog Window.

Browse the file hierarchy and interpret the appropriate modules by selecting a module name and pressing Choose (or carriage return), or by double clicking the module name. Interpreted modules are displayed with a * in front of the name.

Pressing All will interpret all displayed modules in the chosen directory.

Pressing Done will close the window.

Note!

In a distributed environment modules added (or deleted) for interpretation will be added (or deleted) on all known Erlang nodes.

1.6 The Attach Process Window

From an attach process window the user can interact with a debugged process. One window is opened for each process that has been attached to. Note that when attaching to a process, its execution is automatically stopped.

images/attach
The Attach Process Window.

The window is divided into five parts:

It is configurable using the Options menu which areas should be shown or hidden. By default, all areas except the trace area is shown.

1.6.1 The File Menu

Close
Close this window and detach from the process.

1.6.2 The Edit Menu

Go to line...
Go to a specified line number.
Search...
Search for a specified string.

1.6.3 The Process Menu

Step
Execute the current line of code, stepping into any function calls.
Next
Execute the current line of code and stop at the next line.
Continue
Continue the execution.
Finish
Continue the execution until the current function returns.
Skip
Skip the current line of code and stop at the next line. If used on the last line in a function body, the function will return skipped.
Time Out
Simulate a timeout when executing a receive...after statement.
Stop
Stop the execution of a running process.
Where
Make sure the current location of the execution is visible in the code area.
Kill
Terminate the process using exit(Pid,kill).
Messages
Inspect the message queue of the process. The queue is printed in the evaluator area.
Back Trace
Display the back trace of the process, i.e. a summary of the call frames on the stack, in the trace area. Requires that the trace area is visible and that the stack trace option is set to 'Stack On, Tail' or 'Stack On, No Tail'.
Up
Inspect the previous call frame. The code area will show the location and the bindings area will show the bindings for that call frame.
Down
Inspect the next call frame. The code area will show the location and the bindings area will show the bindings for that call frame.

1.6.4 The Options Menu

Trace Window
Set which areas should be visible. Does not affect other attach process windows.
Stack Trace
Same as in the monitor window, but does only affect the debugged process the window is attached to.
Back Trace Size...
Set how many call frames should be fetched when inspecting the back trace. Does not affect other attach process windows.

1.6.5 Break, Windows and Help Menus

See the chapter The Monitor Window.

1.7 The View Module Window

The view module window shows the contents of an interpreted module and makes it possible to set breakpoints.

images/view
The View Module Window.

The source code is indented and each line is prefixed with its line number.

Clicking a line will highlight it and select it to be the target of the breakpoint functions available from the Break menu. Doubleclicking a line will set a line breakpoint on that line. Doubleclicking a line with an existing breakpoint will remove the breakpoint.

Breakpoints are marked with -@-.

1.7.1 The Break Menu

The Break menu looks the same as the Break menu in the monitor window, see the chapter The Monitor Window, except that only breakpoints in the viewed module are shown.

1.7.2 File and Edit Menus

See the chapter The Attach Process Window.

1.7.3 Windows and Help Menus

See the chapter The Monitor Window.

1.8 Miscellaneous

1.8.1 Performance

Execution of interpreted code is naturally slower than for regularly compiled modules. Using the Debugger also increases the number of processes in the system, as for each debugged process another process (the meta process) is created.

It is also worth to keep in mind that programs with timers may behave differently when debugged. This is especially true when stopping the execution of a process, for example at a breakpoint. Timeouts can then occur in other processes that continue execution as normal.

1.8.2 Code loading mechanism

Code loading works almost as usual, except that interpreted modules are also stored in a database and debugged processes uses only this stored code. Re-interpreting an interpreted module will result in the new version being stored as well, but does not affect existing processes executing an older version of the code. This means that the code replacement mechanism of Erlang does not work for debugged processes.

1.9 Debugging Remote Nodes

By using debugger:start/1, it can be specified if Debugger should be started in local or global mode.

debugger:start(local | global)
    

If no argument is provided, Debugger is started in global mode.

In local mode, code is interpreted only at the current node. In global mode, code is interpreted at all known nodes. Processes at other nodes executing interpreted code will automatically be shown in the monitor window and can be attached to like any other debugged process.

It is not recommended to use Debugger in global mode on more than one node in a network, as they may interfere with each other leading to inconsistent behaviour.


Copyright © 1991-2002 Ericsson Utvecklings AB