debugger

v7.0

Debugger Release Notes

This document describes the changes made to the Debugger application.

Debugger 7.0

Improvements and New Features

Native records as described in EEP-79 has been implemented.

A native record is a data structure similar to the traditional tuple-based records, except that is a true data type.

Native records are considered experimental in Erlang/OTP 29 and possibly also in Erlang/OTP 30, meaning that their behavior may change, potentially requiring updates to applications that use them.

Own Id: OTP-19785 Aux Id: PR-10617

Tools such as the debugger, beam_lib, and xref no longer support BEAM files created before OTP 13B.

Own Id: OTP-19906 Aux Id: PR-10519

Multi-valued comprehensions according to EEP 78 has been implemented.

Example:

> [I, -I || I <- lists:seq(1, 5)].
[1,-1,2,-2,3,-3,4,-4,5,-5]

Own Id: OTP-19942 Aux Id: PR-9374

Added support for -unsafe attributes, which is used to mark functions as unsafe to use.

This is similar to but separate from deprecation, and the compiler will by default now generate warnings for calls to functions in Erlang/OTP that are known to be always unsafe.

Furthermore, xref can now be used to find calls to functions in another application that lack a -doc attribute (undocumented_function_calls), calls to functions in another application marked -doc false. (private_function_calls), as well as calls to unsafe functions (unsafe_function_calls).

Own Id: OTP-20066 Aux Id: PR-10839

Debugger 6.0.3

Fixed Bugs and Malfunctions

Fixed unbound error in interpreted modules

Own Id: OTP-19719 Aux Id: GH-10057, PR-10066

Debugger 6.0.2

Fixed Bugs and Malfunctions

Fixed debugger priv dir, which was removed and caused crashes when the icons could not be found.

Own Id: OTP-19687 Aux Id: PR-9994, GH-9858

Debugger 6.0.1

Fixed Bugs and Malfunctions

Restore deleted icon so that debugger does not crash on startup.

Own Id: OTP-19641 Aux Id: GH-9858, PR-9861

Debugger 6.0

Fixed Bugs and Malfunctions

Error handling has been improved when modules fail to load.

Own Id: OTP-19484 Aux Id: GH-7819, PR-9399

Improvements and New Features

Comprehensions have been extended with zip generators according to EEP 73.

Example:

1> [A+B || A <- [1,2,3] && B <- [4,5,6]].
[5,7,9]

Own Id: OTP-19184 Aux Id: PR-8926

New strict generators have been added for comprehensions.

The currently existing generators are "relaxed": they ignore terms in the right-hand side expression that do not match the left-hand side pattern.

The new strict generators fail with exception badmatch if a pattern doesn't match.

Examples:

Using the current relaxed generator operator <-, any element not matching the pattern {_,_} will be silently discarded:

1> [T || {_,_}=T <- [{ok,1},ok,{error,2}]].
[{ok,1},{error,2}]

If the intention is that all lists processed by a list comprehension must only contain tuples of size two, using the new strict version of the operator ensures that term not matching will cause a crash:

2> [T || {_,_}=T <:- [{ok,1},ok,{error,2}]].
** exception error: no match of right hand side value ok

Using the strict generator operator to mark the intention that all list elements must match the pattern could help finding mistakes quicker if something unpexected is added to the list processed by the generator.

The strict version for bitstring generators is <:=.

Own Id: OTP-19317 Aux Id: PR-8625

The license and copyright header has changed format to include an SPDX-License-Identifier. At the same time, most files have been updated to follow a uniform standard for license headers.

Own Id: OTP-19575 Aux Id: PR-9670

Debugger 5.5.0.1

Fixed Bugs and Malfunctions

Fix unbound error in interpreted modules

Own Id: OTP-19719 Aux Id: GH-10057, PR-10066

Debugger 5.5

Fixed Bugs and Malfunctions

Defining a fun in the shell using the syntax fun Name/Arity would fail. This has been corrected so that the following now works:

1> F = fun is_atom/1.
#Fun.erl.42.18682967>
> F(a).
true
3> Id = fun id/1.
#Fun.erl.42.18682967>
4> Id(42).
** exception error: undefined shell command id/1
5> id(I) -> I.
ok
6> Id(42).
42

The Debugger has also been corrected to correctly handle this syntax for a BIF.

Own Id: OTP-19322 Aux Id: GH-8963, PR-8987

Improvements and New Features

Erlang/OTP type specifications has been updated to eliminate overlapping domains.

Own Id: OTP-19310 Aux Id: GH-8810, GH-8821, PR-8986

Debugger 5.4

Fixed Bugs and Malfunctions

The dependencies for this application are now listed in the app file.

Own Id: OTP-18831 Aux Id: PR-7441

Improvements and New Features

Type specs have been added to all API functions.

Own Id: OTP-18819 Aux Id: PR-7781

The documentation has been migrated to use Markdown and ExDoc.

Own Id: OTP-18955 Aux Id: PR-8026

The Debugger now use a trace session for its internal use of tracing to avoid interfering with the user's use of tracing.

Own Id: OTP-19074 Aux Id: PR-8389

Debugger 5.3.4

Fixed Bugs and Malfunctions

Guards with nested record expression could wrongly evaluate to false.

Own Id: OTP-18958 Aux Id: GH-8120, PR-8275

Debugger 5.3.3

Fixed Bugs and Malfunctions

Map comprehensions now work in the Debugger.

Own Id: OTP-18888 Aux Id: GH-7914

Debugger 5.3.2

Fixed Bugs and Malfunctions

The call int:no_break(Module) did not remove any breakpoints.

Own Id: OTP-18644 Aux Id: GH-7336

The maybe expression is now supported in the Debugger.

Own Id: OTP-18740 Aux Id: GH-7410, PR-7599

Debugger 5.3.1.3

Fixed Bugs and Malfunctions

Guards with nested record expression could wrongly evaluate to false.

Own Id: OTP-18958 Aux Id: GH-8120, PR-8275

Debugger 5.3.1.2

Fixed Bugs and Malfunctions

The maybe expression is now supported in the Debugger.

Own Id: OTP-18740 Aux Id: GH-7410, PR-7599

Debugger 5.3.1.1

Fixed Bugs and Malfunctions

The call int:no_break(Module) did not remove any breakpoints.

Own Id: OTP-18644 Aux Id: GH-7336

Debugger 5.3.1

Fixed Bugs and Malfunctions

Fixed a bug that would cause analysis to crash.

Own Id: OTP-18372 Aux Id: GH-6580

Debugger 5.3

Improvements and New Features

The configuration files .erlang, .erlang.cookie and .erlang.crypt can now be located in the XDG Config Home directory.

See the documentation for each file and filename:basedir/2 for more details.

Own Id: OTP-17554 Aux Id: GH-5016 PR-5408 OTP-17821

Debugger 5.2.1.1

Fixed Bugs and Malfunctions

The call int:no_break(Module) did not remove any breakpoints.

Own Id: OTP-18644 Aux Id: GH-7336

Debugger 5.2.1

Fixed Bugs and Malfunctions

Fix record index matching, it was broken and could never match.

Own Id: OTP-17865 Aux Id: GH-5571

Debugger 5.2

Improvements and New Features

Improve record handling, print known records with record syntax.

Own Id: OTP-17574

Debugger 5.1

