ghc-debugger: A step-through machine-interface debugger for GHC Haskell
The GHC debugger package provides a binary
ghc-debug-adapter that implements the Debug Adapter
Protocol (DAP) for debugging Haskell programs.
.
The Debug Adapter is implemented on top of the
ghc-debugger library which defines the primitive
debugging capabilities. These debugger features are
implemented by managing a GHC session and debugging it
through the GHC API.
.
The ghc-debug-adapter is transparently compatible with
most projects because it uses hie-bios to figure out the
right flags to invoke GHC with.
.
Additional information can be found in the README.
[Skip to Readme]
Modules
[Index] [Quick Jump]
Downloads
- ghc-debugger-0.1.0.0.tar.gz [browse] (Cabal source package)
- Package description (as included in the package)
Maintainer's Corner
For package maintainers and hackage trustees
Candidates
| Versions [RSS] | 0.1.0.0 |
|---|---|
| Change log | CHANGELOG.md |
| Dependencies | aeson (>=2.2.3 && <2.3), array (>=0.5.8 && <0.6), async (>=2.2.5 && <2.3), base (>4.21 && <5), binary (>=0.8.9 && <0.11), bytestring (>=0.12.1 && <0.13), containers (>=0.7 && <0.9), dap (>=0.2 && <1), directory (>=1.3.9 && <1.4), exceptions (>=0.10.9 && <0.11), filepath (>=1.5.4 && <1.6), ghc (>=9.13 && <9.14), ghc-debugger, ghci (>=9.13 && <9.14), hie-bios (>=0.15 && <0.16), mtl (>=2.3 && <3), process (>=1.6.25 && <1.7), text (>=2.1 && <2.3), unix (>=2.8.6 && <2.9) [details] |
| License | BSD-3-Clause |
| Author | Rodrigo Mesquita |
| Maintainer | rodrigo@well-typed.com |
| Category | Development |
| Home page | https://github.com/well-typed/ghc-debugger |
| Bug tracker | https://github.com/well-typed/ghc-debugger/issues |
| Source repo | head: git clone https://github.com/well-typed/ghc-debugger |
| Uploaded | by romes at 2025-05-08T15:23:17Z |
| Distributions | |
| Executables | ghc-debug-adapter |
| Downloads | 3 total (3 in the last 30 days) |
| Rating | (no votes yet) [estimated by Bayesian average] |
| Your Rating | |
| Status | Docs uploaded by user Build status unknown [no reports yet] |
Readme for ghc-debugger-0.1.0.0
[back to package description]GHC Debugger
Status: Work In Progress
We are working on a first class debugger for Haskell. It is still not ready for general consumption!
We will properly announce through the common channels the debugger when the first major release is ready.
Installation
[!WARNING]
ghc-debug-adapteris only supported by the latest nightly GHC version. The first release it will be compatible with is GHC 9.14.
To install and use the GHC debugger, you need the executable ghc-debug-adapter
and the VSCode extension haskell-debugger-extension.
Since ghc-debug-adapter implements the Debug Adapter Protocol
(DAP), it also supports
debugging with tools such as vim, neovim, or emacs -- as long as a DAP client is
installed and the launch arguments for ghc-debug-adapter configured.
To build, install, and run ghc-debug-adapter you currently need a nightly
version of GHC in PATH. You can get one using
GHCup, or building from source:
ghcup config add-release-channel https://ghc.gitlab.haskell.org/ghcup-metadata/ghcup-nightlies-0.0.7.yaml
ghcup install ghc latest-nightly
PATH=$(dirname $(ghcup whereis ghc latest-nightly)):$PATH cabal install exe:ghc-debug-adapter --enable-executable-dynamic --allow-newer=ghc-bignum,containers,time,ghc
To run the debugger, the same nightly version of GHC needs to be in PATH. Make sure the DAP client knows this. For instance, to launch VSCode use:
PATH=$(dirname $(ghcup whereis ghc latest-nightly)):$PATH code /path/to/proj
Currently, to install the debugger extension, download the .vsix file from the
GitHub release artifacts and drag and drop it to the extensions side panel. In
the future we will release it on the marketplace.
Usage
To use the debugger in VSCode, select the debugger tab, select Haskell Debugger,
and create a launch.json file by clicking the debugger settings icon (next to
the green run button).
The launch.json file contains some settings about the debugger session here.
Namely:
| Setting | Description |
|---|---|
entryFile |
the relative path from the project root to the file with the entry point for execution |
entryPoint |
the name of the function that is called to start execution |
entryArgs |
the arguments passed to the entryPoint. If the entryPoint is main, these arguments are passed as environment arguments (as in getArgs) rather than direct function arguments. |
extraGhcArgs |
additional flags to pass to the ghc invocation that loads the program for debugging. |
Change them accordingly.
To run the debugger, simply hit the green run button. See the Features section below for what is currently supported.
Note: Listing global variables is only supported in GHC versions newer than May 6, 2025
Related Work
ghc-debug-adapter is inspired by the original
haskell-debug-adapter by @phoityne.
ghc-debug-adapter improves on the original ideas implemented in
haskell-debug-adapter but makes them more robust by implementing the debugger
directly via the GHC API (similarly to HLS), rather than by communicating with a
custom ghci process.
We have been doing custom work on GHC to support debugging in a predictable,
robust, and more performant way. That is why ghc-debug-adapter is only
compatible with the latest and greatest GHC. If you want to debug using an older
GHC version (9.12 and older), please check out haskell-debug-adapter.
To implement the Debug Adapter Protocol (DAP) server part, we are using the
dap library by @dmjio.
dap is a framework for building language-agnostic DAP.
The ghc-debug-adapter is transparently compatible with most projects (simple,
Cabal, Stack, custom hie.yaml) because
it uses hie-bios to figure out the
right flags to prepare the GHC session with.
Features
Many not listed! Here are a few things:
Stepping
- Continue (resume execution forward)
- Next (step within local function)
- Step into (single step to next immediate tick)
- Step out (execute until end of function and break after the call)
In Reverse
- Local step backwards (ie reverse of Next)
- Single step backwards (ie reverse of Step into)
- Continue backwards (resume execution backwards until a breakpoint is hit)
Breakpoints
- [x] Module breakpoints
- [x] Function breakpoints
- [x] Exception breakpoints
- Data breakpoints
- Instruction breakpoints
Conditionals
- Conditional breakpoints (breakpoint is hit only if condition is satisfied)
- Hit conditional breakpoints (stop after N number of hits)