Initial import

doc/endb.txt

@@ -0,0 +1,174 @@
+===========================================
+  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 is 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.