From 2a43b90eadcbce8763c84d2692e89f5e7a1ec150 Mon Sep 17 00:00:00 2001 From: xsipewe Date: Mon, 14 Dec 2015 10:01:25 +0100 Subject: debugger: Editorial changes in documentation --- lib/debugger/doc/src/book.xml | 1 - lib/debugger/doc/src/debugger.xml | 26 +- lib/debugger/doc/src/debugger_chapter.xml | 858 +++++++++++++++--------------- lib/debugger/doc/src/i.xml | 138 +++-- lib/debugger/doc/src/int.xml | 334 ++++++------ lib/debugger/doc/src/introduction.xml | 63 +++ lib/debugger/doc/src/part.xml | 12 +- lib/debugger/doc/src/ref_man.xml | 7 +- 8 files changed, 743 insertions(+), 696 deletions(-) create mode 100644 lib/debugger/doc/src/introduction.xml (limited to 'lib/debugger/doc') diff --git a/lib/debugger/doc/src/book.xml b/lib/debugger/doc/src/book.xml index 071a04eb61..5424ef2c04 100644 --- a/lib/debugger/doc/src/book.xml +++ b/lib/debugger/doc/src/book.xml @@ -47,4 +47,3 @@ - diff --git a/lib/debugger/doc/src/debugger.xml b/lib/debugger/doc/src/debugger.xml index 15d498d5ae..1ecdbcd064 100644 --- a/lib/debugger/doc/src/debugger.xml +++ b/lib/debugger/doc/src/debugger.xml @@ -4,7 +4,7 @@
- 20022013 + 20022016 Ericsson AB. All Rights Reserved. @@ -29,7 +29,7 @@
debugger - Erlang Debugger + Erlang Debugger.

Erlang Debugger for debugging and testing of Erlang programs.

 @@ -48,14 +48,14 @@

Starts Debugger.

-

If given a file name as argument, Debugger will try to load - its settings from this file. Refer to Debugger User's Guide - for more information about settings.

+

If a filename is specified as argument, Debugger tries to load + its settings from this file. For details about settings, see + the User's Guide.

-

If given local as argument, Debugger will interpret - code only at the current node. If given global as - argument, Debugger will interpret code at all known nodes, - this is the default.

+

If local is specified as argument, Debugger interprets + code only at the current node. If global is specified as + argument, Debugger interprets code at all known nodes, this + is the default.

 @@ -67,11 +67,9 @@ Args = [term()] -

This function can be used to debug a single process. - The module Module is interpreted and - apply(Module,Name,Args) is called. This will open an - Attach Process window, refer to Debugger User's Guide for - more information.

+

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.

 diff --git a/lib/debugger/doc/src/debugger_chapter.xml b/lib/debugger/doc/src/debugger_chapter.xml index 98fe4ae377..45dfdb3776 100644 --- a/lib/debugger/doc/src/debugger_chapter.xml +++ b/lib/debugger/doc/src/debugger_chapter.xml @@ -4,7 +4,7 @@
- 19972013 + 19972016 Ericsson AB. All Rights Reserved. @@ -31,97 +31,92 @@
- Introduction + Getting Started -

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 int, see int(3). -

+

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

-

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 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:

-
- Getting Started with Debugger +

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

-

Start Debugger by calling debugger:start(). It will start - the Monitor window showing - information about all debugged processes, interpreted modules and - selected options.

+

The Interpret Modules window + is displayed.

-

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 - Interpret Dialog window. -

+

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

-

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

+

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

 -

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

- -

Now the program that should be debugged can be started. This is - done the normal way from the Erlang shell. All processes executing - code in interpreted modules will be displayed in the Monitor - window. It is possible to attach to 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 - Attach Process window being - opened for this process. From the Attach Process window, it is - possible to control the process execution, inspect variable - values, set breakpoints etc.

+

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 Dialogue Windows + 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.

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

Executable Lines -

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

