Haskell Debugger

We are working on a first class debugger for Haskell!

Installation

Please find up to date installation instructions on the project homepage!

[!WARNING] hdb can currently be compiled with GHC 9.14 The first release it will be compatible with is GHC 9.14.

To install and use the debugger, you need the executable hdb and the VSCode extension Haskell Debugger.

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 run the debugger, the same version of GHC which compiled it needs to be in PATH. Make sure the DAP client knows this. For instance, to launch VSCode with a specific GHC use:

PATH=/path/to/ghc-dir:$PATH code /path/to/proj

Prebuilt release binaries

The hdb-<version>-<arch>.tar.gz bindists attached to GitHub Releases unpack into a self-contained folder:

hdb-<version>-<arch>/
  hdb        # wrapper script -- put THIS on PATH, not bin/hdb
  bin/hdb    # the real executable
  lib/*      # bundled dynamic dependencies

The top-level hdb is a wrapper (modeled on haskell-language-server's) that locates a GHC installation on your machine matching the version and boot library ABIs hdb was built against, sets up the library search path, and then execs the real binary in bin/. If it can't find a matching GHC it will print an error explaining how to install one (e.g. via ghcup install ghc <version> --set); set HDB_WRAPPER_DEBUG=1 for more detail.

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). Now, it is also supported to just Run a file which contains a main function.

The launch.json file contains some settings about the debugger session here. Namely:

Change them accordingly.

You can also run the debugger as a server on a specific port by executing hdb server --port 12345. To connect VSCode to this server, add the field "debugServer": 12345 to your launch.json configuration.

To run the debugger, simply hit the green run button. See the Features section below for what is currently supported.

Multiple home units session

Multiple home units is supported but currently may require a workaround (issue is tracked by #38).

If your multiple home units session does not work by default (e.g. if you cannot set breakpoints on different units), and you do not have a hie.yaml file, you may want to try creating a hie.yaml file in the root of the workspace with:

cradle:
    cabal:
        component: "all"

Related Work

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 GHC 9.14. 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

• Module breakpoints
• Function breakpoints
• 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)

Custom Debug Visualizations

The user can extend the debugger visualization behavior (in a plugin sort of way) by implementing DebugView from haskell-debugger-view for the desired types.

We ship built-in custom instances for various base datatypes, such as String and (a, b), and for a core packages as well, such as Text, ByteString, Map and IntMap.

Here is an example of a completely custom DebugView instance for a user-defined datatype. You can also see how the IntMap is displayed as a pair of Int keys to their values as opposed as as a Bin/Tip tree mimicking its real definition:

When the package dependency closure includes haskell-debugger-view, we will use that unit specifically. When it is not in the dependencies, we will load a built-in version in memory.

Talks

MuniHac 2025: A modern step-through debugger for Haskell

ZuriHac 2025: Haskell Implementor's Workshop: The GHC Debugger

Building from source

Build hdb (using Cabal)

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

Build VS Code extension (using Nix)

cd vscode-extension
nix-build

Testing and Debugging

# Main testsuite (includes the golden tests, unit tests, and the integration
# tests that used to be run via the NodeJS @vscode-debugadapter-testsupport@
# library).
cabal run haskell-debugger-test

Debugging the debugger with the debugger

1. Run the debugger (e.g. through VSCode) with entryFile: hdb/Main.hs and arguments entryArgs: [server, --port, 12345]. This will start the debugger executable on port 12345 through the debugger.

2. Using VSCode, setup the launch.json for the project you want to test the debugger with debugServer: 12345. This will tell VSCode to connect to this port for the DAP server. This should trigger the breakpoint you set on the debugger in step (1).