Improvements and New Features

Extended error information for failing BIF calls as proposed in EEP 54 has been implemented.

When a BIF call from the Erlang shell fails, more information about which argument or arguments that were in error will be printed. The same extended error information will by proc_lib, common_test, and qlc when BIF calls fail.

For applications that wish to provide the same extended error information, there are new functions erl_error:format_exception/3 and erl_error:format_exception/4.

There is a new error/3 BIF that allows applications or libraries to provide extended error information in the same way for their own exceptions.

Own Id: OTP-16686

Debugger 5.0

Improvements and New Features

EEP-52 has been implemented.

In binary matching, the size of the segment to be matched is now allowed to be a guard expression, and similarly in map matching the keys can now be guard expressions. See the Erlang Reference Manual and Programming Examples for more details.

Language compilers or code generators that generate Core Erlang code may need to be updated to be compatible with the compiler in OTP 23. For more details, see the section Backwards Compatibility in EEP 52.

Own Id: OTP-14708

The deprecated erlang:get_stacktrace/0 BIF now returns an empty list instead of a stacktrace. To retrieve the stacktrace, use the extended try/catch syntax that was introduced in OTP 21. erlang:get_stacktrace/0 is scheduled for removal in OTP 24.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-16484

Debugger 4.2.8

Fixed Bugs and Malfunctions

Fix a bug where Unicode atoms are printed differently depending on if integer lists are printed as strings or not.

Own Id: OTP-16186

Debugger 4.2.7

Fixed Bugs and Malfunctions

All incorrect (that is, all) uses of "can not" has been corrected to "cannot" in source code comments, documentation, examples, and so on.

Own Id: OTP-14282 Aux Id: PR-1891

Debugger 4.2.6

Fixed Bugs and Malfunctions

Improved documentation.

Own Id: OTP-15190

Debugger 4.2.5

Fixed Bugs and Malfunctions

Fix a bug where calling a fun inside a binary would crash the Debugger.

Own Id: OTP-14957 Aux Id: PR-1741

Debugger 4.2.4

Fixed Bugs and Malfunctions

Do not quote variables and button names in Debugger windows. The bug was introduced in Erlang/OTP 20.1.

Own Id: OTP-14802

Debugger 4.2.3

Improvements and New Features

Tools are updated to show Unicode atoms correctly.

Own Id: OTP-14464

Debugger 4.2.2

Fixed Bugs and Malfunctions

The Erlang shell, qlc:string_to_handle(), and the Debugger (the Evaluator area and Edit variable window of the Bindings area) can parse pids, ports, references, and external funs, as long as they can be created in the running system.

Own Id: OTP-14296

Fix editing of simple binary values in the Bindings area of the Debugger's Attach Process Window.

Own Id: OTP-14318

Improvements and New Features

Miscellaneous updates due to atoms containing arbitrary Unicode characters.

Own Id: OTP-14285

Debugger 4.2.1

Fixed Bugs and Malfunctions

Update build scripts to not make assumptions about where env, cp and perl are located.

Own Id: OTP-13800

A bug causing non-interpreted code to crash the debugger has been fixed.

Own Id: OTP-13756

Debugger 4.2

Improvements and New Features

When the debugger searches for source files, it will also use the location of the source in the compilation information part of the BEAM file.

Own Id: OTP-13375

Debugger 4.1.2

Improvements and New Features

Documentation corrections.

Own Id: OTP-12994

Debugger 4.1.1

Fixed Bugs and Malfunctions

Fix crash when starting a quick debugging session. Thanks Alan Duffield.

Own Id: OTP-12911 Aux Id: seq12906

Debugger 4.1

Improvements and New Features

Support variables as Map keys in expressions and patterns

Erlang will accept any expression as keys in Map expressions and it will accept literals or bound variables as keys in Map patterns.

Own Id: OTP-12218

Debugger 4.0.3

Fixed Bugs and Malfunctions

Fix save state which did not work on Mac.

Own Id: OTP-12378

Debugger 4.0.2

Fixed Bugs and Malfunctions

Make sure to install .hrl files when needed

Own Id: OTP-12197

Invoking debugger functions ia/1 and iaa/1 crashed, when it tried to invoke the old and removed gs based gui functions.

Own Id: OTP-12357

Debugger 4.0.1

Fixed Bugs and Malfunctions

Fix evaluation of map updates in the debugger and erl_eval

Reported-by: José Valim

Own Id: OTP-11922

Debugger 4.0

Fixed Bugs and Malfunctions

The debugger now correctly evaluates code such as 'X = true andalso X'. (Thanks to Anthony Ramine.)

Own Id: OTP-11553

A few subtle bugs in the evaluation of code in the debugger has been corrected. (Thanks to Anthony Ramine.)

Own Id: OTP-11676

Application upgrade (appup) files are corrected for the following applications:

asn1, common_test, compiler, crypto, debugger, dialyzer, edoc, eldap, erl_docgen, et, eunit, gs, hipe, inets, observer, odbc, os_mon, otp_mibs, parsetools, percept, public_key, reltool, runtime_tools, ssh, syntax_tools, test_server, tools, typer, webtool, wx, xmerl

A new test utility for testing appup files is added to test_server. This is now used by most applications in OTP.

(Thanks to Tobias Schlager)

Own Id: OTP-11744

Improvements and New Features

Removed gs based applications and gs based backends. The observer application replaces the removed applications.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-10915

Support Maps syntax in debugger (Thanks to Anthony Ramine).

Own Id: OTP-11673

Debugger 3.2.12

Improvements and New Features

Fix matching of floating point middle-endian machines. Thanks to Johannes Weissl.

Own Id: OTP-11201

Debugger 3.2.11

Improvements and New Features

A new checkbox has been added. When it is checked, the range set by the erl flag +pc is used for determining when to print lists of integers as strings. When it is unchecked, integer lists are never printed as strings.

A minor incompatibility: settings saved by Erlang R16B01 or later cannot be read by Erlang R16B or earlier.

Own Id: OTP-10899

Erlang source files with non-ASCII characters are now encoded in UTF-8 (instead of latin1).

Own Id: OTP-11041 Aux Id: OTP-10907

Debugger 3.2.10

Improvements and New Features

The +pc flag to erl can be used to set the range of characters considered printable. This affects how the shell and io:format("~tp",...) functionality does heuristic string detection. More can be read in STDLIB users guide.

Own Id: OTP-10884

Debugger 3.2.9

Fixed Bugs and Malfunctions

Fix Debugger settings dialog due to changed behavior in wxFileDialog (Thanks to Håkan Mattsson)

Own Id: OTP-10621

Improvements and New Features

Support for Unicode has been implemented.

Own Id: OTP-10302

Where necessary a comment stating encoding has been added to Erlang files. The comment is meant to be removed in Erlang/OTP R17B when UTF-8 becomes the default encoding.

Own Id: OTP-10630

Integer lists and utf-8 binaries in variables are now displayed as strings.

Own Id: OTP-10679

Debugger 3.2.8

Fixed Bugs and Malfunctions

Fixed disappearing breakpoints bug, reported by Ricardo Catalinas Jiménez.

Own Id: OTP-9950

Debugger 3.2.7

Fixed Bugs and Malfunctions

Fix "OK" spelling in debugger messages and variables

