summary refs log tree commit diff stats
path: root/doc/endb.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/endb.txt')
-rwxr-xr-xdoc/endb.txt174
1 files changed, 0 insertions, 174 deletions
diff --git a/doc/endb.txt b/doc/endb.txt
deleted file mode 100755
index 63e382859..000000000
--- a/doc/endb.txt
+++ /dev/null
@@ -1,174 +0,0 @@
-===========================================

-  Embedded Nimrod Debugger User Guide

-===========================================

-

-:Author: Andreas Rumpf

-:Version: |nimrodversion|

-

-.. contents::

-

-Nimrod comes with a platform independant debugger -

-the `Embedded Nimrod Debugger`:idx: (`ENDB`:idx:). The debugger is

-*embedded* into your executable if it has been

-compiled with the ``--debugger:on`` command line option.

-This also defines the conditional symbol ``ENDB`` for you.

-

-Note: You must not compile your program with the ``--app:gui``

-command line option because then there would be no console

-available for the debugger.

-

-If you start your program the debugger will immediately show

-a prompt on the console. You can now enter a command. The next sections

-deal with the possible commands. As usual for Nimrod for all commands

-underscores and case do not matter. Optional components of a command

-are listed in brackets ``[...]`` here.

-

-

-General Commands

-================

-

-``h``, ``help``

-    Display a quick reference of the possible commands.

-

-``q``, ``quit``

-    Quit the debugger and the program.

-

-<ENTER>

-    (Without any typed command) repeat the previous debugger command.

-    If there is no previous command, ``step_into`` is assumed.

-

-Executing Commands

-==================

-

-``s``, ``step_into``

-    Single step, stepping into routine calls.

-

-``n``, ``step_over``

-    Single step, without stepping into routine calls.

-

-``f``, ``skip_current``

-    Continue execution until the current routine finishes.

-

-``c``, ``continue``

-    Continue execution until the next breakpoint.

-

-``i``, ``ignore``

-    Continue execution, ignore all breakpoints. This is effectively quitting

-    the debugger and runs the program until it finishes.

-

-

-Breakpoint Commands

-===================

-

-``b``, ``setbreak`` <identifier> [fromline [toline]] [file]

-    Set a new breakpoint named 'identifier' for the given file

-    and line numbers. If no file is given, the current execution point's

-    filename is used. If the filename has no extension, ``.nim`` is

-    appended for your convenience.

-    If no line numbers are given, the current execution point's

-    line is used. If both ``fromline`` and ``toline`` are given the

-    breakpoint contains a line number range. Some examples if it is still

-    unclear:

-

-    * ``b br1 12 15 thallo`` creates a breakpoint named ``br1`` that

-      will be triggered if the instruction pointer reaches one of the

-      lines 12-15 in the file ``thallo.nim``.

-    * ``b br1 12 thallo`` creates a breakpoint named ``br1`` that

-      will be triggered if the instruction pointer reaches the

-      line 12 in the file ``thallo.nim``.

-    * ``b br1 12`` creates a breakpoint named ``br1`` that

-      will be triggered if the instruction pointer reaches the

-      line 12 in the current file.

-    * ``b br1`` creates a breakpoint named ``br1`` that

-      will be triggered if the instruction pointer reaches the

-      current line in the current file again.

-

-``breakpoints``

-    Display the entire breakpoint list.

-

-``disable`` <identifier>

-    Disable a breakpoint. It remains disabled until you turn it on again

-    with the ``enable`` command.

-

-``enable`` <identifier>

-    Enable a breakpoint.

-

-Often it happens when debugging that you keep retyping the breakpoints again

-and again because they are lost when you restart your program. This is not

-necessary: A special pragma has been defined for this:

-

-

-The ``{.breakpoint.}`` pragma

------------------------------

-

-The `breakpoint`:idx: pragma is syntactically a statement. It can be used

-to mark the *following line* as a breakpoint:

-

-.. code-block:: Nimrod

-  write("1")

-  {.breakpoint: "before_write_2".}

-  write("2")

-

-The name of the breakpoint here is ``before_write_2``. Of course the

-breakpoint's name is optional - the compiler will generate one for you

-if you leave it out.

-

-Code for the ``breakpoint`` pragma is only generated if the debugger

-is turned on, so you don't need to remove it from your source code after

-debugging.

-

-

-Data Display Commands

-=====================

-

-``e``, ``eval`` <exp>

-    Evaluate the expression <exp>. Note that ENDB has no full-blown expression

-    evaluator built-in. So expressions are limited:

-

-    * To display global variables prefix their names with their

-      owning module: ``nim1.globalVar``

-    * To display local variables or parameters just type in

-      their name: ``localVar``. If you want to inspect variables that are not

-      in the current stack frame, use the ``up`` or ``down`` command.

-

-    Unfortunately, only inspecting variables is possible at the moment. Maybe

-    a future version will implement a full-blown Nimrod expression evaluator,

-    but this is not easy to do and would bloat the debugger's code.

-

-    Since displaying the whole data structures is often not needed and

-    painfully slow, the debugger uses a *maximal display depth* concept for

-    displaying.

-

-    You can alter the *maximal display depth* with the ``maxdisplay``

-    command.

-

-``maxdisplay`` <natural>

-    Sets the maximal display depth to the given integer value. A value of 0

-    means there is no maximal display depth. Default is 3.

-

-``o``, ``out`` <filename> <exp>

-    Evaluate the expression <exp> and store its string representation into a

-    file named <filename>. If the file does not exist, it will be created,

-    otherwise it will be opened for appending.

-

-``w``, ``where``

-    Display the current execution point.

-

-``u``, ``up``

-    Go up in the call stack.

-

-``d``, ``down``

-    Go down in the call stack.

-

-``stackframe`` [file]

-    Displays the content of the current stack frame in ``stdout`` or

-    appends it to the file, depending on whether a file is given.

-

-``callstack``

-    Display the entire call stack (but not its content).

-

-``l``, ``locals``

-    Display the available local variables in the current stack frame.

-

-``g``, ``globals``

-    Display all the global variables that are available for inspection.