Debugger is a graphical user interface for the Erlang interpreter, 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.
The Erlang interpreter can also be accessed via the interface
module int
, see int(3).
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, interpreted modules and
selected options.
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 one of these processes, by double-clicking it, or 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.
Right-clicking the Module entry will open a popup menu from which the appropriate module can be selected.
A line breakpoint can also be created (and deleted) by double-clicking the line when the module is displayed in the View Module or Attach Process window.
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
CModule
and a function name CFunction
. When a
process reaches the breakpoint,
CModule:CFunction(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}
.
Right-clicking the Module entry will open a popup menu from which the appropriate module can be selected.
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.
Right-clicking the Module entry will open a popup menu from which the appropriate module can be selected.
Clicking the Ok button (or 'Return' or 'Tab') when a module name has been given, will bring up all functions of the module in the listbox.
The Erlang emulator keeps track of a stack trace, information about recent function calls. This information is used, for example, if an error occurs:
1> a+1. ** exited: {badarith,[{erl_eval,eval_op,3}, {shell,exprs,6}, {shell,eval_loop,3}]} **
In the case above, the stack trace shows that the function called
last was erl_eval:eval_op/3
. See Erlang Reference
Manual, Errors and Error handling, for more information
about stack trace.
Debugger emulates the stack trace by keeping track of recently called interpreted functions. (The real stack trace cannot be used, as it shows which functions of the Debugger have been called, rather than which interpreted functions).
This information can be used to traverse the chain of function calls, using the 'Up' and 'Down' buttons of the Attach Process window.
By default, the Debugger saves information about all current function calls, that is, function calls that have not yet returned a value (option 'Stack On, Tail').
This means, however, that information is saved also for tail
recursive calls. For example, repeated calls to the loop
function of an Erlang process. This may consume unnecessary
amounts of memory for debugged processes with long lifetimes and
many tail recursive calls. It is therefore possible to set
the option 'Stack On, no tail', in which case information about
previous calls are discarded when a tail recursive call is made.
It is also possible to turn off the Debugger stack trace facility ('Stack Off'). Note: If an error occurs, in this case the stack trace will be empty.
See the section about the Monitor Window for information about how to change the stack trace option.
The Monitor window is the main window of Debugger and shows a listbox containing the names of all interpreted modules (double-clicking a module brings up the View Module window), which options are selected, and information about all debugged processes, that is all processes which have been/are executing code in interpreted modules.
The Auto Attach buttons, Stack Trace label and Back Trace Size label show some options set, see Options Menu for further information about these options.
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.
![]() |
When the Debugger is started in global mode (which is the default, see debugger:start/1), 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 call level 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)
.
The Break, Windows and Help menus look the same as in the Monitor window, see the chapter The Monitor Window, except that the Breaks menu apply to the local breakpoints only.
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 File and Edit menus look the same as in the Attach Process window, see the chapter The Attach Process Window.
The Break, Windows and Help menus look the same as in the Monitor window, see the chapter The Monitor Window, except that the Breaks menu apply to the local breakpoints only.
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 possible, but definitely not recommended to start Debugger in global mode on more than one node in a network, as they will interfer with each other leading to inconsistent behaviour.