Simple code refactor in the debugger: renames all the occurrences of "Ok" to "OK" in the code, variable names and strings. This improves the consistency of the code and follows the GTK UI where "OK" is always used.(Thanks to Ricardo Catalinas Jiménez)

Own Id: OTP-9699

Improvements and New Features

Variables are now now allowed in 'fun M:F/A' as suggested by Richard O'Keefe in EEP-23.

The representation of 'fun M:F/A' in the abstract format has been changed in an incompatible way. Tools that directly read or manipulate the abstract format (such as parse transforms) may need to be updated. The compiler can handle both the new and the old format (i.e. extracting the abstract format from a pre-R15 BEAM file and compiling it using compile:forms/1,2 will work). The syntax_tools application can also handle both formats.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-9643

Debugger 3.2.6

Improvements and New Features

Fix issues reported by dialyzer.

Own Id: OTP-9107

Debugger 3.2.5

Improvements and New Features

Miscellaneous updates

Own Id: OTP-8976

Debugger 3.2.4

Improvements and New Features

Type specs have been added/cleaned up. (Thanks to Kostis Sagonas.)

Own Id: OTP-8757

Debugger 3.2.3

Improvements and New Features

Warnings due to new autoimported BIFs removed

Own Id: OTP-8674 Aux Id: OTP-8579

The predefined builtin type tid() has been removed. Instead, ets:tid() should be used.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-8687

Debugger 3.2.2

Fixed Bugs and Malfunctions

Bugs have been fixed in the evaluation of comprehensions and short-circuit expressions in guards.

Own Id: OTP-8310

Improvements and New Features

Miscellaneous corrections of the WX version of the debugger.

Own Id: OTP-8346

Debugger 3.2.1

Improvements and New Features

The documentation is now built with open source tools (xsltproc and fop) that exists on most platforms. One visible change is that the frames are removed.

Own Id: OTP-8201

Debugger 3.2

Improvements and New Features

Added a new gui, start with debugger:start(gs) for old gui.

Own Id: OTP-7366

The undocumented, unsupported, and deprecated guard BIF is_constant/1 has been removed.

* INCOMPATIBILITY with R12B *

Own Id: OTP-7673

Debugger 3.1.1.4

Improvements and New Features

There is now experimental support for loading of code from archive files. See the documentation of code, init, erl_prim_loaderand escript for more info.

The error handling of escripts has been improved.

An escript may now set explicit arguments to the emulator, such as -smp enabled.

An escript may now contain a precompiled beam file.

An escript may now contain an archive file containing one or more applications (experimental).

The internal module code_aux has been removed.

Own Id: OTP-7548 Aux Id: otp-6622

Debugger 3.1.1.3

Improvements and New Features

Minor changes.

Own Id: OTP-7388

Debugger 3.1.1.2

Improvements and New Features

The documentation has been updated so as to reflect the last updates of the Erlang shell as well as the minor modifications of the control sequence p of the io_lib module.

Superfluous empty lines have been removed from code examples and from Erlang shell examples.

Own Id: OTP-6944 Aux Id: OTP-6554, OTP-6911

Debugger 3.1.1.1

Improvements and New Features

Minor Makefile changes.

Own Id: OTP-6689

Obsolete guard tests (such as list()) have been replaced with the modern guard tests (such as is_list()).

Own Id: OTP-6725

Debugger 3.1.1

Fixed Bugs and Malfunctions

Removed some dead code from dbg_ieval.

Own Id: OTP-6552

Debugger 3.1

Fixed Bugs and Malfunctions

The interpreter could not handle the case where an expression that should evaluate to a fun referred to uninterpreted code.

Own Id: OTP-6061 Aux Id: seq10295

Timeout for gen_server calls within Debugger is now set to infinity.

Own Id: OTP-6103

Improvements and New Features

Notification windows are now centered over a parent window.

Own Id: OTP-6011 Aux Id: OTP-5987

When interpreting a module, it is now checked that the module does not belong to the Kernel, STDLIB, GS or Debugger application, as interpreting a module used by the debugger/interpreter itself will lead to a deadlock or emulator crash.

Also int:interpretable(Mod) has been extended to return {error,{app,App}} if Mod belongs to one of the above applications.

Own Id: OTP-6020

andalso/orelse is now supported.

Own Id: OTP-6021 Aux Id: OTP-5894

Debugger 3.0.1

Fixed Bugs and Malfunctions

When evaluating a guard expression for a fun function clause, the environment variable bindings were not taken into account.

Own Id: OTP-5837

Improvements and New Features

A number of smaller improvements to the GUI:

Multiple choices now possible in Function Break Dialog Window.

Right-clicking the Module entry in a Break Dialog Window will open a popup menu from which the appropriate (interpreted) module can be selected.

Auto Attach options can now be changed using the buttons in the left part of the Monitor Window, not only by the corresponding menu buttons.

Buttons for enabling and disabling all breakpoints have been added.

View Module Window keyboard shortcuts corrected.

Own Id: OTP-4284

Debugger 3.0

Improvements and New Features

Debugger can now handle try-catch. This meant large parts of the interpreter had to be rewritten. Also, some small changes to the GUI have been made.

Own Id: OTP-5730

Debugger 2.3.3

Improvements and New Features

It is now possible to encrypt the debug information in Beam files, to help keep the source code secret. See the documentation for compile on how to provide the key for encrypting, and the documentation for beam_lib on how to provide the key for decryption so that tools such as the Debugger, Xref, or Cover can be used.

The beam_lib:chunks/2 functions now accepts an additional chunk type 'compile_info' to retrieve the compilation information directly as a term. (Thanks to Tobias Lindahl.)

Own Id: OTP-5460 Aux Id: seq9787

Debugger 2.3.2

Fixed Bugs and Malfunctions

The graphic applications now search for HTML documentation in the correct place.

Own Id: OTP-5381

Debugger 2.3.1

Fixed Bugs and Malfunctions

Package support has been added to the debugger. Thanks to Richard Carlsson in the HiPE project.

Own Id: OTP-5255

Improvements and New Features

Updated to handle the latest version of the compiler.

Own Id: OTP-5265

Introduction

Scope

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.

Debugger can also be accessed through the interface module int.

Prerequisites

It is assumed that the reader is familiar with the Erlang programming language.

Modules to be debugged must include debug information, for example, erlc +debug_info MODULE.erl.

Debugger

Getting Started

To use Debugger, the basic steps are as follows:

Step 1. Start Debugger by calling debugger:start().

The Monitor window is displayed with information about all debugged processes, interpreted modules, and selected options. Initially there are normally no debugged processes. First, it must be specified which modules that are to be debugged (also called interpreted). Proceed as follows:

Step 2. Select Module > Interpret... in the Monitor window.

The Interpret Modules window is displayed.

Step 3. Select the appropriate modules from the Interpret Dialog window.

Note

Only modules compiled with option debug_info set can be interpreted. Non-interpretable modules are displayed within parenthesis in the Interpret Modules window.

Step 4. In the Monitor window, select Module > the module to be interpreted > View.

The contents of the source file is displayed in the View Module window.

Step 5. Set the breakpoints, if any.

Step 6. Start the program to be debugged. This is done the normal way from the Erlang shell.

All processes executing code in interpreted modules are displayed in the Monitor window.