+

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 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.
@@ -161,54 +154,56 @@

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

- The Line Break Dialog Window. + Line Break Dialog Window -

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.

Conditional Breakpoints

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

+ the 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) will be evaluated. If and - only if this function call returns true, the process - will stop. If the function call returns false, - the breakpoint will be silently ignored.

- -

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

+ 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}.

- The Conditional Break Dialog Window. + Conditional Break Dialog Window -

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 - c_test:c_break/1 is added at line 6 in the module +

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, and when N is equal to 3 it returns true, - and the process stops.

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

Definition of c_test:c_break/1:

@@ -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,.
@@ -249,7 +244,7 @@ c_break(Bindings) ->

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, - - Errors and Error Handling, - for more information about the stack trace.

+

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

-

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

+ calls, using the Up and Down buttons in the + Attach Process window.

-

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 the Monitor - Window for information about how to change the stack - trace option.

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

+ + +

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.

- The Monitor Window + Monitor Window + +

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 Monitor Window. + Monitor Window -

The Auto Attach buttons, Stack Trace label, Back Trace Size - label, and Strings button show some options set, see - Options Menu for further - information about these options.

+

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)

 + process. (Module:Function/Arity)

Name -

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.

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

+

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.

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

 + the process is located.

 Information -

Additional information, if any. If the process is - stopped at a breakpoint, the field contains information - about the location {Module,Line}. If the process has - terminated, the field contains the exit reason.

 +

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.
- The File Menu - + File Menu + Load Settings... - -

Try to load and restore Debugger settings from a file - previously saved using Save Settings..., see below. - Any errors are silently ignored. - 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 Settings... -

Save Debugger settings to a file. The settings include - the set of interpreted files, breakpoints, and the selected - options. The settings can be restored in a later Debugger - session using Load Settings..., see above. - Any errors are silently ignored.

+

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 -

Stop Debugger.

 +

Stops Debugger.
- The Edit Menu + Edit Menu Refresh -

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.

 Kill All -

Terminate all processes listed in the window using - exit(Pid,kill).

 +

Terminates all processes listed in the window using + exit(Pid,kill).
- The Module Menu + Module Menu Interpret... -

Open the Interpret Dialog - window where new modules to be interpreted can - be specified.

 - +

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

 + Delete All -

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:

Delete -

Stop interpreting the selected module. Processes - executing in this module will terminate.

 - +

Stops interpreting the selected module. Processes + executing in this module terminate.

 + View -

Open a View Module - window showing the contents of the selected - module.

 +

Opens a + View Module window, displaying the + contents of the selected module.
- The Process Menu + Process Menu

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

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

+ process:

Attach -

Attach to the process and open a - Attach Process window. -

- +

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

 + Kill -

Terminate the process using exit(Pid,kill).

- +

Terminates the process using exit(Pid,kill).
-
- The Break Menu -

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

+
+ Break Menu +

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

+ Line Break... -

Set a line breakpoint.

 +

Sets a line breakpoint.

 Conditional Break... -

Set a conditional breakpoint.

 +

Sets a conditional breakpoint.

 Function Break... -

Set a function breakpoint.

 +

Sets a function breakpoint.

 Enable All -

Enable all breakpoints.

 +

Enables all breakpoints.

 Disable All -

Disable all breakpoints.

 +

Disables all breakpoints.

 - Delete All -

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

+

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.

- The Options Menu + Options Menu Trace Window -

Set which areas should be visible in - an Attach Process - window. Does not affect already existing - Attach Process windows.

+

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

 Auto Attach -

Set at which events a debugged process should be - automatically attached to. 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. +

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 -

Set stack trace option, see section +

Sets the stack trace option, see section Stack Trace. Does not - affect already existing debugged processes.

- - Stack On, Tail - save information about all - current calls. - Stack On, No Tail - save information about + 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 - do not save any information about - current calls. + recursive call is made.

 +

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

 Strings -

