Rodrigo Mesquita authored May 14, 2025 and Marge Bot committed Jul 08, 2025

Implements support for stepping-out of a function (aka breaking right after
returning from a function) in the interactive debugger.

It also introduces a GHCi command :stepout to step-out of a function
being debugged in the interpreter. The feature is described as:

    Stop at the first breakpoint immediately after returning from the current
    function scope.

    Known limitations: because a function tail-call does not push a stack
    frame, if step-out is used inside of a function that was tail-called,
    execution will not be returned to its caller, but rather its caller's
    first non-tail caller. On the other hand, it means the debugger
    follows the more realistic execution of the program.
    In the following example:

    .. code-block:: none

    f = do
       a
       b <--- (1) set breakpoint then step in here
       c
    b = do
       ...
       d <--- (2) step-into this tail call
    d = do
       ...
       something <--- (3) step-out here
       ...

    Stepping-out will stop execution at the `c` invokation in `f`, rather than
    stopping at `b`.

The key idea is simple: When step-out is enabled, traverse the runtime
stack until a continuation BCO is found -- and enable the breakpoint
heading that BCO explicitly using its tick-index.
The details are specified in `Note [Debugger: Step-out]` in `rts/Interpreter.c`.

Since PUSH_ALTS BCOs (representing case continuations) were never headed
by a breakpoint (unlike the case alternatives they push), we introduced
the BRK_ALTS instruction to allow the debugger to set a case
continuation to stop at the breakpoint heading the alternative that is
taken. This is further described in `Note [Debugger: BRK_ALTS]`.

Fixes #26042