Step 7. To attach to one of these processes, double-click it, or select the process and then choose Process > Attach. Attaching to a process opens an Attach Process window for this process.

Step 8. From the Attach Process window, you can control the process execution, inspect variable values, set breakpoints, and so on.

Breakpoints and Break Dialog Windows

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 either the Monitor window, View Module window, or Attach Process window.

Executable Lines

To have an 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 statement or receive statement is not executable.

In the following example, lines 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.

Status and Trigger Action

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

Each breakpoint has a trigger action that specifies what is to happen when a process has reached it (and stopped):

Enable - Breakpoint is to remain active (default).

Disable - Breakpoint is to be made inactive.

Delete - Breakpoint is to be deleted.

Line Breakpoints

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

Right-click the Module entry to 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 window or Attach Process window.

Conditional Breakpoints

A conditional breakpoint is created at a certain line in the module, but a process reaching the breakpoint stops only if a specified 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) is evaluated. If and only if this function call returns true, the process stops. If the function call returns false, the breakpoint is silently ignored.

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

Right-click the Module entry to 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 6 in module fact. Each time the breakpoint is reached, the function is called. When N is equal to 3, the function returns true and the process stops.

Extract from fact.erl:

5. fac(0) -> 1;
6. fac(N) when N > 0, is_integer(N) -> 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.

Function Breakpoints

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

To open a popup menu from which the appropriate module can be selected, right-click the Module entry.

To bring up all functions of the module in the listbox, click the OK button (or press the Return or Tab key) when a module name has been specified,.

Stack Trace

The Erlang emulator keeps track of a stack trace, information about recent function calls. This information is used if an error occurs, for example:

1> catch a+1.
{'EXIT',{badarith,[{erlang,'+',[a,1],[]},
                   {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,573}]},
                   {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,357}]},
                   {shell,exprs,7,[{file,"shell.erl"},{line,674}]},
                   {shell,eval_exprs,7,[{file,"shell.erl"},{line,629}]},
                   {shell,eval_loop,3,[{file,"shell.erl"},{line,614}]}]}}

For details about the stack trace, see section Errors and Error Handling in the Erlang Reference Manual.

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 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 in the Attach Process window.

By default, Debugger only saves information about recursive function calls, that is, function calls that have not yet returned a value (option Stack On, No Tail).

Sometimes, however, it can be useful to save all calls, even tail-recursive calls. This is done with option Stack On, Tail. Notice that this option consumes more memory and slows down execution of interpreted functions when there are many tail-recursive calls.

To turn off the Debugger stack trace facility, select option Stack Off.

Note

If an error occurs, the stack trace becomes empty in this case.

For information about how to change the stack trace option, see section Monitor Window.

Monitor Window

The Monitor window is the main window of Debugger and displays the following:

A listbox containing the names of all interpreted modules

Double-clicking a module brings up the View Module window.

Which options are selected

Information about all debugged processes, that is, all processes that have been or are executing code in interpreted modules

The Auto Attach boxes, Stack Trace label, Back Trace Size label, and Strings box display some options set. For details about these options, see section Options Menu.

Process Grid

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. If a registered name is not displayed, it can be that Debugger received information about the process before the name was registered. Try selecting Edit > Refresh.

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 - More 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.

File Menu

Load Settings... - Tries to load and restore Debugger settings from a file previously saved using Save Settings... (see below). Any errors are silently ignored.

Notice that settings saved by Erlang/OTP R16B01 or later cannot be read by Erlang/OTP R16B or earlier.

Save Settings... - Saves 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 - Stops Debugger.

Edit Menu

Refresh - Updates information about debugged processes. Information about all terminated processes are removed from the window. All Attach Process windows for terminated processes are closed.

Kill All - Terminates all processes listed in the window using exit_signal(Pid, kill).

Module Menu

Interpret... - Opens the Interpret Modules window, where new modules to be interpreted can be specified.

Delete All - Stops interpreting all modules. Processes executing in interpreted modules terminate.

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

Delete - Stops interpreting the selected module. Processes executing in this module terminate.

View - Opens a View Module window, displaying the contents of the selected module.

Process Menu

The following menu items apply to the currently selected process, provided it is stopped at a breakpoint (for details, see section Attach Process window):

Step

Next

Continue

Finish

The following menu items apply to the currently selected process:

Attach - Attaches to the process and open an Attach Process window.

Kill - Terminates the process using exit_signal(Pid, kill).

Break Menu

The items in this menu are used to create and delete breakpoints. For details, see section Breakpoints.

Line Break... - Sets a line breakpoint.

Conditional Break... - Sets a conditional breakpoint.

Function Break... - Sets a function breakpoint.

Enable All - Enables all breakpoints.

Disable All - Disables all breakpoints.

Delete All - Removes 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.

Options Menu

Trace Window - Sets the areas to be visible in an Attach Process window. Does not affect existing Attach Process windows.

Auto Attach - Sets the events a debugged process is to be attached to automatically. Affects existing debugged 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 - Sets the stack trace option, see section Stack Trace. Does not affect existing debugged processes.

Stack On, Tail - Saves information about all current calls.

Stack On, No Tail - Saves information about current calls, discarding previous information when a tail recursive call is made.

Stack Off - Does not save any information about current calls.

Strings - Sets the integer lists to be printed as strings. Does not affect existing debugged processes.

Use range of +pc flag - Uses the printable character range set by the erl(1) flag +pc.

Back Trace Size... - Sets how many call frames to be fetched when inspecting the call stack from the Attach Process window. Does not affect existing Attach Process windows.

Windows Menu

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

Help Menu

Help - Shows the Debugger documentation. This function requires a web browser.

Interpret Modules Window

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

Interpretable modules are modules for which a .beam file, compiled with option debug_info set, is located in the same directory as the source code, or in an ebin directory next to it.

Modules for which these requirements are not fulfilled are not interpretable and are therefore displayed within parentheses.

Option debug_info causes debug information or abstract code to be added to the .beam file. This increases the file size and 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).

To browse the file hierarchy and interpret the appropriate modules, either select a module name and click Choose (or press carriage return), or double-click the module name. Interpreted modules have the type erl src.

To interpret all displayed modules in the chosen directory, click All.

To close the window, click Done.

Note

When Debugger is started in global mode (which is the default, see debugger:start/0), modules added (or deleted) for interpretation are added (or deleted) on all known Erlang nodes.

Attach Process Window

From an Attach Process window, you can interact with a debugged process. One window is opened for each process that has been attached to. Notice that when attaching to a process, its execution is automatically stopped.

The window is divided into the following five parts:

The Code area, displaying the code being executed. The code is indented and each line is prefixed with its line number. If the process execution is stopped, the current line is marked with -->. An existing break point at a line is marked with a stop symbol. In the example shown in the illustration, the execution stopped at line 6, before the execution of fac/1.

Active breakpoints are displayed in red and inactive breakpoints in blue.

The Button area, with buttons for quick access to frequently used functions in the Process menu.

The Evaluator area, where you can evaluate functions within the context of the debugged process, if that process execution is stopped.

The Bindings area, displaying all variables bindings. If you click a variable name, the value is displayed in the Evaluator area. Double-click a variable name to open a window where the variable value can be edited. Notice however that pid, port, reference, or fun values cannot be edited unless they can be represented in the running system.

The Trace area, which displays a trace output for the process.