Set which integer lists should be printed as strings. - Does not affect already existing debugged processes.

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

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

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.
- The Windows Menu + Windows Menu

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.

- The Help Menu + Help Menu Help -

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 Window + Interpret Modules Window -

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

+

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 the option debug_info set, can be found in the same +

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 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 debug_info option causes debug information or - abstract code to be added to the BEAM file. This will - increase the size of the file, and also makes it possible to +

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

- + 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).

- + the Erlang shell:

+ 
+4> c(module, debug_info).
+ - The Interpret Dialog Window. + Interpret Modules Window -

Browse the file hierarchy and interpret the appropriate modules - by selecting a module name and pressing Choose (or - carriage return), or by double clicking the module name. - Interpreted modules have the type erl src. -

+

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.

-

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 - debugger:start/0), - modules added (or deleted) for interpretation will be added (or - deleted) on all known Erlang nodes.

+

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.
- The Attach Process Window + Attach Process Window -

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 Attach Process Window. + Attach Process Window -

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 fac/1.

-

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 -->. 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 the user can evaluate functions - within the context of the debugged process, provided that - process execution has been stopped. - The Bindings area, showing all variables bindings. - Clicking on a variable name will result in the value being - displayed in the Evaluator area. - Double-clicking on a variable name will open a window where - the variable value may be edited. Note however that pid, - reference, binary or port values can not be edited. + +

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.

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

Function call, where N is the call level and + L the line number.

 - -- (N) - Function return value. + -- (N) +

Function return value

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

The message Msg is sent to process + Pid.

 - - The message Msg is received. + +

The message Msg is received.

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

Waiting in a receive.

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

Waiting in a receive...after.

 + -

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.

- The File Menu + File Menu Close -

Close this window and detach from the process.

+

Closes this window and detach from the process.
- The Edit Menu + Edit Menu Go to line... -

Go to a specified line number.

 +

Goes to a specified line number.

 Search... -

Search for a specified string.

 +

Searches for a specified string.
- The Process Menu + Process Menu Step -

Execute the current line of code, stepping into any +

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

 Next -

Execute the current line of code and stop at the next +

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

 Continue -

Continue the execution.

 +

Continues the execution.

 Finish -

Continue the execution until the current function +

Continues the execution until the current function returns.

 Skip -

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

 + the function returns skipped.

Time Out -

Simulate a timeout when executing a +

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

 Stop -

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.

 Where -

Make sure the current location of the execution is +

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

 Kill -

Terminate the process using exit(Pid,kill).

+

Terminates the process using exit(Pid,kill).

 Messages -

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.

 Back Trace -

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.

 Up -

Inspect the previous function call on the stack, +

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

 Down -

Inspect the next function call on the stack, showing +

Inspects the next function call on the stack, showing the location and variable bindings.
- The Options Menu + Options Menu Trace Window -

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.

 Stack Trace -

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

- +

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.

- +

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

 Back Trace Size... -

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.

- + Process windows.
- Break, Windows and Help Menus + Break, Windows, and Help Menus -

The Break, Windows and Help menus look the same as in - the Monitor window, see the chapter - The Monitor Window, except - that the Breaks menu apply to the local breakpoints only.

+

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

- The View Module Window + View Module Window -

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 View Module Window. + View Module Window

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

-

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

+

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 look the same as in the Attach Process - window, see the chapter The Attach - Process Window.

+

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

- Break, Windows and Help Menus + Break, Windows, and Help Menus -

The Break, Windows and Help menus look the same as in - the Monitor window, see the chapter - The Monitor Window, except - that the Breaks menu apply to the local breakpoints only.

+

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

@@ -862,14 +852,14 @@ c_break(Bindings) -> Performance

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.

@@ -878,8 +868,8 @@ c_break(Bindings) ->

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) ->
Debugging Remote Nodes -

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

