debugging.md

Debugging

To profile a component of the current project, pass the --profile flag to stack build.

The flag:

• for project packages, turns on the Cabal flag --enable-profiling;
• turns on the Cabal flag --enable-library-profiling; and
• passes GHC's +RTS -p runtime options to any test suites and benchmarks.

For example the following command will build the my-tests testsuite with profiling options and create a my-tests.prof file in the current directory as a result of the test run.

stack test --profile my-tests

The my-tests.prof file now contains time and allocation info for the test run.

To create a profiling report for an executable, e.g. my-exe, you can command:

stack exec --profile -- my-exe +RTS -p

For more fine-grained control of compilation options there are the --library-profiling flag and --executable-profiling flag.

The --library-profiling flag:

• turns on the Cabal flag --enable-library-profiling; and
• passes GHC's +RTS -p runtime options to any test suites and benchmarks.

The --executable-profiling flag:

• for project packages, turns on the Cabal flag --enable-profiling;
• turns on the Cabal flag --enable-library-profiling; and
• passes GHC's +RTS -p runtime options to any test suites and benchmarks.

To enable compilation with profiling options by default you can add the following to a project-level or global YAML configuration file:

build:
  library-profiling: true
  executable-profiling: true

Further reading

For more commands and uses, see the official GHC chapter on profiling, the Haskell wiki, and the chapter on profiling in Real World Haskell.

Tracing

To generate a backtrace in case of exceptions during a test or benchmarks run, use the --trace flag. Like --profile this compiles with profiling options, but adds the +RTS -xc runtime option.

Debugging symbols

Building with debugging symbols in the DWARF information is supported by Stack. This can be done by passing the flag --ghc-options="-g" and also to override the default behaviour of stripping executables of debugging symbols by passing either one of the following flags: --no-strip, --no-library-stripping or --no-executable-stripping.

In Windows, GDB can be installed to debug an executable with stack exec -- pacman -S gdb. Windows' Visual Studio compiler's debugging format PDB is not supported at the moment. This might be possible by separating debugging symbols and converting their format. Or as an option when using the LLVM backend.