GHC step-through debugger

A modern debugger and debug adapter for Haskell — compatible with VSCode, Vim, and Emacs

All the features:

Installation Guide

The haskell-debugger executable hdb is a standalone application which uses the GHC library to implement the Debug Adapter Protocol (DAP) for Haskell.

Any editor which supports DAP can be configured to step-through Haskell code by using the hdb tool. This includes VSCode, Vim and Emacs.

First, the executable must be made available in PATH. It can be downloaded and installed from hackage with: 

cabal install haskell-debugger --allow-newer=base,time,containers,ghc,ghc-bignum,template-haskell --enable-executable-dynamic

Second, your editor must be taught how to launch hdb:

Editor Description
VSCode Install the Haskell Debugger VSCode extension, select the debugger tab, and click the "Create launch.json" button followed by the green "Run" button.
Nvim Install the nvim-dap plugin and configure it accordingly
Emacs Install and configure a DAP client plugin. Do submit the instructions in a PR

Usage varies depending on the editor. Please consult the editor documentation regarding the debugger controls, such as Debug code with Visual Studio Code

Configuration

The debugger is launched with the following properties customizing the debugging session. In VSCode, these options can be set in the launch.json file.

Setting Description
projectRoot the full path to the project root; this is typically ${workspaceFolder}, a value which is interpolated by the editor with the actual path
entryFile the relative path from the project root to the file with the entry point for execution (e.g. app/Main.hs)
entryPoint the name of the function that is called to start execution (e.g. main)
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 (e.g. []).
extraGhcArgs additional flags to pass to the ghc invocation that loads the program for debugging (e.g. [])

GHC Developers: Debugging GHC itself

You can debug GHC with the debugger now! The debugger version must be at least v0.12.2. Assuming you have installed hdb and the DAP plugin for your editor, here are the steps to run GHC under the debugger (s.t. you can set breakpoints in the editor):

  1. Make sure you're using GHC 9.14 as the boot compiler and available in PATH
  2. Build the compiler normally with the desired build flavour in hadrian
  3. Configure the debugger launch arguments as follows
Setting Value
entryFile "ghc/Main.hs"
entryArgs ["-B/path/to/ghc/_build/stage0/lib/", "Test.hs"]

Where Test.hs is the program which the GHC you are debugging will compile. You can also pass whatever additional arguments you desire to the GHC being debugged in entryArgs.

Please try it out and send me an e-mail if you can't!

Talks