+

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

 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.

 diff --git a/lib/debugger/doc/src/i.xml b/lib/debugger/doc/src/i.xml index 9ceba94b44..db89f23494 100644 --- a/lib/debugger/doc/src/i.xml +++ b/lib/debugger/doc/src/i.xml @@ -4,7 +4,7 @@
- 19982013 + 19982016 Ericsson AB. All Rights Reserved. @@ -29,35 +29,36 @@
i - Debugger/Interpreter Interface + Debugger/Interpreter Interface. -

The module i provides short forms for some of +

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

+ 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 giving the corresponding process identity only. By default, an attachment - window pops up. Processes at other Erlang nodes can be + window is displayed. Processes at other Erlang nodes can be attached manually or automatically.

-

By preference, these functions can be included in the module - shell_default. By default, they are.

+

By preference, these functions can be included in module + stdlib:shell_default. + By default, they are included in that module.

 im() -> pid() - Start a graphical monitor + Start a graphical monitor.

Starts a new graphical monitor. This is the Monitor window, - the main window of the Debugger. All of the Debugger and + the main window of Debugger. All the Debugger and interpreter functionality is accessed from the Monitor window. - The Monitor window displays the status of all processes that - have been/are executing interpreted modules.

+ This window displays the status of all processes that + have been or are executing interpreted modules.

 @@ -66,7 +67,7 @@ ii(AbsModule) -> {module, Module} | error ini(AbsModules) -> ok ini(AbsModule) -> {module, Module} | error - Interpret a module + Interpret a module. AbsModules = [AbsModule] AbsModule = Module | File @@ -85,7 +86,7 @@ iq(AbsModule) -> ok inq(AbsModule) -> ok - Stop interpreting a module + Stop interpreting a module. AbsModule = Module | File  Module = atom() @@ -110,28 +111,27 @@ ip() -> ok - Make a printout of the current status of all interpreted - processes + Print the current status of all interpreted + processes. -

Makes a printout of the current status of all interpreted - processes.

+

Prints the current status of all interpreted processes.

 ic() -> ok Clear information about processes executing interpreted - code + code.

Clears information about processes executing interpreted code - byt removing all information about terminated processes.

+ by removing all information about terminated processes.

 iaa(Flags) -> true iaa(Flags, Function) -> true - Set when and how to attach to a process + Set when and how to attach to a process. Flags = [init | break | exit] Function = {Module,Name,Args} @@ -139,42 +139,41 @@  Args = [term()] -

Sets when and how to automatically attach to a debugged - process, see +

Sets when and how to attach to a debugged process + automatically, see int:auto_attach/2. Function defaults to the standard function used by - the Debugger.

+ Debugger.

 ist(Flag) -> true - Set how to save call frames + Set how to save call frames. Flag = all | no_tail | false

Sets how to save call frames in the stack, see - int:stack_trace/1. -

+ int:stack_trace/1.

 ia(Pid) -> ok | no_proc - Attach to a process + Attache to a process. Pid = pid() -

Attaches to the debugged process Pid. A Debugger +

Attaches to the debugged process Pid. An Attach Process window is opened for the process.

 ia(X,Y,Z) -> ok | no_proc - Attach to a process + Attache to a process. X = Y = Z = int() @@ -186,7 +185,7 @@ ia(Pid, Function) -> ok | no_proc - Attach to a process + Attache to a process. Pid = pid() Function = {Module,Name} @@ -194,14 +193,14 @@

