debug-pp: A preprocessor for the debug package

[ bsd3, debugging, program ] [ Propose Tags ]
Versions, 0.1.1
Dependencies aeson, base (>=4.7 && <5), debug‑hoed, directory, filepath, yaml [details]
License BSD-3-Clause
Copyright All Rights Reserved
Author Pepe Iborra
Category Debugging
Home page
Bug tracker
Source repo head: git clone
Uploaded by PepeIborra at Sat Jan 20 16:09:12 UTC 2018
Executables debug-pp
Downloads 142 total (11 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2018-01-20 [all 3 reports]
Hackage Matrix CI

A preprocessor to automate the instrumentation of a module for the debug package

[Skip to Readme]


Maintainer's Corner

For package maintainers and hackage trustees

Readme for debug-pp-0.1.1

[back to package description]

Travis Build Status Hackage Stackage Nightly


A preprocessor for streamlining the debug instrumentation of a module or a package.


debug-pp is a Haskell source preprocessor that performs the steps a programmer would need to follow in order to debug a module with the debug package. That is:

  • append an import for the Debug module, and
  • wrap the body in a debug splice using a TH declaration quasiquote.


usage: debug-pp [FILENAME] [SOURCE] [DEST]
Instrument Haskell module for debugging from SOURCE (derived from FILENAME) and write
standard Haskell to DEST.
If no FILENAME, use SOURCE as the original name.
If no DEST or if DEST is `-', write to standard output.
If no SOURCE or if SOURCE is `-', read standard input.

To instrument a module, add the following pragma to the top of the file:

{-# OPTIONS -F -pgmF debug-pp #-}

To instrument an entire program, add the following line to your stack descriptor, or if you don't use stack, to your cabal descriptor:

ghc-options: -F -pgmF debug-pp

In both cases you will also need to modify your Cabal descriptor in order to:

  • add a dependency on the debug package, and
  • add a build tool depends on debug-pp (required Cabal 2.0) :
  build-tool-depends: debug-pp:debug-pp


The tool is customizable to some extent. It tries to find a config file in the following order:

  1. .debug-pp.yaml in the current directory (useful for per-directory settings)
  2. .debug-pp.yaml in the nearest ancestor directory (useful for per-project settings)
  3. debug-pp/config.yaml in the platform’s configuration directory (on Windows, it is %APPDATA%, elsewhere it defaults to ~/.config and can be overridden by the XDG_CONFIG_HOME environment variable; useful for user-wide settings)
  4. .debug-pp.yaml in your home directory (useful for user-wide settings)
  5. The default settings.

Use debug-pp --defaults > .debug-pp.yaml to dump a well-documented default configuration to a file, this way you can get started quickly.

The configuration options include:

  • Exclude modules by name.
  • Instrument the main function to launch a web browser upon completion.
  • Select which language extensions are included automatically.
  • Configure the debug-hoed instrumentation to include e.g. deriving Generic and Observable instances


  • Debugging individual functions is often impractical due to the declaration groups restriction of Template Haskell. Therefore, it's often easier to debug an entire module.

  • However, error messages are much worse for TH quoted code. Errors like Not in scope: data constructor Foo in line X become Not in scope: Foo, in the TH quotation ENTIRE MODULE HERE.

  • Personally, quoting/unquoting the module by hand is annoying. Having a preprocessor do this for me is convenient, and can be easily tied to a Cabal flag or a stack command line arg.