Commit 8536b7f8 authored by Ben Gamari's avatar Ben Gamari 🐢
Browse files

users-guide: Rework and finish debug flag documentation

This documentation was incomplete and not terribly well organized. Given that
I've spent a lot of time searching through this page, I figured it is perhaps
worth it to clean it up a bit.
parent 7e790b38
......@@ -8,6 +8,8 @@ Debugging the compiler
HACKER TERRITORY. HACKER TERRITORY. (You were warned.)
.. contents:: Dump flags
.. _dumping-output:
Dumping out compiler intermediate structures
......@@ -17,354 +19,362 @@ Dumping out compiler intermediate structures
single: dumping GHC intermediates
single: intermediate passes, output
``-ddump-`` ⟨pass⟩
.. index::
single: -ddump options
.. ghc-flag:: -ddump-to-file
:shortdesc: Dump to files instead of stdout
:type: dynamic
:category:
Make a debugging dump after pass ``<pass>`` (may be common enough to
need a short form…). You can get all of these at once (*lots* of
output) by using ``-v5``, or most of them with ``-v4``. You can
prevent them from clogging up your standard output by passing
:ghc-flag:`-ddump-to-file`. Some of the most useful ones are:
Causes the output from all of the flags listed below to be dumped
to a file. The file name depends upon the output produced; for instance,
output from :ghc-flag:`-ddump-simpl` will end up in
:file:`{module}.dump-simpl`.
.. ghc-flag:: -ddump-to-file
:shortdesc: Dump to files instead of stdout
:type: dynamic
:category:
.. ghc-flag:: -ddump-json
:shortdesc: Dump error messages as JSON documents
:type: dynamic
:category:
Causes the output from all of the flags listed below to be dumped
to a file. The file name depends upon the output produced; for instance,
output from :ghc-flag:`-ddump-simpl` will end up in
:file:`{module}.dump-simpl`.
Dump error messages as JSON documents. This is intended to be consumed
by external tooling. A good way to use it is in conjunction with
:ghc-flag:`-ddump-to-file`.
.. ghc-flag:: -ddump-parsed
:shortdesc: Dump parse tree
:type: dynamic
:category:
.. ghc-flag:: -dshow-passes
:shortdesc: Print out each pass name as it happens
:type: dynamic
:category:
Dump parser output
Print out each pass name, its runtime and heap allocations as it happens.
Note that this may come at a slight performance cost as the compiler will
be a bit more eager in forcing pass results to more accurately account for
their costs.
.. ghc-flag:: -ddump-parsed-ast
:shortdesc: Dump parser output as a syntax tree
:type: dynamic
:category:
Two types of messages are produced: Those beginning with ``***`` are
denote the beginning of a compilation phase whereas those starting with
``!!!`` mark the end of a pass and are accompanied by allocation and
runtime statistics.
Dump parser output as a syntax tree
.. ghc-flag:: -dfaststring-stats
:shortdesc: Show statistics for fast string usage when finished
:type: dynamic
:category:
.. ghc-flag:: -ddump-rn
:shortdesc: Dump renamer output
:type: dynamic
:category:
Show statistics on the usage of fast strings by the compiler.
Dump renamer output
.. ghc-flag:: -dppr-debug
:shortdesc: Turn on debug printing (more verbose)
:type: dynamic
:category:
.. ghc-flag:: -ddump-rn-ast
:shortdesc: Dump renamer output as a syntax tree
:type: dynamic
:category:
Debugging output is in one of several "styles." Take the printing of
types, for example. In the "user" style (the default), the
compiler's internal ideas about types are presented in Haskell
source-level syntax, insofar as possible. In the "debug" style
(which is the default for debugging output), the types are printed
in with explicit foralls, and variables have their unique-id
attached (so you can check for things that look the same but
aren't). This flag makes debugging output appear in the more verbose
debug style.
Dump renamer output as a syntax tree
.. ghc-flag:: -ddump-tc
:shortdesc: Dump typechecker output
:type: dynamic
:category:
GHC is a large program consisting of a number of stages. You can tell GHC to
dump information from various stages of compilation using the ``-ddump-⟨pass⟩``
flags listed below. Note that some of these tend to produce a lot of output.
You can prevent them from clogging up your standard output by passing
:ghc-flag:`-ddump-to-file`.
Dump typechecker output
Front-end
~~~~~~~~~
.. ghc-flag:: -ddump-tc-ast
:shortdesc: Dump typechecker output as a syntax tree
:type: dynamic
:category:
These flags dump various information from GHC's frontend. This includes the
parser and interface file reader.
Dump typechecker output as a syntax tree
.. ghc-flag:: -ddump-parsed
:shortdesc: Dump parse tree
:type: dynamic
:category:
.. ghc-flag:: -ddump-splices
:shortdesc: Dump TH spliced expressions, and what they evaluate to
:type: dynamic
:category:
Dump parser output
Dump Template Haskell expressions that we splice in, and what
Haskell code the expression evaluates to.
.. ghc-flag:: -ddump-parsed-ast
:shortdesc: Dump parser output as a syntax tree
:type: dynamic
:category:
.. ghc-flag:: -dth-dec-file=⟨file⟩
:shortdesc: Show evaluated TH declarations in a .th.hs file
:type: dynamic
:category:
Dump parser output as a syntax tree
Dump expansions of all top-level Template Haskell splices into ⟨file⟩.
.. ghc-flag:: -ddump-if-trace
:shortdesc: Trace interface files
:type: dynamic
:category:
.. ghc-flag:: -ddump-types
:shortdesc: Dump type signatures
:type: dynamic
:category:
Make the interface loader be *real* chatty about what it is up to.
Dump a type signature for each value defined at the top level of
the module. The list is sorted alphabetically. Using
:ghc-flag:`-dppr-debug` dumps a type signature for all the imported and
system-defined things as well; useful for debugging the
compiler.
.. ghc-flag:: -ddump-deriv
:shortdesc: Dump deriving output
:type: dynamic
:category:
Type-checking and renaming
~~~~~~~~~~~~~~~~~~~~~~~~~~
Dump derived instances
These flags dump various information from GHC's typechecker and renamer.
.. ghc-flag:: -ddump-ds
:shortdesc: Dump desugarer output
:type: dynamic
:category:
.. ghc-flag:: -ddump-tc-trace
:shortdesc: Trace typechecker
:type: dynamic
:category:
Dump desugarer output
Make the type checker be *real* chatty about what it is up to.
.. ghc-flag:: -ddump-spec
:shortdesc: Dump specialiser output
:type: dynamic
:category:
.. ghc-flag:: -ddump-rn-trace
:shortdesc: Trace renamer
:type: dynamic
:category:
Dump output of specialisation pass
Make the renamer be *real* chatty about what it is up to.
.. ghc-flag:: -ddump-rules
:shortdesc: Dump rewrite rules
:type: dynamic
:category:
.. ghc-flag:: -ddump-ec-trace
:shortdesc: Trace exhaustiveness checker
:type: dynamic
:category:
Dumps all rewrite rules specified in this module; see
:ref:`controlling-rules`.
Make the pattern match exhaustiveness checker be *real* chatty about
what it is up to.
.. ghc-flag:: -ddump-rule-firings
:shortdesc: Dump rule firing info
:type: dynamic
:category:
.. ghc-flag:: -ddump-rn-stats
:shortdesc: Renamer stats
:type: dynamic
:category:
Dumps the names of all rules that fired in this module
Print out summary of what kind of information the renamer had to
bring in.
.. ghc-flag:: -ddump-rule-rewrites
:shortdesc: Dump detailed rule firing info
:type: dynamic
:category:
.. ghc-flag:: -ddump-rn
:shortdesc: Dump renamer output
:type: dynamic
:category:
Dumps detailed information about all rules that fired in this
module
Dump renamer output
.. ghc-flag:: -ddump-vect
:shortdesc: Dump vectoriser input and output
:type: dynamic
:category:
.. ghc-flag:: -ddump-rn-ast
:shortdesc: Dump renamer output as a syntax tree
:type: dynamic
:category:
Dumps the output of the vectoriser.
Dump renamer output as a syntax tree
.. ghc-flag:: -ddump-simpl
:shortdesc: Dump final simplifier output
:type: dynamic
:category:
.. ghc-flag:: -ddump-tc
:shortdesc: Dump typechecker output
:type: dynamic
:category:
Dump simplifier output (Core-to-Core passes)
Dump typechecker output
.. ghc-flag:: -ddump-inlinings
:shortdesc: Dump inlining info
:type: dynamic
:category:
.. ghc-flag:: -ddump-tc-ast
:shortdesc: Dump typechecker output as a syntax tree
:type: dynamic
:category:
Dumps inlining info from the simplifier. Note that if used in
conjunction with :ghc-flag:`-dverbose-core2core` the compiler will
also dump the inlinings that it considers but passes up, along with
its rationale.
Dump typechecker output as a syntax tree
.. ghc-flag:: -ddump-stranal
:shortdesc: Dump strictness analyser output
:type: dynamic
:category:
.. ghc-flag:: -ddump-splices
:shortdesc: Dump TH spliced expressions, and what they evaluate to
:type: dynamic
:category:
Dump strictness analyser output
Dump Template Haskell expressions that we splice in, and what
Haskell code the expression evaluates to.
.. ghc-flag:: -ddump-str-signatures
:shortdesc: Dump strictness signatures
:type: dynamic
:category:
.. ghc-flag:: -dth-dec-file=⟨file⟩
:shortdesc: Show evaluated TH declarations in a .th.hs file
:type: dynamic
:category:
Dump strictness signatures
Dump expansions of all top-level Template Haskell splices into ⟨file⟩.
.. ghc-flag:: -ddump-cse
:shortdesc: Dump CSE output
:type: dynamic
:category:
.. ghc-flag:: -ddump-types
:shortdesc: Dump type signatures
:type: dynamic
:category:
Dump common subexpression elimination (CSE) pass output
Dump a type signature for each value defined at the top level of
the module. The list is sorted alphabetically. Using
:ghc-flag:`-dppr-debug` dumps a type signature for all the imported and
system-defined things as well; useful for debugging the
compiler.
.. ghc-flag:: -ddump-worker-wrapper
:shortdesc: Dump worker-wrapper output
:type: dynamic
:category:
.. ghc-flag:: -ddump-deriv
:shortdesc: Dump deriving output
:type: dynamic
:category:
Dump worker/wrapper split output
Dump derived instances
.. ghc-flag:: -ddump-occur-anal
:shortdesc: Dump occurrence analysis output
:type: dynamic
:category:
Dump "occurrence analysis" output
Core representation and simplification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. ghc-flag:: -ddump-prep
:shortdesc: Dump prepared core
:type: dynamic
:category:
These flags dump various phases of GHC's Core-to-Core pipeline. This begins with
the desugarer and includes the simplifier, worker-wrapper transformation, the
rule engine, the specialiser, the strictness/occurrence analyser, and a common
subexpression elimination pass.
Dump output of Core preparation pass
.. ghc-flag:: -ddump-core-stats
:shortdesc: Print a one-line summary of the size of the Core program at the
end of the optimisation pipeline
:type: dynamic
:category:
.. ghc-flag:: -ddump-stg
:shortdesc: Dump final STG
:type: dynamic
:category:
Print a one-line summary of the size of the Core program at the end
of the optimisation pipeline.
Dump output of STG-to-STG passes
.. ghc-flag:: -ddump-ds
:shortdesc: Dump desugarer output
:type: dynamic
:category:
.. ghc-flag:: -ddump-cmm
:shortdesc: Dump the final C-- output
:type: dynamic
:category:
Dump desugarer output
Dump the result of the C-- pipeline processing
.. ghc-flag:: -ddump-simpl-iterations
:shortdesc: Dump output from each simplifier iteration
:type: dynamic
:category:
.. ghc-flag:: -ddump-cmm-from-stg
:shortdesc: Dump STG-to-C-- output
:type: dynamic
:category:
Show the output of each *iteration* of the simplifier (each run of
the simplifier has a maximum number of iterations, normally 4). This
outputs even more information than ``-ddump-simpl-phases``.
Dump the result of STG-to-C-- conversion
.. ghc-flag:: -ddump-simpl-stats
:shortdesc: Dump simplifier stats
:type: dynamic
:category:
.. ghc-flag:: -ddump-cmm-verbose
:shortdesc: Show output from each C-- pipeline pass
:type: dynamic
:category:
Dump statistics about how many of each kind of transformation too
place. If you add ``-dppr-debug`` you get more detailed information.
Dump output from all C-- pipeline stages. In case of
``.cmm`` compilation this also dumps the result of
file parsing.
.. ghc-flag:: -dverbose-core2core
:shortdesc: Show output from each core-to-core pass
:type: dynamic
:category:
.. ghc-flag:: -ddump-opt-cmm
:shortdesc: Dump the results of C-- to C-- optimising passes
:type: dynamic
:category:
Show the output of the intermediate Core-to-Core pass. (*lots* of output!)
So: when we're really desperate:
Dump the results of C-- to C-- optimising passes.
.. code-block:: sh
.. ghc-flag:: -ddump-asm
:shortdesc: Dump assembly
:type: dynamic
:category:
% ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs
Dump assembly language produced by the :ref:`native code
generator <native-code-gen>`
.. ghc-flag:: -ddump-spec
:shortdesc: Dump specialiser output
:type: dynamic
:category:
.. ghc-flag:: -ddump-llvm
:shortdesc: Dump LLVM intermediate code.
Implies :ghc-flag:`-fllvm`.
:type: dynamic
:category:
Dump output of specialisation pass
:implies: :ghc-flag:`-fllvm`
.. ghc-flag:: -ddump-rules
:shortdesc: Dump rewrite rules
:type: dynamic
:category:
LLVM code from the :ref:`LLVM code generator <llvm-code-gen>`
Dumps all rewrite rules specified in this module; see
:ref:`controlling-rules`.
.. ghc-flag:: -ddump-bcos
:shortdesc: Dump interpreter byte code
:type: dynamic
:category:
.. ghc-flag:: -ddump-rule-firings
:shortdesc: Dump rule firing info
:type: dynamic
:category:
Dump byte-code compiler output
Dumps the names of all rules that fired in this module
.. ghc-flag:: -ddump-foreign
:shortdesc: Dump ``foreign export`` stubs
:type: dynamic
:category:
.. ghc-flag:: -ddump-rule-rewrites
:shortdesc: Dump detailed rule firing info
:type: dynamic
:category:
dump foreign export stubs
Dumps detailed information about all rules that fired in this
module
.. ghc-flag:: -ddump-json
:shortdesc: Dump error messages as JSON documents
:type: dynamic
:category:
.. ghc-flag:: -ddump-vect
:shortdesc: Dump vectoriser input and output
:type: dynamic
:category:
Dump error messages as JSON documents. This is intended to be consumed
by external tooling. A good way to use it is in conjunction with
:ghc-flag:`-ddump-to-file`.
Dumps the output of the vectoriser.
.. ghc-flag:: -ddump-simpl-iterations
:shortdesc: Dump output from each simplifier iteration
.. ghc-flag:: -ddump-simpl
:shortdesc: Dump final simplifier output
:type: dynamic
:category:
Show the output of each *iteration* of the simplifier (each run of
the simplifier has a maximum number of iterations, normally 4). This
outputs even more information than ``-ddump-simpl-phases``.
Dump simplifier output (Core-to-Core passes)
.. ghc-flag:: -ddump-simpl-stats
:shortdesc: Dump simplifier stats
.. ghc-flag:: -ddump-inlinings
:shortdesc: Dump inlining info
:type: dynamic
:category:
Dump statistics about how many of each kind of transformation too
place. If you add ``-dppr-debug`` you get more detailed information.
Dumps inlining info from the simplifier. Note that if used in
conjunction with :ghc-flag:`-dverbose-core2core` the compiler will
also dump the inlinings that it considers but passes up, along with
its rationale.
.. ghc-flag:: -ddump-if-trace
:shortdesc: Trace interface files
.. ghc-flag:: -ddump-stranal
:shortdesc: Dump strictness analyser output
:type: dynamic
:category:
Make the interface loader be *real* chatty about what it is up to.
Dump strictness analyser output
.. ghc-flag:: -ddump-tc-trace
:shortdesc: Trace typechecker
.. ghc-flag:: -ddump-str-signatures
:shortdesc: Dump strictness signatures
:type: dynamic
:category:
Make the type checker be *real* chatty about what it is up to.
Dump strictness signatures
.. ghc-flag:: -ddump-vt-trace
:shortdesc: Trace vectoriser
.. ghc-flag:: -ddump-cse
:shortdesc: Dump CSE output
:type: dynamic
:category:
Make the vectoriser be *real* chatty about what it is up to.
Dump common subexpression elimination (CSE) pass output
.. ghc-flag:: -ddump-rn-trace
:shortdesc: Trace renamer
.. ghc-flag:: -ddump-worker-wrapper
:shortdesc: Dump worker-wrapper output
:type: dynamic
:category:
Make the renamer be *real* chatty about what it is up to.
Dump worker/wrapper split output
.. ghc-flag:: -ddump-ec-trace
:shortdesc: Trace exhaustiveness checker
.. ghc-flag:: -ddump-occur-anal
:shortdesc: Dump occurrence analysis output
:type: dynamic
:category:
Make the pattern match exhaustiveness checker be *real* chatty about
what it is up to.
Dump "occurrence analysis" output
.. ghc-flag:: -ddump-rn-stats
:shortdesc: Renamer stats
.. ghc-flag:: -ddump-vt-trace
:shortdesc: Trace vectoriser
:type: dynamic
:category:
Print out summary of what kind of information the renamer had to
bring in.
Make the vectoriser be *real* chatty about what it is up to.
.. ghc-flag:: -dverbose-core2core
:shortdesc: Show output from each core-to-core pass
.. ghc-flag:: -ddump-prep
:shortdesc: Dump prepared core
:type: dynamic
:category:
Show the output of the intermediate Core-to-Core pass. (*lots* of output!)
So: when we're really desperate:
Dump output of Core preparation pass
.. code-block:: sh
% ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs
STG representation
~~~~~~~~~~~~~~~~~~
These flags dump various phases of GHC's STG pipeline.
.. ghc-flag:: -ddump-stg
:shortdesc: Dump final STG
:type: dynamic
:category:
Dump output of STG-to-STG passes
.. ghc-flag:: -dverbose-stg2stg
:shortdesc: Show output from each STG-to-STG pass
......@@ -373,51 +383,202 @@ Dumping out compiler intermediate structures
Show the output of the intermediate STG-to-STG pass. (*lots* of output!)
.. ghc-flag:: -dshow-passes
:shortdesc: Print out each pass name as it happens
C-- representation
~~~~~~~~~~~~~~~~~~
These flags dump various phases of GHC's C-- pipeline.
.. ghc-flag:: -ddump-cmm-verbose
:shortdesc: Show output from each C-- pipeline pass
:type: dynamic
:category:
Print out each pass name, its runtime and heap allocations as it happens.
Note that this may come at a slight performance cost as the compiler will
be a bit more eager in forcing pass results to more accurately account for
their costs.
Dump output from all C-- pipeline stages. In case of
``.cmm`` compilation this also dumps the result of
file parsing.
Two types of messages are produced: Those beginning with ``***`` are
denote the beginning of a compilation phase whereas those starting with
``!!!`` mark the end of a pass and are accompanied by allocation and
runtime statistics.
.. ghc-flag:: -ddump-cmm-from-stg
:shortdesc: Dump STG-to-C-- output
:type: dynamic
:category:
.. ghc-flag:: -ddump-core-stats
:shortdesc: Print a one-line summary of the size of the Core program at the
end of the optimisation pipeline
Dump the result of STG-to-C-- conversion