haskell-debugger: A step-through machine-interface debugger for GHC Haskell

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

[missing-upper-bounds] On executable 'hdb', these packages miss upper bounds: - transformers - time Please add them. There is more information at https://pvp.haskell.org/

The GHC debugger package provides a standalone executable called hdb which can be used to step-through Haskell programs and can act as a Debug Adapter Protocol (DAP) server in the --server mode for debugging Haskell programs. . The Debug Adapter is implemented on top of the haskell-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 hdb 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]

Properties

Versions	0.5.0.0, 0.5.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), base16-bytestring (>=1.0.2.0 && <1.1), binary (>=0.8.9 && <0.11), bytestring (>=0.12.1 && <0.13), co-log-core (>=0.3.2.5 && <0.4), containers (>=0.7 && <0.9), cryptohash-sha1 (>=0.11.101.0 && <0.12), dap (>=0.2 && <1), directory (>=1.3.9.0 && <1.4), exceptions (>=0.10.9 && <0.11), filepath (>=1.5.4 && <1.6), ghc (>=9.14 && <9.16), ghci (>=9.14 && <9.16), haskell-debugger, hie-bios (>=0.15 && <0.18), implicit-hie (>=0.1.4.0 && <0.2), mtl (>=2.3 && <3), prettyprinter (>=1.7.1 && <2), process (>=1.6.25 && <1.7), text (>=2.1 && <2.3), time, transformers, 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/haskell-debugger
Bug tracker	https://github.com/well-typed/haskell-debugger/issues
Source repo	head: git clone https://github.com/well-typed/haskell-debugger
Uploaded	by romes at 2025-08-27T08:00:05Z

Modules

GHC
- GHC.Debugger
  - GHC.Debugger.Breakpoint
  - GHC.Debugger.Evaluation
  - Interface
    - GHC.Debugger.Interface.Messages
  - GHC.Debugger.Monad
  - GHC.Debugger.Runtime
    - Term
      - GHC.Debugger.Runtime.Term.Cache
      - GHC.Debugger.Runtime.Term.Key
  - GHC.Debugger.Session
  - GHC.Debugger.Stopped
    - GHC.Debugger.Stopped.Variables
  - GHC.Debugger.Utils

Downloads

haskell-debugger-0.5.0.0.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

Package maintainers

romes

For package maintainers and hackage trustees

edit package information

Readme for haskell-debugger-0.5.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.

Hackage badge

Installation

[!WARNING] hdb is 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 hdb and the VSCode extension haskell-debugger-extension.

Since hdb 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 hdb configured.

To build, install, and run hdb 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 haskell-debugger:hdb --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

hdb is inspired by the original haskell-debug-adapter by @phoityne.

hdb 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 hdb 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 hdb 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

Conditionals

Conditional breakpoints (breakpoint is hit only if condition is satisfied)
Hit conditional breakpoints (stop after N number of hits)

Building from source

To build hdb:

cabal build -w /path/to/recent/ghc exe:hdb

To build the VSCode extension

cd vscode-extension
nix-build

Testing

cd test/integration-tests
nix-shell
make GHC=/path/to/recent/ghc \
     DEBUGGER=$(cd ../.. && cabal list-bin -w /path/to/recent/ghc exe:hdb)