Isabelle/ML is based on Poly/ML and thus benefits from the source-level debugger of that implementation of Standard ML. The Prover IDE provides the Debugger dockable to connect to running ML threads, inspect the stack frame with local ML bindings, and evaluate ML expressions in a particular run-time context. A typical debugger session is shown in the screenshot below.

ML debugging depends on the following pre-requisites.

1. ML source needs to be compiled with debugging enabled. This may be controlled for particular chunks of ML sources using any of the subsequent facilities.

   1. The system option ML_debugger as implicit state of the Isabelle process. It may be changed in the menu Plugins / Plugin Options / Isabelle / General. ML modules need to be reloaded and recompiled to pick up that option as intended.
   2. The configuration option ML_debugger, with an attribute of the same name, to update a global or local context (e.g. with the declare command).
   3. Commands that modify ML_debugger state for individual files: ML_file_debug, ML_file_no_debug, SML_file_debug, SML_file_no_debug.

   The instrumentation of ML code for debugging causes minor run-time overhead. ML modules that implement critical system infrastructure may lead to deadlocks or other undefined behaviour, when put under debugger control!

2. The Debugger panel needs to be active, otherwise the program ignores debugger instrumentation of the compiler and runs unmanaged. It is also possible to start debugging with the panel open, and later undock it, to let the program continue unhindered.

3. The ML program needs to be stopped at a suitable breakpoint, which may be activated individually or globally as follows.

   For ML sources that have been compiled with debugger support, the IDE visualizes possible breakpoints in the text. A breakpoint may be toggled by pointing accurately with the mouse, with a right-click to activate jEdit’s context menu and its Toggle Breakpoint item. Alternatively, the Break checkbox in the Debugger panel may be enabled to stop ML threads always at the next possible breakpoint.

Note that the state of individual breakpoints gets lost when the coresponding ML source is re-compiled! This may happen unintentionally, e.g. when following hyperlinks into ML modules that have not been loaded into the IDE before.

The debugger panel (see screenshot) shows a list of all threads that are presently stopped. Each thread shows a stack of all function invocations that lead to the current breakpoint at the top.

It is possible to jump between stack positions freely, by clicking on this list. The current situation is displayed in the big output window, as a local ML environment with names and printed values.

ML expressions may be evaluated in the current context by entering snippets of source into the text fields labeled Context and ML, and pushing the Eval button. By default, the source is interpreted as Isabelle/ML with the usual support for antiquotations (like ML, ML_file). Alternatively, strict Standard ML may be enforced via the SML checkbox (like SML_file).

The context for Isabelle/ML is optional, it may evaluate to a value of type theory, Proof.context, Context.generic. Thus the given ML expression (with its antiquotations) may be subject to the intended dynamic run-time context, instead of the static compile-time context.

The buttons labeled Continue, Step, Step over, Step out recommence execution of the program, with different policies concerning nested function invocations. The debugger always moves the cursor within the ML source to the next breakpoint position, and offers new stack frames as before.