breakpoint
Set breakpoints using a GHC plugin
Version on this page: | 0.1.3.0 |
LTS Haskell 22.36: | 0.1.4.0 |
Stackage Nightly 2024-10-05: | 0.1.4.0 |
Latest on Hackage: | 0.1.4.0 |
breakpoint-0.1.3.0@sha256:2a5dc6a715bdbdb12d2202a99f0c88b59e4f3aa02a7d82ec6debda89c455c3cf,2155
Module documentation for 0.1.3.0
Breakpoint
The ability to set breakpoints in a program can provide valuable insights when debugging. While GHCi has built-in support for setting breakpoints, it is not actively maintained and suffers from several critical limitations:
- It’s prohibitively buggy when used with concurrent programs, such as web servers.
- Breakpoints can only be set in interpreted code.
- Occasionally it simply doesn’t work at all.
The breakpoint
library solves these problems by implementing breakpoints as
a GHC plugin.
Usage
Add breakpoint
as a dependency to your project then enable breakpoints in a
module by adding {-# OPTIONS_GHC -fplugin Debug.Breakpoint #-}
to the top of
the file and importing the Debug.Breakpoint
module. You can then use the
breakpoint
, breakpointIO
, or breakpointM
functions as appropriate to set
a breakpoint.
breakpoint :: a -> a
is for use in pure code. Apart from the side-effect of setting a breakpoint, it is the identity function. The value passed tobreakpoint
will appear as a variable called*result
in the output.breakpointIO :: MonadIO m => m ()
is for monadic code that can perform IO.breakpointM :: Applicative f => f ()
is for arbitraryApplicative
contexts.
breakpoint
and breakpointM
both use unsafePerformIO
which means they are
at the mercy of the simplifier and all the other pitfalls of lazy IO. For this
reason, it’s generally preferable to use breakpointIO
in contexts that
support it.
Here’s an example module:
{-# OPTIONS_GHC -fplugin Debug.Breakpoint #-}
import Debug.Breakpoint
main :: IO ()
main = do
x <- getLine
let y = 2 :: Int
z = id :: Bool -> Bool
breakpointIO
pure ()
When the breakpoint expression gets evaluated, you will see terminal output such as
### Breakpoint Hit ###
(app/Main.hs:24:3-6)
x =
"input"
y =
2
z =
<Bool -> Bool>
Press enter to continue
showing the location of the breakpoint and the free variables that are visible from the callsite, this includes function arguments, let bindings, where binds, monadic binds, pattern binds, etc.
If the type of a value has a Show
instance then that will be used to generate
the printed value, otherwise the output will contain the type of the value
within angle brackets.
Execution of the program effectively halts on waiting for user input. In concurrent programs, all threads will be stopped, not just the one executing the breakpoint.
Querying variables
In contrast to the standard breakpoint functions which print out the values for
all current variables, the queryVars
, queryVarsM
, and queryVarsIO
functions first print the variables names and then initiate a prompt where you
can enter a specific variable name to have its value printed.
This is useful if you are only interested in certain values or if printing one or more values would result in a non-terminating process (an infinite data structure for example).
You can tab-complete variable names at the query prompt. Only the current thread is blocked while the prompt is active. To resume execution, press enter with a blank line.
Caveats
- Currently supports GHC version 9.2.x - 9.8.x
- Printing values may cause thunks to be evaluated earlier than they otherwise would which could be problematic for programs that rely heavily on laziness.
ApplicativeDo
can sometimes cause variables that are in scope to not be traced.- Implicit params are not currently supported
RecursiveDo
binds aren’t visible before they are bound, despite being in scope.- If there is anything buffered in
stdin
then that will interfere with the blocking mechanism. - On Windows or when using the non-threaded runtime, calls to
threadDelay
are not suspended by breakpoints in the sense that time continues to elapse, however they won’t unblock until the breakpoint finishes. - Variables being traced cannot have a type that contains type variables with
class constraints, otherwise you get a compiler error. This happens most
commonly with a where clause binding that lacks a type signature. You can
deal with this by using
excludeVars
or giving a type signature to the binding that doesn’t introduce such type variables.
Changes
Revision history for breakpoint
0.1.3.0 – 2023-10-28
- Support GHC 9.8.x
- Drop support for GHC 8.10.x and 9.0.x
0.1.2.2 – 2023-09-02
- Improvement to instance resolution for showing arbitrary values
- Strictly evaluate variable output before modifying timeouts
0.1.2.1 – 2023-03-12
- Support GHC 9.6.x
0.1.2.0 – 2022-11-18
breakpoint
andqueryVars
include a*result
binding in their output- Fix a bug breaking Windows compatibility
- Fix a bug with overlapping breakpoints and timeouts
0.1.1.1 – 2022-11-02
- Support
IsString
version of string literals inexcludeVars
0.1.1.0 – 2022-10-30
- Support for GHC 9.4.*
- Values are pretty printed using
pretty-simple
- Timeouts are suspended during breakpoints for GHC >= 9.2 and non-windows
- Fix a bug with monadic binds in do blocks
- Variable names are no longer visible in their definition body
- Adds
excludeVars
to ingore a list of vars, especially those that don’t compile
0.1.0.0 – YYYY-mm-dd
- First version. Released on an unsuspecting world.