++ (N) <L> - Function call, where N is the call level and L the line number.

-- (N) - Function return value

.

==> Pid : Msg - The message Msg is sent to process Pid.

<== Msg - The message Msg is received.

++ (N) receive - Waiting in a receive.

++ (N) receive with timeout - Waiting in a receive...after.

The Trace area also displays Back Trace, a summary of the current function calls on the stack.

Using the Options menu, you can set which areas to be displayed. By default, all areas except the Trace area are displayed.

File Menu

Close - Closes this window and detach from the process.

Edit Menu

Go to line... - Goes to a specified line number.

Search... - Searches for a specified string.

Process Menu

Step - Executes the current code line, stepping into any (interpreted) function calls.

Next - Executes the current code line and stop at the next line.

Continue - Continues the execution.

Finish - Continues the execution until the current function returns.

Skip - Skips the current code line and stop at the next line. If used on the last line in a function body, the function returns skipped.

Time Out - Simulates a time-out when executing a receive...after statement.

Stop - Stops the execution of a running process, that is, make the process stop at a breakpoint. The command takes effect (visibly) the next time the process receives a message.

Where - Verifies that the current location of the execution is visible in the code area.

Kill - Terminates the process using exit_signal(Pid, kill).

Messages - Inspects the message queue of the process. The queue is displayed in the Evaluator area.

Back Trace - Displays the back trace of the process, a summary of the current function calls on the stack, in the Trace area. Requires that the Trace area is visible and that the Stack Trace option is Stack On, Tail or Stack On, No Tail.

Up - Inspects the previous function call on the stack, showing the location and variable bindings.

Down - Inspects the next function call on the stack, showing the location and variable bindings.

Options Menu

Trace Window - Sets which areas are to be visible. Does not affect other Attach Process windows.

Stack Trace - Same as in the Monitor window, but only affects the debugged process the window is attached to.

Strings - Same as in the Monitor window, but only affects the debugged process the window is attached to.

Back Trace Size... - Sets how many call frames are to be fetched when inspecting the call stack. Does not affect other Attach Process windows.

Break, Windows, and Help Menus

The Break, Windows, and Help menus are the same as in the Monitor Window, except that the Breaks menu applies only to local breakpoints.

View Module Window

The View Module window displays 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 highlights it and selects it to be the target of the breakpoint functions available from the Break menu. To set a line breakpoint on a line, double-click it. To remove the breakpoint, double-click the line with an existing breakpoint.

Breakpoints are marked with a stop symbol.

File and Edit Menus

The File and Edit menus are the same as in the Attach Process Window.

Break, Windows, and Help Menus

The Break, Windows, and Help menus are the same as in the Monitor Window, except that the Break menu applies only to local breakpoints.

Performance

Execution of interpreted code is naturally slower than for regularly compiled modules. Using 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 can behave differently when debugged. This is especially true when stopping the execution of a process (for example, at a breakpoint). Time-outs can then occur in other processes that continue execution as normal.

Code Loading Mechanism

Code loading works almost as usual, except that interpreted modules are also stored in a database and debugged processes use only this stored code. Reinterpreting an interpreted module results 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.

Debugging Remote Nodes

By using debugger:start/1, you can specify if Debugger is to be started in local or global mode:

debugger:start(local | global)

If debugger:start/0 is called, Debugger starts in global mode.

In local mode, code is interpreted only on the current node. In global mode, code is interpreted on all known nodes. Processes on other nodes executing interpreted code are automatically displayed in the Monitor window and can be attached to like any other debugged process.

Note

It not recommended to start Debugger in global mode on more than one node in a network, as the nodes interfere with each other, leading to inconsistent behavior.

debugger

The Erlang Debugger for debugging and testing of Erlang programs.

Summary

Functions

quick(Module, Name, Args)

Debugs a single process.

start()

Starts Debugger.

start(ModeOrFile)

Starts Debugger.

start(Mode, File)

Starts Debugger.

Functions

quick(Module, Name, Args)

-spec quick(Module, Name, Args) -> term() when Module :: atom(), Name :: atom(), Args :: [term()].

Debugs a single process.

The module Module is interpreted and apply(Module, Name, Args) is called. This opens an "Attach Process" window. For details, see the User's Guide.

start()

-spec start() -> term().

Starts Debugger.

Started by this function, Debugger interprets code on all known nodes.

start(ModeOrFile)

-spec start(Mode) -> term() when Mode :: local | global | wx;
           (File) -> term() when File :: string().

Starts Debugger.

If ModeOrFile is a string, it is assumed to be the name of a file, and Debugger tries to load its settings from this file. For details about settings, see the User's Guide.

If ModeOrFile is atom local, Debugger interprets code only at the current node. If ModeOrFile is global, Debugger interprets code on all known nodes.

start(Mode, File)

-spec start(Mode, File) -> term() when Mode :: local | global, File :: string().

Starts Debugger.

Debugger tries to load its settings from the file named by File. For details about settings, see the User's Guide.

If Mode is local, Debugger interprets code only on the current node. If Mode is global, Debugger interprets code on all known nodes.

i

Debugger/Interpreter Interface.

The i module provides short forms for some of the functions used by the graphical Debugger and some of the functions in module int, the Erlang interpreter.

This module also provides facilities for displaying status information about interpreted processes and break points.

It is possible to attach to interpreted processes by only giving the corresponding process identity. By default, an attachment window is displayed. Processes at other Erlang nodes can be attached manually or automatically.

The functions in this module are defined in the Erlang shell. That is, they can be called without the i: prefix. For example:

1> ii(t).
{module,t}
2> iaa([init]).
true

Summary

Functions

help()

Prints help for using the functions in this module.

ia(Pid)

Attaches to the debugged process Pid.

ia(Pid, Function)

Attaches to the debugged process Pid.

ia(X, Y, Z)

Equivalent to ia(Pid), where Pid is the result of calling the shell function pid(X, Y, Z).

ia(X, Y, Z, Function)

Equivalent to ia(Pid, Function), where Pid is the result of calling the shell function pid(X, Y, Z).

iaa(Flags)

Sets when to attach to a debugged process automatically.

iaa(Flags, Function)

Sets when and how to attach to a debugged process automatically.

ib(Module, Line)

Creates a breakpoint at Line in Module.

ib(Module, Name, Arity)

Creates breakpoints at the first line of every clause of function Module:Name/Arity.

iba(Module, Line, Action)

Sets the trigger action of the breakpoint at Line in Module to Action.

ibc(Module, Line, Function)

Sets the conditional test of the breakpoint at Line in Module to Function.

ibd(Module, Line)

Makes the breakpoint at Line in Module inactive.

ibe(Module, Line)

Makes the breakpoint at Line in Module active.

ic()

Clears information about processes executing interpreted code by removing all information about terminated processes.

ii(Module)

Interprets the specified module(s) on the local node.

il()

Makes a printout of all interpreted modules.

im()

Starts a new graphical Monitor window.

ini(Module)

Interprets the specified module(s) on all known nodes.

inq(AbsModule)

Stops interpreting the specified module on all known nodes.

ip()

Prints the current status of all interpreted processes.

ipb()

Prints all existing breakpoints.

ipb(Module)

Prints all existing breakpoints in Module.

iq(AbsModule)

Stops interpreting the specified module on the local node.

ir()

