From 2a43b90eadcbce8763c84d2692e89f5e7a1ec150 Mon Sep 17 00:00:00 2001
From: xsipewe 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.
- To use Debugger, the basic steps are as follows: The Erlang interpreter can also be accessed via the interface
- module Step 1. Start Debugger by calling
+ 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. The Step 2. Select Module > Interpret... in the
+ Monitor window. Start Debugger by calling The 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
- choosing Module->Interpret... in the Monitor window and
- then selecting the appropriate modules from the
- Step 3. Select the appropriate modules from the Interpret
+ Dialog window. Only modules compiled with the option Only modules compiled with option When a module is interpreted, it can be viewed in a
- 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 choosing Process->Attach. Attaching to a process will result in a
- Step 4. In the Monitor window, select
+ Module > the module to be interpreted > View. The contents of the source file is displayed in the
+ Step 5. Set the
+ 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
+ Step 8. From the Attach Process window, you can control
+ the process execution, inspect variable values, set breakpoints,
+ and so on. 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.
+ 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. -
+Breakpoints are created and deleted using the Break menu of + either the Monitor window, View Module window, or 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
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
In the example below, lines number 2, 4, 6, 8 and 11 are - executable lines:
+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 @@ -141,17 +136,15 @@Status and Trigger Action A breakpoint can be either active or - inactive. Inactive breakpoints are ignored.
- -Each breakpoint has a trigger action which specifies - what should happen when a process has reached it (and stopped): -
--
- enable Breakpoint should remain active (default). -
-- disable Breakpoint should be made inactive. -
-- delete Breakpoint should be deleted.
+ 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.
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.
+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 or Attach Process window.
+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.
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 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
-
Right-clicking the Module entry will open a popup menu from - which the appropriate module can be selected.
+Right-click the Module entry to open a popup menu from + which the appropriate module can be selected.
-Example: A conditional breakpoint calling
-
Example:
+ +A conditional breakpoint calling
+
Extract from
-5. fac(0) -> 1; -6. fac(N) when N > 0, is_integer(N) -> N * fac(N-1).+5. fac(0) -> 1; +6. fac(N) when N > 0, is_integer(N) -> N * fac(N-1).
Definition of
@@ -228,18 +223,18 @@ c_break(Bindings) ->Function Breakpoints A function breakpoint is a set of line breakpoints, one at - the first line of each clause in the given function.
+ the first line of each clause in the specified function.- -The Function Break Dialog Window. +Function Break Dialog Window Right-clicking the Module entry will open a popup menu from - which the appropriate module can be selected.
+To open a popup menu from which the appropriate module can be + selected, right-click the Module entry.
-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.
+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,.
The Erlang emulator keeps track of a stack trace, information about recent function calls. This information is - used, for example, if an error occurs:
+ used if an error occurs, for example:1> catch a+1. {'EXIT',{badarith,[{erlang,'+',[a,1],[]}, @@ -259,602 +254,597 @@ c_break(Bindings) -> {shell,eval_exprs,7,[{file,"shell.erl"},{line,629}]}, {shell,eval_loop,3,[{file,"shell.erl"},{line,614}]}]}}-
See the Erlang Reference Manual,
-
For details about the stack trace, see section
+
The Debugger emulates the stack trace by keeping track of recently +
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).
+ 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 of
-
By default, the Debugger only saves information about recursive +
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').
+ a value (option Stack On, No Tail).Sometimes, however, it can be useful to save all calls, even - tail-recursive calls. That can be done with the 'Stack On, Tail' - option. Note that this option will consume more memory and slow - down execution of interpreted functions when there are many - tail-recursive calls. -
- -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
To turn off the Debugger stack trace facility, select option + Stack Off.
+ +If an error occurs, the stack trace becomes empty in this + case.
+For information about how to change the stack trace option, see
+ section
The Monitor window is the main window of Debugger and displays the + following:
-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.
+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 buttons, Stack Trace label, Back Trace Size
- label, and Strings button show some options set, see
-
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
+
The process identifier.
The first call to an interpreted function by this
- process. (
The registered name, if any. If a registered name does - not show up, it may be that the Debugger received - information about the process before the name had been - registered. Try selecting Edit->Refresh.
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.
The current status, one of the following:
The interpreted function call has returned a value, - and the process is no longer executing interpreted code. -
The interpreted function call has returned a value, and + the process is no longer executing interpreted code.
The process is running.
The process is waiting in a
The process is stopped at a breakpoint.
The process has terminated.
There is no connection to the node where - the process is located.
Additional information, if any. If the process is
- stopped at a breakpoint, the field contains information
- about the location
More information, if any. If the process is
+ stopped at a breakpoint, the field contains information
+ about the location
Try to load and restore Debugger settings from a file - previously saved using Save Settings..., see below. - Any errors are silently ignored. - Note: Settings saved by Erlang R16B01 or later - cannot be read by Erlang R16B or earlier.
+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 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.
+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.
Stop Debugger.
Stops Debugger.
Update information about debugged processes. Removes - information about all terminated processes from the window, - and also closes all Attach Process windows for terminated - processes.
Updates information about debugged processes. Information + about all terminated processes are removed from the window. All + Attach Process windows for terminated processes are closed.
Terminate all processes listed in the window using
-
Terminates all processes listed in the window using
+
Open the
Opens the
+
Stop interpreting all modules. Processes executing in - interpreted modules will terminate.
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:
+ the Module menu, with the following submenu:Stop interpreting the selected module. Processes - executing in this module will terminate.
Stops interpreting the selected module. Processes + executing in this module terminate.
Open a
Opens a
+
The following menu items apply to the currently selected
- process, provided it is stopped at a breakpoint. See the chapter
- about the
The following menu items apply to the currently selected - process.
+ process:Attach to the process and open a
-
Attaches to the process and open an
+
Terminate the process using
Terminates the process using
The items in this menu are used to create and delete
- breakpoints.
- See the
The items in this menu are used to create and delete breakpoints.
+ For details, see section
+
Set a line breakpoint.
Sets a line breakpoint.
Set a conditional breakpoint.
Sets a conditional breakpoint.
Set a function breakpoint.
Sets a function breakpoint.
Enable all breakpoints.
Enables all breakpoints.
Disable all breakpoints.
Disables all breakpoints.
Remove all breakpoints.
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.
+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.
Set which areas should be visible in
- an
Sets the areas to be visible in an
+
Set at which events a debugged process should be - automatically attached to. Affects existing debugged - processes.
-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.
Set stack trace option, see section
+ Sets the stack trace option, see section
-
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.
Set which integer lists should be printed as strings. - Does not affect already existing debugged processes.
-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
Set how many call frames should be fetched when - inspecting the call stack from the Attach Process window. - Does not affect already existing Attach Process windows.
+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.
Contains a menu item for each open Debugger window. Selecting - one of the items will raise the corresponding window.
+ one of the items raises the corresponding window.View the Debugger documentation. Currently this - function requires a web browser to be up and running.
Shows the Debugger documentation. This function requires a + web browser.
The interpret dialog module is used for selecting which modules
- to interpret. Initially, the window shows the modules (
The Interpret Modules window is used for selecting which modules
+ to interpret. Initially, the window displays the modules (
Interpretable modules are modules for which a BEAM file, compiled
- with the option
Interpretable modules are modules for which a
Modules, for which the above requirements are not fulfilled, are - not interpretable and are therefore displayed within parentheses. -
+Modules for which these requirements are not fulfilled are + not interpretable and are therefore displayed within parentheses.
-The
Option
An example of how to compile code with debug information using
-
-
+% 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 have the type
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
Pressing All will interpret all displayed modules in - the chosen directory.
+To interpret all displayed modules in the chosen directory, click + All.
-Pressing Done will close the window.
+To close the window, click Done.
When the Debugger is started in global mode (which is
- the default, see
-
When Debugger is started in global mode (which is the default, see
+
From an Attach Process window the user can interact with a +
From an Attach Process window, you 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. -
+ been attached to. Notice that when attaching to a process, its + execution is automatically stopped.The window is divided into five parts:
-The Code area, showing 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 above,
- the execution has been stopped at line 6, before
- the execution of
Active breakpoints are shown in red, while inactive - breakpoints are shown in blue.
+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
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, + reference, binary, or port values cannot be edited.
The Trace area, showing a trace output for the process. -
+ +The Trace area, which displays a trace output for the + process.
Function call, where
Function return value
.The message
The message
Waiting in a
Waiting in a
Also the back trace, a summary of the current function calls - on the stack, is displayed in the Trace area.
+The Trace area also displays Back Trace, a summary of the + current function calls on the stack.
It is configurable using the Options menu which areas should - be shown or hidden. By default, all areas except the Trace area - are shown.
+Using the Options menu, you can set which areas to be + displayed. By default, all areas except the Trace area are displayed.
Close this window and detach from the process.
+Closes this window and detach from the process.
Go to a specified line number.
Goes to a specified line number.
Search for a specified string.
Searches for a specified string.
Execute the current line of code, stepping into any
+ Executes the current code line, stepping into any
(interpreted) function calls. Execute the current line of code and stop at the next
+ Executes the current code line and stop at the next
line. Continue the execution. Continues the execution. Continue the execution until the current function
+ Continues the execution until the current function
returns. Skip the current line of code and stop at the next
+ Skips the current code line and stop at the next
line. If used on the last line in a function body,
- the function will return Simulate a timeout when executing a
+ Simulates a time-out when executing a
Stop the execution of a running process, that is, make
- the process stop as at a breakpoint. The command will take
+ 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. Make sure the current location of the execution is
+ Verifies that the current location of the execution is
visible in the code area. Terminate the process using Terminates the process using Inspect the message queue of the process. The queue is
- printed in the evaluator area. Inspects the message queue of the process. The queue is
+ displayed in the Evaluator area. Display 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'. 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. Inspect the previous function call on the stack,
+ Inspects the previous function call on the stack,
showing the location and variable bindings. Inspect the next function call on the stack, showing
+ Inspects the next function call on the stack, showing
the location and variable bindings.
Set which areas should be visible. Does not affect - other Attach Process windows.
-Sets which areas are to be visible. Does not affect + other Attach Process windows.
Same as in
Same as in the
Same as in
Same as in the
Set how many call frames should be fetched when
+ Sets how many call frames are to be fetched when
inspecting the call stack. Does not affect other Attach
- Process windows.
The Break, Windows and Help menus look the same as in
- the Monitor window, see the chapter
-
The Break, Windows, and Help menus
+ are the same as in the
+
The View Module window shows the contents of an interpreted +
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 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.
+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.
The File and Edit menus look the same as in the Attach Process
- window, see the chapter
The File and Edit menus are the same as in the
+
The Break, Windows and Help menus look the same as in
- the Monitor window, see the chapter
-
The Break, Windows, and Help menus
+ are the same as in the
+
Execution of interpreted code is naturally slower than for - regularly compiled modules. Using the Debugger also increases + 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 may +
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. Timeouts can then occur in other processes that + 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 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 + 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.
@@ -888,22 +878,24 @@ c_break(Bindings) ->By using
By using
+
debugger:start(local | global)-
If no argument is provided, Debugger is started in global mode. -
+ +If no argument is provided, Debugger starts 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 + at other nodes executing interpreted code are automatically + displayed 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 - interfere with each other leading to inconsistent behaviour.
+It is possible, but definitely 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.