breakpoint_command

Automatically execute commands on breakpoint stop as in gdb, pdb, and other debuggers, including dbstep and dbcont.

Simulates the "commands on breakpoint" functionality that is present in many debuggers, e.g.

• gdb: https://sourceware.org/gdb/onlinedocs/gdb/Break-Commands.html
• windbg: https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/bs--update-breakpoint-command-
• pdb: https://docs.python.org/3/library/pdb.html#pdbcommand-commands

but is not officially present in MATLAB debugger.

This is done by leveraging conditional breakpoint side effects and the ability to cue commands in the console with com.mathworks.mlservices.MLExecuteServices.consoleEval as described in [1].

Other tools such as Darin_dbtools make use of conditional breakpoint side effects to print variables and even modify values. However, this technique is fundamentally limited due to the fact that actual debugger commands (such as dbstep) cannot be run in this mode.

Example use:

Consider f.m:

function [x,y] = f(a)
x = a + 1;
y = a + 2;

It is desired to print the function output 'y' at line 3 before returning (without modifying the code using disp statements).

This could be done with the Darin_dbtools dbdisp as a breakpoint evaluation side effect if we could only attach the breakpoint to a line after y has been assigned. (Note this function has no end statement).

Instead, place conditional breakpoint at line 3 with condition:

breakpoint_command({'dbstep', 'disp(y)'})

Now, run:

>> [x,y] = f(1)
3   y = a + 2;
End of function f.
   3


x =

   2


y =

   3
>>

Despite the breakpoint being at the start of line 3, the dbstep command moves the debugger to "End of function f" (for which a breakpoint cannot be placed) where the value of y can be printed.

The condition can also be given using strings rather than chars.

breakpoint_command(["dbstep", "disp(y)"])

Single commands do not have to be placed in an array.

breakpoint_command('disp(x)')

or

breakpoint_command("disp(x)")

By passing optional second argument as false, the debugger will not be made to continue after the commands and interactive debugging can proceed normally.

breakpoint_command("disp(x)", false)

This can even be used to end the run completely with dbquit.

breakpoint_command("dbquit", false)

In this case, the false is necessary because if a dbcont is attempted after dbquit, this will result in an error.

In short, this function allows you to script any MATLAB debugger behavior that could occur in an interactive session. This should enable powerful workflows including runtime instrumentation of code and swapping of function implementations before/after call (using path modifications). If you find yourself using a complex workflow (such as runtime injected plotting), place it in a script which you then call with this command.

The function has been developed and tested in R2020a. Other releases will probably work too (even old ones without string type support if you use char only).

Since the function makes use of undocumented feature com.mathworks.mlservices.MLExecuteServices.consoleEval, it is not guaranteed to work in a future version.

References:

[1] Altman, Yair M. Undocumented secrets of MATLAB-Java programming. CRC Press, 2011.