Attaches to the debugged process Pid. The interpreter - will call spawn(Module, Name, [Pid]) (and ignore + calls spawn(Module, Name, [Pid]) (and ignores the result).

 ia(X,Y,Z, Function) -> ok | no_proc - Attach to a process + Attache to a process. X = Y = Z = int() Function = {Module,Name} @@ -211,15 +210,15 @@

Same as 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 - int:attached(Pid) function and to be able to handle - messages from the interpreter, see dbg_wx_trace.erl for - an example.

+ function int:attached(Pid) and to be able to handle + messages from the interpreter. For an example, see + dbg_wx_trace.erl.

 ib(Module, Line) -> ok | {error, break_exists} - Create a breakpoint + Create a breakpoint. Module = atom() Line = int() @@ -232,20 +231,20 @@ ib(Module, Name, Arity) -> ok | {error, function_not_found} - Create breakpoints in the specified function + Create breakpoints in the specified function. Module = Name = atom() Arity = int()

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

+ function Module:Name/Arity.

 ir() -> ok - Delete all breakpoints + Delete all breakpoints.

Deletes all breakpoints.

 @@ -253,7 +252,7 @@ ir(Module) -> ok - Delete all breakpoints in a module + Delete all breakpoints in a module. Module = atom() @@ -264,61 +263,57 @@ ir(Module, Line) -> ok - Delete a breakpoint + Delete a breakpoint. Module = atom() Line = int() -

Deletes the breakpoint located at Line in - Module.

+

Deletes the breakpoint at Line in Module.

 ir(Module, Name, Arity) -> ok | {error, function_not_found} - Delete breakpoints from the specified function - + Delete breakpoints from the specified function. Module = Name = atom() Arity = int()

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

+ function Module:Name/Arity.

 ibd(Module, Line) -> ok - Make a breakpoint inactive + Make a breakpoint inactive. Module = atom() Line = int() -

Makes the breakpoint at Line in Module - inactive.

+

Makes the breakpoint at Line in Module inactive.

 ibe(Module, Line) -> ok - Make a breakpoint active + Make a breakpoint active. Module = atom() Line = int() -

Makes the breakpoint at Line in Module active. -

+

Makes the breakpoint at Line in Module active.

 iba(Module, Line, Action) -> ok - Set the trigger action of a breakpoint + Set the trigger action of a breakpoint. Module = atom() Line = int() @@ -332,7 +327,7 @@ ibc(Module, Line, Function) -> ok - Set the conditional test of a breakpoint + Set the conditional test of a breakpoint. Module = atom() Line = int() @@ -346,62 +341,53 @@

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). Use - int:get_binding(Var, Bindings) to retrieve the value - of a variable Var.

+ true (break) or false (do not break). + To retrieve the value of a variable Var, use + int:get_binding(Var, Bindings).

 ipb() -> ok - Make a printout of all existing breakpoints + Print all existing breakpoints. -

Makes a printout of all existing breakpoints.

+

Prints all existing breakpoints.

 ipb(Module) -> ok - Make a printout of all breakpoints in a module - + Print all existing breakpoints in a module. Module = atom() -

Makes a printout of all existing breakpoints in - Module.

+

Prints all existing breakpoints in Module.

 iv() -> atom() - Current version number of the interpreter + Return the current version number of the interpreter. +

Returns the current version number of the interpreter. - The same as the version number of the Debugger application. -

+ Same as the version number of the Debugger application.

 help() -> ok - Print help text + Print help text.

Prints help text.

 -
- Usage - -

Refer to the Debugger User's Guide for information about - the Debugger.

-
-
See Also -

int(3)

+

int(3)

 diff --git a/lib/debugger/doc/src/int.xml b/lib/debugger/doc/src/int.xml index ea21d04a07..31e9dfe923 100644 --- a/lib/debugger/doc/src/int.xml +++ b/lib/debugger/doc/src/int.xml @@ -4,7 +4,7 @@
- 19982013 + 19982016 Ericsson AB. All Rights Reserved. @@ -29,16 +29,16 @@
int - Interpreter Interface + Interpreter Interface.

The Erlang interpreter provides mechanisms for breakpoints and - stepwise execution of code. It is mainly intended to be used by - the Debugger, see Debugger User's Guide and - debugger(3).

+ stepwise execution of code. It is primarily intended to be used by + Debugger, see the User's Guide and + debugger(3).

-

From the shell, it is possible to:

