.. default-domain:: chpl

.. module:: Debugger
   :synopsis: Provides a collection of useful debugging utilities.

Debugger
========
**Usage**

.. code-block:: chapel

   use Debugger;


or

.. code-block:: chapel

   import Debugger;

.. warning::

   The Debugger module is unstable due to its experimental behavior

Provides a collection of useful debugging utilities.

The Debugger module currently provides two functions: :proc:`breakpoint` and
:proc:`debugTrap`. Both functions can be used to set breakpoints in your code
when using a debugger. Users should prefer using the :proc:`breakpoint`
function, as it is more portable and easier to use.

The :proc:`debugTrap` function is a lower-level function that raises a debug
trap exception. This function is useful for testing purposes, but can crash the
program if used and no debugger is attached.

.. function:: proc breakpoint

   
   Sets a breakpoint at this point in execution.
   
   This only works if a breakpoint is set on the 'debuggerBreakHere' function
   with ``b debuggerBreakHere``. If using ``--gdb`` or ``--lldb``, this
   is done automatically.
   

.. data:: config param disableDebugTraps = false

   
   If ``disableDebugTraps`` is set to ``true``, then the
   :proc:`debugTrap` function will not raise a debug trap exception.
   
   This is useful for testing purposes, as it allows code to be left
   unchanged and still be able to run without a debugger attached.
   

.. function:: proc debugTrap

   
   Raises a debug trap exception. Using this function will cause the program
   automatically stop at a breakpoint if a debugger is attached. If no debugger
   is attached, the program will terminate with a message indicating that a
   debug trap was raised.