Deletes all breakpoints in all interpreted modules.

ir(Module)

Deletes all breakpoints in Module.

ir(Module, Line)

Deletes the breakpoint at Line in Module.

ir(Module, Name, Arity)

Deletes the breakpoints at the first line of every clause of function Module:Name/Arity.

ist(Flag)

Sets how to save call frames in the stack.

iv()

Returns the current version of the interpreter (Debugger).

Functions

help()

-spec help() -> ok.

Prints help for using the functions in this module.

ia(Pid)

-spec ia(Pid) -> ok | no_proc when Pid :: pid().

Attaches to the debugged process Pid.

An "Attach Process" window is opened for the process.

ia(Pid, Function)

-spec ia(Pid, Function) -> ok | no_proc
            when Pid :: pid(), Function :: {Module, Name}, Module :: module(), Name :: atom().

Attaches to the debugged process Pid.

The interpreter calls spawn(Module, Name, [Pid]) (and ignores the result).

ia(X, Y, Z)

-spec ia(X, Y, Z) -> ok | no_proc when X :: integer(), Y :: integer(), Z :: integer().

Equivalent to ia(Pid), where Pid is the result of calling the shell function pid(X, Y, Z).

ia(X, Y, Z, Function)

-spec ia(X, Y, Z, Function) -> ok | no_proc
            when
                X :: integer(),
                Y :: integer(),
                Z :: integer(),
                Function :: {Module, Name},
                Module :: module(),
                Name :: atom().

Equivalent to ia(Pid, Function), where Pid is the result of calling the shell function pid(X, Y, Z).

An attached process is expected to call the unofficial function int:attached(Pid) and to be able to handle messages from the interpreter. For an example, see dbg_wx_trace.erl.

iaa(Flags)

-spec iaa(Flags) -> true when Flags :: [init | break | exit].

Sets when to attach to a debugged process automatically.

Debugger supplies a function that opens "Attach Process" window for the process.

See int:auto_attach/2 for more information.

iaa(Flags, Function)

-spec iaa(Flags, Function) -> true
             when
                 Flags :: [init | break | exit],
                 Function :: {Module, Name, Args},
                 Module :: module(),
                 Name :: atom(),
                 Args :: [term()].

Sets when and how to attach to a debugged process automatically.

See int:auto_attach/2 for more information.

ib(Module, Line)

-spec ib(Module, Line) -> ok | {error, break_exists} when Module :: module(), Line :: integer().

Creates a breakpoint at Line in Module.

ib(Module, Name, Arity)

-spec ib(Module, Name, Arity) -> ok | {error, function_not_found}
            when Module :: module(), Name :: atom(), Arity :: integer().

Creates breakpoints at the first line of every clause of function Module:Name/Arity.

iba(Module, Line, Action)

-spec iba(Module, Line, Action) -> ok
             when Module :: module(), Line :: integer(), Action :: enable | disable | delete.

Sets the trigger action of the breakpoint at Line in Module to Action.

ibc(Module, Line, Function)

-spec ibc(Module, Line, Function) -> ok
             when Module :: module(), Line :: integer(), Function :: {Module, Name}, Name :: atom().

Sets the conditional test of the breakpoint at Line in Module to Function.

The conditional test is performed by calling Module:Name(Bindings), where Bindings is the current variable bindings. The function must return true (break) or false (do not break). To retrieve the value of a variable Var use int:get_binding(Var, Bindings).

ibd(Module, Line)

-spec ibd(Module, Line) -> ok when Module :: module(), Line :: integer().

Makes the breakpoint at Line in Module inactive.

ibe(Module, Line)

-spec ibe(Module, Line) -> ok when Module :: module(), Line :: integer().

Makes the breakpoint at Line in Module active.

ic()

-spec ic() -> ok.

Clears information about processes executing interpreted code by removing all information about terminated processes.

ii(Module)

-spec ii(AbsModules | AbsModule) -> Result
            when
                AbsModules :: [AbsModule, ...],
                AbsModule :: Module | File,
                Module :: module(),
                File :: file:name_all(),
                Result :: AbsModuleResult | AbsModulesResult,
                AbsModuleResult :: {module, Module} | error,
                AbsModulesResult :: ok.

Interprets the specified module(s) on the local node.

If AbsModule :: Module | File, then Result :: {module, Module} | error.

If AbsModules :: [AbsModule], then Result :: ok.

See int:i/1 for more information.

il()

-spec il() -> ok.

Makes a printout of all interpreted modules.

Modules are printed together with the full path name of the corresponding source code file.

im()

-spec im() -> pid().

Starts a new graphical Monitor window.

This is the Monitor window, the main window of Debugger. All the Debugger and interpreter functionality is accessed from the Monitor window. This window displays the status of all processes that have been or are executing interpreted modules.

ini(Module)

-spec ini(AbsModules | AbsModule) -> Result
             when
                 AbsModules :: [AbsModule],
                 AbsModule :: Module | File,
                 Module :: module(),
                 File :: file:name_all(),
                 Result :: AbsModuleResult | AbsModulesResult,
                 AbsModuleResult :: {module, Module} | error,
                 AbsModulesResult :: ok.

Interprets the specified module(s) on all known nodes.

If AbsModule :: Module | File, then Result :: {module, Module} | error.

If AbsModules :: [AbsModule], then Result :: ok.

See int:ni/1 for more information.

inq(AbsModule)

-spec inq(AbsModule) -> ok when AbsModule :: Module | File, Module :: module(), File :: file:name_all().

Stops interpreting the specified module on all known nodes.

ip()

-spec ip() -> ok.

Prints the current status of all interpreted processes.

ipb()

-spec ipb() -> ok.

Prints all existing breakpoints.

ipb(Module)

-spec ipb(Module) -> ok when Module :: module().

Prints all existing breakpoints in Module.

iq(AbsModule)

-spec iq(AbsModule) -> ok when AbsModule :: Module | File, Module :: module(), File :: file:name_all().

Stops interpreting the specified module on the local node.

ir()

-spec ir() -> ok.

Deletes all breakpoints in all interpreted modules.

ir(Module)

-spec ir(Module) -> ok when Module :: module().

Deletes all breakpoints in Module.

ir(Module, Line)

-spec ir(Module, Line) -> ok when Module :: module(), Line :: integer().

Deletes the breakpoint at Line in Module.

ir(Module, Name, Arity)

-spec ir(Module, Name, Arity) -> ok | {error, function_not_found}
            when Module :: module(), Name :: atom(), Arity :: integer().

Deletes the breakpoints at the first line of every clause of function Module:Name/Arity.

ist(Flag)

-spec ist(Flag) -> true when Flag :: all | no_tail | false.

Sets how to save call frames in the stack.

See int:stack_trace/1 for more information.

iv()

-spec iv() -> atom().

Returns the current version of the interpreter (Debugger).

int

Interpreter Interface.

The Erlang interpreter provides mechanisms for breakpoints and stepwise execution of code. It is primarily intended to be used by Debugger; see the Users's Guide for Debugger and module debugger.

The following can be done from the shell:

Specify the modules to be interpreted.

Specify breakpoints.

Monitor the current status of all processes executing code in interpreted modules, also processes at other Erlang nodes.