- - Specify which modules should be interpreted. +

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. @@ -48,45 +48,48 @@

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 via a third process, called the meta process. - It is possible to implement your own attached process. See + 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 GS - applications, which means modules belonging to any of these - applications are not allowed to be interpreted as it could lead +

The interpreter depends on the Kernel, STDLIB, and + GS 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 itself.

+ 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 - will stop. This means that that a breakpoint must be set at an - executable line, that is, a line of code containing an executable + stops. This means that a breakpoint must be set at an + executable line, that is, a code line containing an executable expression.

-

A breakpoint have a status, a trigger action and may have a - condition associated with it. The status is either active - or inactive. An inactive breakpoint is ignored. When a - breakpoint is reached, the trigger action specifies if - the breakpoint should continue to be active (enable), if - it should become inactive (disable), or if it should be - removed (delete). A condition is a tuple - {Module,Name}. When the breakpoint is reached, - Module:Name(Bindings) is called. If this evaluates to - true, execution will stop. If this evaluates to - false, the breakpoint is ignored. Bindings contains - the current variable bindings, use get_binding to retrieve - the value for a given variable.

+

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

By default, a breakpoint is active, has trigger action - enable and has no condition associated with it. For more - detailed information about breakpoints, refer to Debugger User's - Guide.

+ enable, and has no associated condition. For details + about breakpoints, see the User's Guide.

@@ -95,7 +98,7 @@ i(AbsModules) -> ok ni(AbsModule) -> {module,Module} | error ni(AbsModules) -> ok - Interpret a module + Interpret a module. AbsModules = [AbsModule] AbsModule = Module | File | [Module | File] @@ -107,41 +110,43 @@ the module only at the current node. ni/1 interprets the module at all known nodes.

-

A module may be given by its module name (atom) or by its - file name. If given by its module name, the object code +

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 a src + the same directory as the object code, then in an src directory next to it.

-

If given by its file name, the file name may include a path - and the .erl extension may be omitted. The object code +

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.

-

The interpreter needs both the source code and the object - code, and the object code must include debug - information. That is, only modules compiled with the option +

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 set can be interpreted.

The functions returns {module,Module} if the module - was interpreted, or error if it was not.

+ was interpreted, otherwise error is returned.

-

The argument may also be a list of modules/file names, in +

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

+ specified earlier. The function then always returns ok, + but prints some information to stdout if a module + cannot be interpreted.

n(AbsModule) -> ok nn(AbsModule) -> ok - Stop interpreting a module + Stop interpreting a module. AbsModule = Module | File | [Module | File]  Module = atom() @@ -152,14 +157,14 @@ interpreting the module only at the current node. nn/1 stops interpreting the module at all known nodes.

-

As for i/1 and ni/1, a module may be given by - either its module name or its file name.

+

As for i/1 and ni/1, a module can be specified by + its module name or filename.

 interpreted() -> [Module] - Get all interpreted modules + Get all interpreted modules. Module = atom() @@ -170,20 +175,20 @@ file(Module) -> File | {error,not_loaded} - Get the file name for an interpreted module + Get the filename for an interpreted module. Module = atom() File = string() -

Returns the source code file name File for an +

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

 interpretable(AbsModule) -> true | {error,Reason} - Check if a module is possible to interpret + Check if a module can be interpreted. AbsModule = Module | File  Module = atom() @@ -193,45 +198,59 @@  App = atom() -

Checks if a module is possible to interpret. The module can - be given by its module name Module or its source file - name File. If given by a module name, the module is - searched for in the code path.

- -

The function returns true if both source code and - object code for the module is found, the module has been - compiled with the option debug_info set and does not - belong to any of the applications Kernel, STDLIB, GS or - Debugger itself.

- -

The function returns {error,Reason} if the module for - some reason is not possible to interpret.

- -

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

- -

Reason is no_debug_info if the module has not - been compiled with the option debug_info set.

- -

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

- -

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

- -

