diff options
Diffstat (limited to 'doc/endb.rst')
| -rw-r--r-- | doc/endb.rst | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/doc/endb.rst b/doc/endb.rst new file mode 100644 index 000000000..6757d98e3 --- /dev/null +++ b/doc/endb.rst @@ -0,0 +1,203 @@ +============================================== + Embedded Nim Debugger (ENDB) User Guide +============================================== + +:Author: Andreas Rumpf +:Version: |nimversion| + +.. contents:: + +**WARNING**: ENDB is not maintained anymore! Please help if you're interested +in this tool. + +Nim comes with a platform independent debugger - +the Embedded Nim Debugger (ENDB). 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 in Nim in 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 effectively quits + the debugger and runs the program until it finishes. + + +Breakpoint Commands +=================== + +``b``, ``setbreak`` [fromline [toline]] [file] + Set a new breakpoint 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 12 15 thallo`` creates a breakpoint that + will be triggered if the instruction pointer reaches one of the + lines 12-15 in the file ``thallo.nim``. + * ``b 12 thallo`` creates a breakpoint that + will be triggered if the instruction pointer reaches the + line 12 in the file ``thallo.nim``. + * ``b 12`` creates a breakpoint that + will be triggered if the instruction pointer reaches the + line 12 in the current file. + * ``b`` creates a breakpoint 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`` pragma is syntactically a statement. It can be used +to mark the *following line* as a breakpoint: + +.. code-block:: Nim + 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. + + +The ``watchpoint`` pragma +------------------------- + +The ``watchpoint`` pragma is syntactically a statement. It can be used +to mark a location as a watchpoint: + +.. code-block:: Nim + var a: array [0..20, int] + + {.watchpoint: a[3].} + for i in 0 .. 20: a[i] = i + +ENDB then writes a stack trace whenever the content of the location ``a[3]`` +changes. The current implementation only tracks a hash value of the location's +contents and so locations that are not word sized may encounter false +negatives in very rare cases. + +Code for the ``watchpoint`` pragma is only generated if the debugger +is turned on, so you don't need to remove it from your source code after +debugging. + +Due to the primitive implementation watchpoints are even slower than +breakpoints: After *every* executed Nim code line it is checked whether the +location changed. + + +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 Nim 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. |