By attaching to a process executing interpreted code, it is possible to examine variable bindings and order stepwise execution. This is done by sending and receiving information to/from the process through a third process, called the meta process. You can implement your own attached process. See int.erl for available functions and dbg_wx_trace.erl for possible messages.

The interpreter depends on the Kernel, STDLIB, and WX applications. This means that modules belonging to any of these applications are not allowed to be interpreted, as it could lead to a deadlock or emulator crash. This also applies to modules belonging to the Debugger application.

Breakpoints

Breakpoints are specified on a line basis. When a process executing code in an interpreted module reaches a breakpoint, it stops. This means that a breakpoint must be set at an executable line, that is, a code line containing an executable expression.

A breakpoint has the following:

A status, which is active or inactive. An inactive breakpoint is ignored.

A trigger action. When a breakpoint is reached, the trigger action specifies if the breakpoint is to continue as active (enable), or to become inactive (disable), or to be removed (delete).

Optionally an associated condition. A condition is a tuple {Module,Name}. When the breakpoint is reached, Module:Name(Bindings) is called. If it evaluates to true, execution stops. If it evaluates to false, the breakpoint is ignored. Bindings contains the current variable bindings. To retrieve the value for a specified variable use get_binding/2.

By default, a breakpoint is active, has trigger action enable, and has no associated condition. For details about breakpoints, see Breakpoints and Break Dialog Windows in the User's Guide for Debugger.

Summary

Functions

action_at_break(Module, Line, Action)

Sets the trigger action of the breakpoint at Line in Module to Action.

all_breaks()

Gets all breakpoints.

all_breaks(Module)

Gets all breakpoints in module Module.

auto_attach()

Gets how to attach automatically to a process executing code in interpreted modules.

auto_attach/1

Disables auto attach.

auto_attach(Flags, Function)

Sets when and how to attach automatically to a process executing code in interpreted modules.

break(Module, Line)

Creates a breakpoint at Line in Module.

break_in(Module, Name, Arity)

Creates a breakpoint at the first line of every clause of function Module:Name/Arity.

clear()

Clears information about processes executing interpreted code by removing all information about terminated processes.

continue(Pid)

Resumes process execution for Pid.

continue(X, Y, Z)

Resumes process execution for c:pid(X, Y, Z).

del_break_in(Module, Name, Arity)

Deletes the breakpoints at the first line of every clause of function Module:Name/Arity.

delete_break(Module, Line)

Deletes the breakpoint at Line in Module.

disable_break(Module, Line)

Makes the breakpoint at Line in Module inactive.

enable_break(Module, Line)

Makes the breakpoint at Line in Module active.

file(Module)

Returns the source code filename File for an interpreted module Module.

get_binding(Var, Bindings)

Retrieves the binding of Var from Bindings.

i(AbsMods)

Interprets the specified module(s) on the local node.

interpretable(AbsModule)

Checks if a module can be interpreted.

interpreted()

Returns a list with all interpreted modules.

n(AbsModule)

Stops interpreting the specified module on the local node.

ni(AbsMods)

Interprets the specified module(s) on all known nodes.

nn(AbsModule)

Stops interpreting the specified module on all known nodes.

no_break()

Deletes all breakpoints.

no_break(Module)

Deletes all breakpoints in Module.

snapshot()

Gets information about all processes executing interpreted code.

stack_trace()

Gets how to save call frames in the stack.

stack_trace(Flag)

Sets how to save call frames in the stack.

test_at_break(Module, Line, Function)

Sets the conditional test of the breakpoint at Line in Module to Function.

Functions

action_at_break(Module, Line, Action)

-spec action_at_break(Module, Line, Action) -> ok
                         when Module :: module(), Line :: integer(), Action :: enable | disable | delete.

Sets the trigger action of the breakpoint at Line in Module to Action.

all_breaks()

-spec all_breaks() -> [Break]
                    when
                        Break :: {Point, Options},
                        Point :: {Module, Line},
                        Module :: module(),
                        Line :: integer(),
                        Options :: [Status | Trigger | null | Cond],
                        Status :: active | inactive,
                        Trigger :: enable | disable | delete,
                        Cond :: null | Function,
                        Function :: {Module, Name},
                        Name :: atom().

Gets all breakpoints.

all_breaks(Module)

-spec all_breaks(Module) -> [Break]
                    when
                        Break :: {Point, Options},
                        Point :: {Module, Line},
                        Module :: module(),
                        Line :: integer(),
                        Options :: [Status | Trigger | null | Cond],
                        Status :: active | inactive,
                        Trigger :: enable | disable | delete,
                        Cond :: null | Function,
                        Function :: {Module, Name},
                        Name :: atom().

Gets all breakpoints in module Module.

auto_attach()

-spec auto_attach() -> false | {Flags, Function}
                     when
                         Flags :: [init | break | exit],
                         Function :: {Module, Name, Args},
                         Module :: module(),
                         Name :: atom(),
                         Args :: [term()].

Gets how to attach automatically to a process executing code in interpreted modules.

See auto_attach/2 for the meaning of the possible values in Flags.

auto_attach/1

-spec auto_attach(false) -> term().

Disables auto attach.

auto_attach(Flags, Function)

-spec auto_attach(Flags, Function) -> term()
                     when
                         Flags :: [init | break | exit],
                         Function :: {Module, Name, Args},
                         Module :: module(),
                         Name :: atom(),
                         Args :: [term()].

Sets when and how to attach automatically to a process executing code in interpreted modules.

By default when the interpreter is started, automatic attach is disabled.

If Flags is an empty list, automatic attach is disabled.

Otherwise Flags should be a list containing at least one of the following flags:

init - Attach when a process for the first time calls an interpreted function.

break - Attach whenever a process reaches a breakpoint.

exit - Attach when a process terminates.

When the specified event occurs, the function Function is called as:

spawn(Module, Name, [Pid | Args])

Pid is the pid of the process executing interpreted code.

break(Module, Line)

-spec break(Module, Line) -> ok | {error, break_exists} when Module :: module(), Line :: integer().

Creates a breakpoint at Line in Module.

break_in(Module, Name, Arity)

-spec break_in(Module, Name, Arity) -> ok | {error, function_not_found}
                  when Module :: module(), Name :: atom(), Arity :: integer().

Creates a breakpoint at the first line of every clause of function Module:Name/Arity.

clear()

-spec clear() -> ok.

Clears information about processes executing interpreted code by removing all information about terminated processes.

continue(Pid)

-spec continue(Pid :: pid()) -> ok | {error, not_interpreted}.

Resumes process execution for Pid.

continue(X, Y, Z)

-spec continue(X, Y, Z) -> ok | {error, not_interpreted}
                  when X :: integer(), Y :: integer(), Z :: integer().

Resumes process execution for c:pid(X, Y, Z).

del_break_in(Module, Name, Arity)

-spec del_break_in(Module, Name, Arity) -> ok | {error, function_not_found}
                      when Module :: module(), Name :: atom(), Arity :: integer().

Deletes the breakpoints at the first line of every clause of function Module:Name/Arity.

delete_break(Module, Line)

-spec delete_break(Module, Line) -> ok when Module :: module(), Line :: integer().

Deletes the breakpoint at Line in Module.

disable_break(Module, Line)

-spec disable_break(Module, Line) -> ok when Module :: module(), Line :: integer().

Makes the breakpoint at Line in Module inactive.

enable_break(Module, Line)