Note that the function can return true for a module - which in fact is not interpretable in the case where +

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, GS, 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 in fact is not interpretable in the case where the module is marked as sticky or resides in a directory - marked as sticky, as this is not discovered until - the interpreter actually tries to load the module.

+ marked as sticky. The reason is that this is not discovered + until the interpreter tries to load the module.

 @@ -239,7 +258,7 @@ auto_attach() -> false | {Flags,Function} auto_attach(false) auto_attach(Flags, Function) - Get/set when and how to attach to a process + Get and set when and how to attach to a process. Flags = [init | break | exit] Function = {Module,Name,Args} @@ -247,24 +266,24 @@  Args = [term()] -

Gets and sets when and how to automatically attach to a +

Gets and sets when and how to attach automatically to a process executing code in interpreted modules. false - means never automatically attach, this is the default. + means never attach automatically, this is the default. Otherwise automatic attach is defined by a list of flags and - a function. The following flags may be specified:

- - init - attach when a process for the very first + a function. The following flags can be specified:

+ + init - Attach when a process for the first time calls an interpreted function. - break - attach whenever a process reaches a + break - Attach whenever a process reaches a breakpoint. - exit - attach when a process terminates. + exit - Attach when a process terminates.

When the specified event occurs, the function Function - will be called as:

+ is called as:

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

Pid is the pid of the process executing interpreted code.

 @@ -273,7 +292,7 @@ spawn(Module, Name, [Pid | Args]) stack_trace() -> Flag stack_trace(Flag) - Get/set if and how to save call frames + Get and set if and how to save call frames. Flag = all | no_tail | false @@ -281,25 +300,30 @@ spawn(Module, Name, [Pid | Args])

Gets and 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.

- - 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, + 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 may be + 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 - do not save any information about current - calls. - + tail recursive calls. This is the default.

 + + false +

Save no information about currentcalls.

 + break(Module, Line) -> ok | {error,break_exists} - Create a breakpoint + Create a breakpoint. Module = atom() Line = int() @@ -311,86 +335,80 @@ spawn(Module, Name, [Pid | Args]) delete_break(Module, Line) -> ok - Delete a breakpoint + Delete a breakpoint. Module = atom() Line = int() -

Deletes the breakpoint located at Line in - Module.

+

Deletes the breakpoint at Line in Module.

 break_in(Module, Name, Arity) -> ok | {error,function_not_found} - Create breakpoints in the specified function + Create breakpoints in the specified function. Module = Name = atom() Arity = int()

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

+ function Module:Name/Arity.

 del_break_in(Module, Name, Arity) -> ok | {error,function_not_found} - Delete breakpoints from the specified function - + Delete breakpoints from the specified function. Module = Name = atom() Arity = int()

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

+ function Module:Name/Arity.

 no_break() -> ok no_break(Module) -> ok - Delete all breakpoints + Delete all breakpoints. -

Deletes all breakpoints, or all breakpoints in Module. -

+

Deletes all breakpoints, or all breakpoints in Module.

 disable_break(Module, Line) -> ok - Make a breakpoint inactive + Make a breakpoint inactive. Module = atom() Line = int() -

Makes the breakpoint at Line in Module - inactive.

+

Makes the breakpoint at Line in Module inactive.

 enable_break(Module, Line) -> ok - Make a breakpoint active + Make a breakpoint active. Module = atom() Line = int() -

Makes the breakpoint at Line in Module active. -

+

Makes the breakpoint at Line in Module active.

 action_at_break(Module, Line, Action) -> ok - Set the trigger action of a breakpoint + Set the trigger action of a breakpoint. Module = atom() Line = int() @@ -404,7 +422,7 @@ spawn(Module, Name, [Pid | Args]) test_at_break(Module, Line, Function) -> ok - Set the conditional test of a breakpoint + Set the conditional test of a breakpoint. Module = atom() Line = int() @@ -414,14 +432,14 @@ spawn(Module, Name, [Pid | Args])

Sets the conditional test of the breakpoint at Line in Module to Function. The function must - fulfill the requirements specified in the section - Breakpoints above.

