diff options
Diffstat (limited to 'lib/debugger/doc/src/debugger_chapter.xml')
| -rw-r--r-- | lib/debugger/doc/src/debugger_chapter.xml | 893 |
1 files changed, 893 insertions, 0 deletions
diff --git a/lib/debugger/doc/src/debugger_chapter.xml b/lib/debugger/doc/src/debugger_chapter.xml new file mode 100644 index 0000000000..1f5d4dd5ff --- /dev/null +++ b/lib/debugger/doc/src/debugger_chapter.xml @@ -0,0 +1,893 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> +<header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Debugger</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>debugger_chapter.xml</file> + </header> + + <section> + <title>Introduction</title> + + <p><em>Debugger</em> 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. + </p> + + <p>The Erlang interpreter can also be accessed via the interface + module <c>int</c>, see <seealso marker="int">int(3)</seealso>. + </p> + + <p><em>Warning:</em> 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.</p> + </section> + + <section> + <title>Getting Started with Debugger</title> + + <p>Start Debugger by calling <c>debugger:start()</c>. It will start + the <seealso marker="#monitor">Monitor window</seealso> showing + information about all debugged processes, interpreted modules and + selected options.</p> + + <p>Initially there are normally no debugged processes. First, it + must be specified which modules should be <em>debugged</em>, or + <em>interpreted</em> as it is also called. This is done by + choosing <em>Module->Interpret...</em> in the Monitor window and + then selecting the appropriate modules from the + <seealso marker="#interpret">Interpret Dialog window</seealso>. + </p> + + <note> + <p>Only modules compiled with the option <c>debug_info</c> set + can be interpreted. Non-interpretable modules are shown within + parenthesis in the Interpret Dialog window.</p> + </note> + + <p>When a module is interpreted, it can be viewed in a + <seealso marker="#view">View Module window</seealso>. This is done + by selecting the module from the <em>Module->module->View</em> + menu. The contents of the source file is shown and it is possible + to set <seealso marker="#breakpoints">breakpoints</seealso>.</p> + + <p>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 <em>attach</em> to one of these + processes, by double-clicking it, or by selecting the process and + then choosing <em>Process->Attach</em>.</p> + + <p>Attaching to a process will result in a + <seealso marker="#attach">Attach Process window</seealso> being + opened for this process. From the Attach Process window, it is + possible to control the process execution, inspect variable + values, set breakpoints etc.</p> + </section> + + <section> + <marker id="breakpoints"/> + <title>Breakpoints and Break Dialogue Windows</title> + + <p>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.</p> + + <note> + <p>When a process reaches a breakpoint, only that process is + stopped. Other processes are not affected.</p> + </note> + + <p>Breakpoints are created and deleted using the Break menu of + the Monitor window, View Module window and Attach Process window. + </p> + + <section> + <title>Executable Lines</title> + + <p>To have effect, a breakpoint must be set at an + <em>executable line</em>, 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 <c>case</c>- or <c>receive</c> statement is not + executable.</p> + + <p>In the example below, lines number 2, 4, 6, 8 and 11 are + executable lines:</p> + <pre> +1: is_loaded(Module,Compiled) -> +2: case get_file(Module,Compiled) of +3: {ok,File} -> +4: case code:which(Module) of +5: ?TAG -> +6: {loaded,File}; +7: _ -> +8: unloaded +9: end; +10: false -> +11: false +12: end.</pre> + </section> + + <section> + <title>Status and Trigger Action</title> + + <p>A breakpoint can be either <em>active</em> or + <em>inactive</em>. Inactive breakpoints are ignored.</p> + + <p>Each breakpoint has a <em>trigger action</em> which specifies + what should happen when a process has reached it (and stopped): + </p> + <list> + <item><em>enable</em> Breakpoint should remain active (default). + </item> + <item><em>disable</em> Breakpoint should be made inactive. + </item> + <item><em>delete</em> Breakpoint should be deleted.</item> + </list> + </section> + + <section> + <title>Line Breakpoints</title> + + <p>A line breakpoint is created at a certain line in a module.</p> + + <image file="images/line_break_dialog.gif"> + <icaption>The Line Break Dialog Window.</icaption> + </image> + + <p>Right-clicking the Module entry will open a popup menu from + which the appropriate module can be selected.</p> + + <p>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.</p> + </section> + + <section> + <title>Conditional Breakpoints</title> + + <p>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.</p> + + <p>The condition is specified by the user as a module name + <c>CModule</c> and a function name <c>CFunction</c>. When a + process reaches the breakpoint, + <c>CModule:CFunction(Bindings)</c> will be evaluated. If and + only if this function call returns <c>true</c>, the process + will stop. If the function call returns <c>false</c>, + the breakpoint will be silently ignored.</p> + + <p><c>Bindings</c> is a list of variable bindings. Use + the function <c>int:get_binding(Variable,Bindings)</c> to + retrieve the value of <c>Variable</c> (given as an atom). + The function returns <c>unbound</c> or <c>{value,Value}</c>.</p> + + <image file="images/cond_break_dialog.gif"> + <icaption>The Conditional Break Dialog Window.</icaption> + </image> + + <p>Right-clicking the Module entry will open a popup menu from + which the appropriate module can be selected.</p> + + <p>Example: A conditional breakpoint calling + <c>c_test:c_break/1</c> is added at line 8 in the module + <c>fac</c>. Each time the breakpoint is reached, the function is + called, and when <c>N</c> is equal to 3 it returns <c>true</c>, + and the process stops.</p> + + <p>Extract from <c>fac.erl</c>:</p> + <pre> +4. fac(0) -> +5. 1; +6. +7. fac(N) -> +8. N * fac(N - 1).</pre> + + <p>Definition of <c>c_test:c_break/1</c>:</p> + <pre> +-module(c_test). +-export([c_break/1]). + +c_break(Bindings) -> + case int:get_binding('N', Bindings) of + {value, 3} -> + true; + _ -> + false + end.</pre> + </section> + + <section> + <title>Function Breakpoints</title> + + <p>A function breakpoint is a set of line breakpoints, one at + the first line of each clause in the given function.</p> + + <image file="images/function_break_dialog.gif"> + <icaption>The Function Break Dialog Window.</icaption> + </image> + + <p>Right-clicking the Module entry will open a popup menu from + which the appropriate module can be selected.</p> + + <p>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.</p> + </section> + </section> + + <section> + <marker id="stack_trace"/> + <title>Stack Trace</title> + + <p>The Erlang emulator keeps track of a <em>stack trace</em>, + information about recent function calls. This information is + used, for example, if an error occurs:</p> + <pre> +1> <input>catch a+1.</input> +{'EXIT',{badarith,[{erlang,'+',[a,1]}, + {erl_eval,do_apply,5}, + {erl_eval,expr,5}, + {shell,exprs,6}, + {shell,eval_exprs,6}, + {shell,eval_loop,3}]}}</pre> + + <p>In the case above, the stack trace shows that the function called + last was <c>erl_eval:eval_op/3</c>. See <em>Erlang Reference + Manual, Errors and Error handling</em>, for more information + about stack trace.</p> + + <p>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).</p> + + <p>This information can be used to traverse the chain of function + calls, using the 'Up' and 'Down' buttons of + <seealso marker="#attach">the Attach Process window</seealso>. + </p> + + <p>By default, the Debugger saves information about all current + function calls, that is, function calls that have not yet returned + a value (option 'Stack On, Tail').</p> + + <p>This means, however, that information is saved also for tail + recursive calls. For example, repeated calls to the <c>loop</c> + function of an Erlang process. This may consume unnecessary + amounts of memory for debugged processes with long lifetimes and + many tail recursive calls. It is therefore possible to set + the option 'Stack On, no tail', in which case information about + previous calls are discarded when a tail recursive call is made. + </p> + + <p>It is also possible to turn off the Debugger stack trace + facility ('Stack Off'). <em>Note:</em> If an error occurs, in this + case the stack trace will be empty.</p> + + <p>See the section about <seealso marker="#monitor">the Monitor + Window</seealso> for information about how to change the stack + trace option.</p> + </section> + + <section> + <marker id="monitor"/> + <title>The Monitor Window</title> + + <p>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.</p> + + <image file="images/monitor.gif"> + <icaption>The Monitor Window.</icaption> + </image> + + <p>The Auto Attach buttons, Stack Trace label and Back Trace Size + label show some options set, see + <seealso marker="#options">Options Menu</seealso> for further + information about these options.</p> + + <section> + <title>Process Grid</title> + + <taglist> + <tag><em>Pid</em></tag> + <item><p>The process identifier.</p></item> + + <tag><em>Initial Call</em></tag> + <item><p>The first call to an interpreted function by this + process. (<c>Module:Function/Arity</c>)</p></item> + + <tag><em>Name</em></tag> + <item><p>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 <em>Edit->Refresh</em>.</p></item> + + <tag><em>Status</em></tag> + <item><p>The current status, one of the following:</p> + <taglist> + <tag><em>idle</em></tag> + <item><p>The interpreted function call has returned a value, + and the process is no longer executing interpreted code. + </p></item> + + <tag><em>running</em></tag> + <item><p>The process is running.</p></item> + + <tag><em>waiting</em></tag> + <item><p>The process is waiting in a <c>receive</c> + statement.</p></item> + + <tag><em>break</em></tag> + <item><p>The process is stopped at a breakpoint.</p></item> + + <tag><em>exit</em></tag> + <item><p>The process has terminated.</p></item> + + <tag><em>no_conn</em></tag> + <item><p>There is no connection to the node where + the process is located.</p></item> + </taglist> + </item> + + <tag><em>Information</em></tag> + <item><p>Additional information, if any. If the process is + stopped at a breakpoint, the field contains information + about the location <c>{Module,Line}</c>. If the process has + terminated, the field contains the exit reason.</p></item> + </taglist> + </section> + + <section> + <title>The File Menu</title> + + <taglist> + <tag><em>Load Settings...</em></tag> + <item> + <p>Try to load and restore Debugger settings from a file + previously saved using <em>Save Settings...</em>, see below. + Any errors are silently ignored.</p> + </item> + + <tag><em>Save Settings...</em></tag> + <item><p>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 <em>Load Settings...</em>, see above. + Any errors are silently ignored.</p> + </item> + + <tag><em>Exit</em></tag> + <item><p>Stop Debugger.</p></item> + </taglist> + </section> + + <section> + <title>The Edit Menu</title> + <taglist> + <tag><em>Refresh</em></tag> + <item><p>Update information about debugged processes. Removes + information about all terminated processes from the window, + and also closes all Attach Process windows for terminated + processes.</p></item> + + <tag><em>Kill All</em></tag> + <item><p>Terminate all processes listed in the window using + <c>exit(Pid,kill)</c>.</p></item> + </taglist> + </section> + + <section> + <title>The Module Menu</title> + <taglist> + <tag><em>Interpret...</em></tag> + <item><p>Open the <seealso marker="#interpret">Interpret Dialog + window</seealso> where new modules to be interpreted can + be specified.</p></item> + + <tag><em>Delete All</em></tag> + <item><p>Stop interpreting all modules. Processes executing in + interpreted modules will terminate.</p></item> + </taglist> + + <p>For each interpreted module, a corresponding entry is added to + the Module menu, with the following submenu:</p> + <taglist> + <tag><em>Delete</em></tag> + <item><p>Stop interpreting the selected module. Processes + executing in this module will terminate.</p></item> + + <tag><em>View</em></tag> + <item><p>Open a <seealso marker="#view">View Module + window</seealso> showing the contents of the selected + module.</p></item> + </taglist> + </section> + + <section> + <title>The Process Menu</title> + <p>The following menu items apply to the currently selected + process, provided it is stopped at a breakpoint. See the chapter + about the <seealso marker="#attach">Attach Process + window</seealso> for more information.</p> + <taglist> + <tag><em>Step</em></tag><item></item> + <tag><em>Next</em></tag><item></item> + <tag><em>Continue</em></tag><item></item> + <tag><em>Finish</em></tag><item></item> + </taglist> + <p>The following menu items apply to the currently selected + process.</p> + <taglist> + <tag><em>Attach</em></tag> + <item><p>Attach to the process and open a + <seealso marker="#attach">Attach Process window</seealso>. + </p></item> + + <tag><em>Kill</em></tag> + <item><p>Terminate the process using <c>exit(Pid,kill)</c>.</p> + </item> + </taglist> + </section> + + <section> + <title>The Break Menu</title> + <p>The items in this menu are used to create and delete + breakpoints. + See the <seealso marker="#breakpoints">Breakpoints</seealso> + chapter for more information.</p> + <taglist> + <tag><em>Line Break...</em></tag> + <item><p>Set a line breakpoint.</p></item> + + <tag><em>Conditional Break...</em></tag> + <item><p>Set a conditional breakpoint.</p></item> + + <tag><em>Function Break...</em></tag> + <item><p>Set a function breakpoint.</p></item> + + <tag><em>Enable All</em></tag> + <item><p>Enable all breakpoints.</p></item> + + <tag><em>Disable All</em></tag> + <item><p>Disable all breakpoints.</p></item> + + <tag><em>Delete All</em></tag> + <item><p>Remove all breakpoints.</p></item> + </taglist> + + <p>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.</p> + </section> + + <section> + <marker id="options"/> + <title>The Options Menu</title> + + <taglist> + <tag><em>Trace Window</em></tag> + <item><p>Set which areas should be visible in + an <seealso marker="#attach">Attach Process + window</seealso>. Does not affect already existing + Attach Process windows.</p> + </item> + + <tag><em>Auto Attach</em></tag> + <item><p>Set at which events a debugged process should be + automatically attached to. Affects existing debugged + processes.</p> + <list> + <item><em>First Call</em> - the first time a process calls a + function in an interpreted module.</item> + <item><em>On Exit</em> - at process termination.</item> + <item><em>On Break</em> - when a process reaches a + breakpoint.</item> + </list> + </item> + + <tag><em>Stack Trace</em></tag> + <item><p>Set stack trace option, see section + <seealso marker="#stack_trace">Stack Trace</seealso>. Does not + affect already existing debugged processes.</p> + <list> + <item><em>Stack On, Tail</em> - save information about all + current calls.</item> + <item><em>Stack On, No Tail</em> - save information about + current calls, discarding previous information when a tail + recursive call is made.</item> + <item><em>Stack Off</em> - do not save any information about + current calls.</item> + </list> + </item> + + <tag><em>Back Trace Size...</em></tag> + <item><p>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.</p> + </item> + </taglist> + </section> + + <section> + <title>The Windows Menu</title> + <p>Contains a menu item for each open Debugger window. Selecting + one of the items will raise the corresponding window.</p> + </section> + + <section> + <title>The Help Menu</title> + <taglist> + <tag><em>Help</em></tag> + <item><p>View the Debugger documentation. Currently this + function requires Netscape to be up and running.</p></item> + </taglist> + </section> + </section> + + <section> + <marker id="interpret"/> + <title>The Interpret Dialog Window</title> + + <p>The interpret dialog module is used for selecting which modules + to interpret. Initially, the window shows the modules (<c>erl</c> + files) and subdirectories of the current working directory.</p> + + <p>Interpretable modules are modules for which a BEAM file, compiled + with the option <c>debug_info</c> set, can be found in the same + directory as the source code, or in an <c>ebin</c> directory next + to it.</p> + + <p>Modules, for which the above requirements are not fulfilled, are + not interpretable and are therefore displayed within parentheses. + </p> + + <p>The <c>debug_info</c> option causes <em>debug information</em> or + <em>abstract code</em> to be added to the BEAM file. This will + increase the size of the file, and also makes it possible to + reconstruct the source code. It is therefore recommended not to + include debug information in code aimed for target systems.</p> + + <p>An example of how to compile code with debug information using + <c>erlc</c>:<br/> + <c>% erlc +debug_info module.erl</c></p> + + <p>An example of how to compile code with debug information from + the Erlang shell:<br/> + <c>4> c(module, debug_info).</c></p> + + <image file="images/interpret.gif"> + <icaption>The Interpret Dialog Window.</icaption> + </image> + + <p>Browse the file hierarchy and interpret the appropriate modules + by selecting a module name and pressing <em>Choose</em> (or + carriage return), or by double clicking the module name. + Interpreted modules are displayed with a * in front of the name. + </p> + + <p>Pressing <em>All</em> will interpret all displayed modules in + the chosen directory.</p> + + <p>Pressing <em>Done</em> will close the window.</p> + + <note> + <p>When the Debugger is started in global mode (which is + the default, see + <seealso marker="debugger:debugger#start/0">debugger:start/0</seealso>), + modules added (or deleted) for interpretation will be added (or + deleted) on all known Erlang nodes.</p> + </note> + </section> + + <section> + <marker id="attach"/> + <title>The Attach Process Window</title> + + <p>From an Attach Process window the user can interact with a + debugged process. One window is opened for each process that has + been attached to. Note that when attaching to a process, its + execution is automatically stopped. + </p> + + <image file="images/attach.gif"> + <icaption>The Attach Process Window.</icaption> + </image> + + <p>The window is divided into five parts:</p> + <list> + <item><p>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 <em>--></em>. An existing break point at a line + is marked with <em>-@-</em>. In the example above, + the execution has been stopped at line 56, before + the execution of <c>io:format/2</c>.</p> + <p>Active breakpoints are shown in red, while inactive + breakpoints are shown in blue.</p> + </item> + <item>The Button area, with buttons for quick access to frequently + used functions in the Process menu.</item> + <item>The Evaluator area, where the user can evaluate functions + within the context of the debugged process, provided that + process execution has been stopped.</item> + <item>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. + </item> + <item><p>The Trace area, showing a trace output for the process. + </p> + <taglist> + <tag><c>++ (N) <L></c></tag> + <item>Function call, where <c>N</c> is the call level and + <c>L</c> the line number.</item> + + <tag><c>-- (N)</c></tag> + <item>Function return value.</item> + + <tag><c>==> Pid : Msg</c></tag> + <item>The message <c>Msg</c> is sent to process <c>Pid</c>. + </item> + + <tag><c><![CDATA[<== Msg]]></c></tag> + <item>The message <c>Msg</c> is received.</item> + + <tag><c>++ (N) receive</c></tag> + <item>Waiting in a <c>receive</c>.</item> + + <tag><c>++ (N) receive with timeout</c></tag> + <item>Waiting in a <c>receive...after</c>.</item> + </taglist> + + <p>Also the back trace, a summary of the current function calls + on the stack, is displayed in the Trace area.</p> + </item> + </list> + + <p>It is configurable using the Options menu which areas should + be shown or hidden. By default, all areas except the Trace area + is shown.</p> + + <section> + <title>The File Menu</title> + + <taglist> + <tag><em>Close</em></tag> + <item><p>Close this window and detach from the process.</p> + </item> + </taglist> + </section> + + <section> + <title>The Edit Menu</title> + + <taglist> + <tag><em>Go to line...</em></tag> + <item><p>Go to a specified line number.</p></item> + + <tag><em>Search...</em></tag> + <item><p>Search for a specified string.</p></item> + </taglist> + </section> + + <section> + <title>The Process Menu</title> + + <taglist> + <tag><em>Step</em></tag> + <item><p>Execute the current line of code, stepping into any + (interpreted) function calls.</p></item> + + <tag><em>Next</em></tag> + <item><p>Execute the current line of code and stop at the next + line.</p></item> + + <tag><em>Continue</em></tag> + <item><p>Continue the execution.</p></item> + + <tag><em>Finish</em></tag> + <item><p>Continue the execution until the current function + returns.</p></item> + + <tag><em>Skip</em></tag> + <item><p>Skip the current line of code and stop at the next + line. If used on the last line in a function body, + the function will return <c>skipped</c>.</p></item> + + <tag><em>Time Out</em></tag> + <item><p>Simulate a timeout when executing a + <c>receive...after</c> statement.</p></item> + + <tag><em>Stop</em></tag> + <item><p>Stop the execution of a running process, that is, make + the process stop as at a breakpoint. The command will take + effect (visibly) the next time the process receives a + message.</p></item> + + <tag><em>Where</em></tag> + <item><p>Make sure the current location of the execution is + visible in the code area.</p></item> + + <tag><em>Kill</em></tag> + <item><p>Terminate the process using <c>exit(Pid,kill)</c>.</p> + </item> + + <tag><em>Messages</em></tag> + <item><p>Inspect the message queue of the process. The queue is + printed in the evaluator area.</p></item> + + <tag><em>Back Trace</em></tag> + <item><p>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'.</p> + </item> + + <tag><em>Up</em></tag> + <item><p>Inspect the previous function call on the stack, + showing the location and variable bindings.</p></item> + + <tag><em>Down</em></tag> + <item><p>Inspect the next function call on the stack, showing + the location and variable bindings.</p></item> + </taglist> + </section> + + <section> + <title>The Options Menu</title> + + <taglist> + <tag><em>Trace Window</em></tag> + <item><p>Set which areas should be visible. Does not affect + other Attach Process windows.</p> + </item> + + <tag><em>Stack Trace</em></tag> + <item><p>Same as in <seealso marker="#monitor">the Monitor + window</seealso>, but does only affect the debugged + process the window is attached to.</p> + </item> + + <tag><em>Back Trace Size...</em></tag> + <item><p>Set how many call frames should be fetched when + inspecting the call stack. Does not affect other Attach + Process windows.</p> + </item> + </taglist> + </section> + + <section> + <title>Break, Windows and Help Menus</title> + + <p>The Break, Windows and Help menus look the same as in + the Monitor window, see the chapter + <seealso marker="#monitor">The Monitor Window</seealso>, except + that the Breaks menu apply to the local breakpoints only.</p> + </section> + </section> + + <section> + <marker id="view"/> + <title>The View Module Window</title> + + <p>The View Module window shows the contents of an interpreted + module and makes it possible to set breakpoints.</p> + + <image file="images/view.gif"> + <icaption>The View Module Window.</icaption> + </image> + + <p>The source code is indented and each line is prefixed with its + line number.</p> + + <p>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.</p> + + <p>Breakpoints are marked with <em>-@-</em>.</p> + + <section> + <title>File and Edit Menus</title> + <p>The File and Edit menus look the same as in the Attach Process + window, see the chapter <seealso marker="#attach">The Attach + Process Window</seealso>.</p> + </section> + + <section> + <title>Break, Windows and Help Menus</title> + + <p>The Break, Windows and Help menus look the same as in + the Monitor window, see the chapter + <seealso marker="#monitor">The Monitor Window</seealso>, except + that the Breaks menu apply to the local breakpoints only.</p> + </section> + </section> + + <section> + <title>Performance</title> + + <p>Execution of interpreted code is naturally slower than for + regularly compiled modules. Using the Debugger also increases + the number of processes in the system, as for each debugged + process another process (the meta process) is created.</p> + + <p>It is also worth to keep in mind that programs with timers may + behave differently when debugged. This is especially true when + stopping the execution of a process, for example at a + breakpoint. Timeouts can then occur in other processes that + continue execution as normal.</p> + </section> + + <section> + <title>Code Loading Mechanism</title> + + <p>Code loading works almost as usual, except that interpreted + modules are also stored in a database and debugged processes + uses only this stored code. Re-interpreting an interpreted + module will result in the new version being stored as well, but + does not affect existing processes executing an older version + of the code. This means that the code replacement mechanism of + Erlang does not work for debugged processes.</p> + </section> + + <section> + <title>Debugging Remote Nodes</title> + + <p>By using <c>debugger:start/1</c>, it can be specified if Debugger + should be started in local or global mode.</p> + <pre> +debugger:start(local | global)</pre> + <p>If no argument is provided, Debugger is started in global mode. + </p> + + <p>In local mode, code is interpreted only at the current node. + In global mode, code is interpreted at all known nodes. Processes + at other nodes executing interpreted code will automatically be + shown in the Monitor window and can be attached to like any other + debugged process.</p> + + <p>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.</p> + </section> +</chapter> + + |