-spec enable_break(Module, Line) -> ok when Module :: module(), Line :: integer().

Makes the breakpoint at Line in Module active.

file(Module)

-spec file(Module) -> File | {error, not_loaded} when Module :: module(), File :: file:filename_all().

Returns the source code filename File for an interpreted module Module.

get_binding(Var, Bindings)

-spec get_binding(Var, Bindings) -> {value, Value} | unbound
                     when Var :: atom(), Bindings :: term(), Value :: term().

Retrieves the binding of Var from Bindings.

This function is intended to be used by the conditional function of a breakpoint.

i(AbsMods)

-spec i(AbsModules | AbsModule) -> Result
           when
               AbsModules :: [AbsModule, ...],
               AbsModule :: Module | File,
               Module :: module(),
               File :: file:name_all(),
               Result :: AbsModuleResult | AbsModulesResult,
               AbsModuleResult :: {module, Module} | error,
               AbsModulesResult :: ok.

Interprets the specified module(s) on the local node.

A module can be specified by its module name (atom) or filename.

If specified by its module name, the object code Module.beam is searched for in the current path. The source code Module.erl is searched for first in the same directory as the object code, then in an src directory next to it.

If specified by its filename, the filename can include a path and the .erl extension can be omitted. The object code Module.beam is searched for first in the same directory as the source code, then in an ebin directory next to it, and then in the current path.

Note

The interpreter requires both the source code and the object code. The object code must include debug information, that is, only modules compiled with option debug_info can be interpreted.

The functions returns {module,Module} if the module was interpreted, otherwise error is returned.

The argument can also be a list of modules or filenames, in which case the function tries to interpret each module as specified earlier. The function then always returns ok, but prints some information to stdout if a module cannot be interpreted.

interpretable(AbsModule)

-spec interpretable(AbsModule) -> true | {error, Reason}
                       when
                           AbsModule :: Module | File,
                           Module :: module(),
                           File :: file:name_all(),
                           Reason :: no_src | no_beam | no_debug_info | badarg | {app, App},
                           App :: atom().

Checks if a module can be interpreted.

The module can be specified by its module name Module or its source filename File. If specified by a module name, the module is searched for in the code path.

The function returns true if all of the following apply:

Both source code and object code for the module is found.

The module has been compiled with option debug_info set.

The module does not belong to any of the applications Kernel, STDLIB, WX, or Debugger.

The function returns {error,Reason} if the module cannot be interpreted. Reason can have the following values:

no_src - No source code is found. It is assumed that the source code and object code are located either in the same directory, or in src and ebin directories next to each other.

no_beam - No object code is found. It is assumed that the source code and object code are located either in the same directory, or in src and ebin directories next to each other.

no_debug_info - The module has not been compiled with option debug_info set.

badarg - AbsModule is not found. This could be because the specified file does not exist, or because code:which/1 does not return a BEAM filename, which is the case not only for non-existing modules but also for modules that are preloaded or cover-compiled.

{app,App} - App is kernel, stdlib, gs, or debugger if AbsModule belongs to one of these applications.

Notice that the function can return true for a module that is not interpretable the module is marked as sticky or resides in a directory marked as sticky. The reason is that this is not discovered until the interpreter tries to load the module.

interpreted()

-spec interpreted() -> [Module] when Module :: module().

Returns a list with all interpreted modules.

n(AbsModule)

-spec n(AbsModule) -> ok
           when
               AbsModule :: Module | File | [Module | File], Module :: module(), File :: file:name_all().

Stops interpreting the specified module on the local node.

Similar to i/1 and ni/1, a module can be specified by its module name or filename.

ni(AbsMods)

-spec ni(AbsModules | AbsModule) -> Result
            when
                AbsModules :: [AbsModule],
                AbsModule :: Module | File,
                Module :: module(),
                File :: file:name_all(),
                Result :: AbsModuleResult | AbsModulesResult,
                AbsModuleResult :: {module, Module} | error,
                AbsModulesResult :: ok.

Interprets the specified module(s) on all known nodes.

A module can be specified by its module name (atom) or filename.

If specified by its module name, the object code Module.beam is searched for in the current path. The source code Module.erl is searched for first in the same directory as the object code, then in an src directory next to it.

If specified by its filename, the filename can include a path and the .erl extension can be omitted. The object code Module.beam is searched for first in the same directory as the source code, then in an ebin directory next to it, and then in the current path.

Note

The interpreter requires both the source code and the object code. The object code must include debug information, that is, only modules compiled with option debug_info can be interpreted.

The functions returns {module,Module} if the module was interpreted, otherwise error is returned.

The argument can also be a list of modules or filenames, in which case the function tries to interpret each module as specified earlier. The function then always returns ok, but prints some information to stdout if a module cannot be interpreted.

nn(AbsModule)

-spec nn(AbsModule) -> ok
            when
                AbsModule :: Module | File | [Module | File],
                Module :: module(),
                File :: file:name_all().

Stops interpreting the specified module on all known nodes.

Similar to i/1 and ni/1, a module can be specified by its module name or filename.

no_break()

-spec no_break() -> ok.

Deletes all breakpoints.

no_break(Module)

-spec no_break(Module :: term()) -> ok.

Deletes all breakpoints in Module.

snapshot()

-spec snapshot() -> [Snapshot]
                  when
                      Snapshot :: {Pid, Function, Status, Info},
                      Pid :: pid(),
                      Function :: {Module, Name, Args},
                      Module :: module(),
                      Name :: atom(),
                      Args :: [term()],
                      Status :: idle | running | waiting | break | exit | no_conn,
                      Info :: {} | {Module, Line} | ExitReason,
                      Line :: integer(),
                      ExitReason :: term().

Gets information about all processes executing interpreted code.

Pid - Process identifier.

Function - First interpreted function called by the process.

Status - Current status of the process.

Info - More information.

Status is one of the following:

idle - The process is no longer executing interpreted code. Info is {}.

running - The process is running. Info is {}.

waiting - The process is waiting at a receive. Info is {}.

break - Process execution is stopped, normally at a breakpoint. Info is {Module,Line}.

exit - The process is terminated. Info is ExitReason.

no_conn - The connection is down to the node where the process is running. Info is {}.

stack_trace()

-spec stack_trace() -> Flag when Flag :: all | no_tail | false.

Gets how to save call frames in the stack.

See stack_trace/1 for the meaning of Flag.

stack_trace(Flag)

-spec stack_trace(Flag) -> term() when Flag :: all | no_tail | false.

Sets how to save call frames in the stack.

Saving call frames makes it possible to inspect the call chain of a process, and is also used to emulate the stack trace if an error (an exception of class error) occurs. The following flags can be specified:

all - Save information about all current calls, that is, function calls that have not yet returned a value.

no_tail - Save information about current calls, but discard previous information when a tail-recursive call is made. This option consumes less memory and can be necessary to use for processes with long lifetimes and many tail-recursive calls. This is the default.

false - Save no information about current calls.

test_at_break(Module, Line, Function)

-spec test_at_break(Module, Line, Function) -> ok
                       when
                           Module :: module(),
                           Line :: integer(),
                           Function :: {Module, Name},
                           Name :: atom().

Sets the conditional test of the breakpoint at Line in Module to Function.

Function Function must fulfill the requirements specified in section Breakpoints.