+ fulfill the requirements specified in section + Breakpoints.

 get_binding(Var, Bindings) -> {value,Value} | unbound - Retrieve a variable binding + Retrieve a variable binding. Var = atom() Bindings = term() @@ -437,7 +455,7 @@ spawn(Module, Name, [Pid | Args]) all_breaks() -> [Break] all_breaks(Module) -> [Break] - Get all breakpoints + Get all breakpoints. Break = {Point,Options}  Point = {Module,Line} @@ -451,15 +469,14 @@ spawn(Module, Name, [Pid | Args])     Name = atom() -

Gets all breakpoints, or all breakpoints in Module. -

+

Gets all breakpoints, or all breakpoints in Module.

 snapshot() -> [Snapshot] Get information about all processes executing interpreted - code + code. Snapshot = {Pid, Function, Status, Info}  Pid = pid() @@ -475,26 +492,27 @@ spawn(Module, Name, [Pid | Args])

Gets information about all processes executing interpreted code.

- - Pid - process identifier. - Function - first interpreted function called by + + Pid - Process identifier. + Function - First interpreted function called by the process. - Status - current status of the process. - Info - additional information. + Status - Current status of the process. + Info - More information. -

Status is one of:

- - idle - the process is no longer executing + +

Status is one of the following:

+ + idle - The process is no longer executing interpreted code. Info={}. - running - the process is running. Info={}. + running - The process is running. Info={}. - waiting - the process is waiting at a + waiting - The process is waiting at a receive. Info={}. - break - process execution has been stopped, + break - Process execution is stopped, normally at a breakpoint. Info={Module,Line}. - exit - the process has terminated. + exit - The process is terminated. Info=ExitReason. - no_conn - the connection is down to the node + no_conn - The connection is down to the node where the process is running. Info={}. @@ -503,7 +521,7 @@ spawn(Module, Name, [Pid | Args]) clear() -> ok Clear information about processes executing interpreted - code + code.

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

@@ -513,13 +531,13 @@ spawn(Module, Name, [Pid | Args]) continue(Pid) -> ok | {error,not_interpreted} continue(X,Y,Z) -> ok | {error,not_interpreted} - Resume process execution + Resume process execution. Pid = pid() X = Y = Z = int() -

Resume process execution for Pid, or for +

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

 diff --git a/lib/debugger/doc/src/introduction.xml b/lib/debugger/doc/src/introduction.xml new file mode 100644 index 0000000000..9f5f279bb0 --- /dev/null +++ b/lib/debugger/doc/src/introduction.xml @@ -0,0 +1,63 @@ + + + + +
+ + 19972013 + Ericsson AB. All Rights Reserved. + + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + + + Introduction + + + + + introduction.xml +
+ +
+ 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. +

+ +

The Erlang interpreter can also be accessed through the interface + module int(3). +

+ + +

Debugger might at some point + start tracing on the processes that execute the interpreted + code. This means that a conflict occurs if tracing by other + means is started on any of these processes.

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

+
+ + + + diff --git a/lib/debugger/doc/src/part.xml b/lib/debugger/doc/src/part.xml index 7515c0ad5b..ce1edbd978 100644 --- a/lib/debugger/doc/src/part.xml +++ b/lib/debugger/doc/src/part.xml @@ -4,7 +4,7 @@
- 19972013 + 19972016 Ericsson AB. All Rights Reserved. @@ -27,14 +27,10 @@ 1998-05-12 B - part.sgml + part.xml
- -

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

- + + diff --git a/lib/debugger/doc/src/ref_man.xml b/lib/debugger/doc/src/ref_man.xml index 6df9e90c2c..c44f07f912 100644 --- a/lib/debugger/doc/src/ref_man.xml +++ b/lib/debugger/doc/src/ref_man.xml @@ -28,12 +28,7 @@ - -

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

- + -- cgit v1.2.3