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.
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.
![]() |
Only modules compiled with the option |
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.
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.
![]() |
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.
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.
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):
A line breakpoint is created at a certain line in a module.
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}
.
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.
A function breakpoint is a set of line breakpoints, one at the first line of each clause in the given function.
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.
Module:Function/Arity
)receive
statement.
{Module,Line}
. If the process has
terminated, the field contains the exit reason.
exit(Pid,kill)
.
For each interpreted module, a corresponding entry is added to the Module menu, with the following submenu:
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.
The following menu items apply to the currently selected process.
exit(Pid,kill)
.The items in this menu are used to create and delete breakpoints. See the Breakpoints chapter for more information.
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.
Contains a menu item for each open Debugger window. Selecting one of the items will raise the corresponding 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.
Interpretable modules are modules for which a BEAM file, compiled
with the option debug_info
set, can be found in the same
directory as the source code, or in an ebin
directory next
to it.
Modules, for which the above requirements are not fulfilled, are not interpretable and are therefore displayed within parentheses.
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).
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.
![]() |
In a distributed environment modules added (or deleted) for interpretation will be added (or deleted) on all known Erlang nodes. |
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.
The window is divided into five parts:
io:format/2
.
++ (N) <L>
N
is the level of recursion
and L
the line number.
-- (N)
==> Pid : Msg
Msg
is sent to process Pid
.
<== Msg
Msg
is received.
++ (N) receive
receive
.
++ (N) receive with timeout
receive...after
.
It is configurable using the Options menu which areas should be shown or hidden. By default, all areas except the trace area is shown.
skipped
.receive...after
statement.exit(Pid,kill)
.
See the chapter The Monitor Window.
The view module window shows the contents of an interpreted module and makes it possible to set breakpoints.
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 -@-.
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.
See the chapter The Attach Process Window.
See the chapter The Monitor Window.
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.
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.
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.