6a34431c843d91e3b7e45de31cf0fa5981fa2140
[ghc.git] / docs / users_guide / debug-info.rst
1 Debugging compiled programs
2 ===========================
3
4 Since the 7.10 release GHC can emit a debugging information to help debugging
5 tools understand the code that GHC produces. This debugging information is
6 useable by most UNIX debugging tools.
7
8 .. ghc-flag:: -g
9               -g⟨n⟩
10
11     :since: 7.10, numeric levels since 8.0
12
13     Emit debug information in object code. Currently only DWARF debug
14     information is supported on x86-64 and i386. Currently debug levels 0
15     through 3 are accepted, with 0 disabling debug information production.
16     Levels 1 through 3 are functionally equivalent.
17
18
19 Tutorial
20 --------
21
22 Let's consider a simple example,
23
24 .. code-block:: hs
25    :linenos:
26
27     -- fib.hs
28     fib :: Int -> Int
29     fib 0 = 0
30     fib 1 = 1
31     fib n = fib (n-1) + fib (n-2)
32
33     main :: IO ()
34     main = print $ fib 50
35
36 Let's first see how execution flows through this program. We start by telling
37 GHC that we want debug information,
38
39 .. code-block:: sh
40
41     $ ghc -g -rtsopts fib.hs
42
43 Here we used the ``-g`` option to inform GHC that it should add debugging
44 information in the produced binary. There are three levels of debugging
45 output: ``-g0`` (no debugging information, the default), ``-g1`` (sufficient for
46 basic backtraces), ``-g2`` (or just ``-g`` for short; emitting everything GHC knows).
47 Note that this debugging information does not affect the optimizations performed
48 by GHC.
49
50 .. tip::
51    Under Mac OS X debug information is kept apart from the executable. After
52    compiling the executable you'll need to use the ``dsymutil`` utility to
53    extract the debugging information and place them in the debug archive,
54
55    .. code-block:: sh
56
57       $ dsymutil fib
58
59    This should produce a file named ``fib.dSYM``.
60
61 Now let's have a look at the flow of control. For this we can just start our
62 program under ``gdb`` (or an equivalent debugger) as we would any other native
63 executable,
64
65 .. code-block:: none
66
67     $ gdb --args ./Fib +RTS -V0
68     Reading symbols from Fib...done.
69     (gdb) run
70     Starting program: /opt/exp/ghc/ghc-dwarf/Fib
71     [Thread debugging using libthread_db enabled]
72     Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
73     ^C
74     Program received signal SIGINT, Interrupt.
75     0x000000000064fc7c in cfy4_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:424
76     424     minusInteger x y = inline plusInteger x (inline negateInteger y)
77     (gdb)
78
79 Here we have used the runtime system's ``-V0`` option to disable the RTS's
80 periodic timer which may interfere with our debugging session. Upon breaking
81 into the program ``gdb`` shows us a location in our source program corresponding
82 to the current point of execution.
83
84 Moreover, we can ask ``gdb`` to tell us the flow of execution that lead us to
85 this point in the program,
86
87 .. code-block:: none
88
89    (gdb) bt
90    #0  0x000000000064fc7c in cfy4_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:424
91    #1  0x00000000006eb0c0 in ?? ()
92    #2  0x000000000064301c in cbuV_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:323
93    #3  0x000000000064311b in integerzmgmp_GHCziIntegerziType_eqInteger_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:312
94    #4  0x0000000000406eca in roz_info () at Fib.hs:2
95    #5  0x00000000006eb0c0 in ?? ()
96    #6  0x000000000064f075 in cfru_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:412
97    #7  0x00000000006eb0c0 in ?? ()
98    #8  0x000000000064f075 in cfru_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:412
99    #9  0x00000000006eb0c0 in ?? ()
100    #10 0x000000000064eefe in integerzmgmp_GHCziIntegerziType_plusInteger_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:393
101    ...
102    #64 0x0000000000643ac8 in integerzmgmp_GHCziIntegerziType_ltIntegerzh_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:343
103    #65 0x00000000004effcc in base_GHCziShow_zdwintegerToString_info () at libraries/base/GHC/Show.hs:443
104    #66 0x00000000004f0795 in base_GHCziShow_zdfShowIntegerzuzdcshow_info () at libraries/base/GHC/Show.hs:145
105    #67 0x000000000048892b in cdGW_info () at libraries/base/GHC/IO/Handle/Text.hs:595
106    #68 0x0000000000419cb2 in base_GHCziBase_thenIO1_info () at libraries/base/GHC/Base.hs:1072
107
108
109 .. hint::
110
111     Here we notice the first bit of the stack trace has many unidentified stack
112     frames at address ``0x006eb0c0``. If we ask ``gdb`` about this location, we
113     find that these frames are actually STG update closures,
114
115     .. code-block:: none
116
117         (gdb) print/a 0x006eb0c0
118         $1 = 0x6eb0c0 <stg_upd_frame_info>
119
120     The reason ``gdb`` doesn't show this symbol name in the backtrace output is an
121     infidelity in its interpretation of debug information, which assumes an
122     invariant preserved in C but not Haskell programs. Unfortunately it is
123     necessary to work around this manually until this behivior is fixed
124     upstream.
125
126 .. note::
127
128     Because of the aggressive optimization that GHC performs to the programs it
129     compiles it is quite difficult to pin-point exactly which point in the source
130     program a given machine instruction should be attributed to. In fact,
131     internally GHC associates each instruction with a **set** of source
132     locations. When emitting the standard debug information used by ``gdb`` and
133     other language-agnostic debugging tools, GHC is forced to heuristically
134     choose one location from among this set.
135
136     For this reason we should be cautious when interpretting the source locations
137     provided by GDB. While these locations will usually be in some sense
138     "correct", they aren't always useful. This is why profiling tools targetting
139     Haskell should supplement the standard source location information with
140     GHC-specific annotations (emitted with ``-g2``) when assigning costs.
141
142 Indeed, we can even set breakpoints,
143
144 .. code-block:: none
145
146     (gdb) break fib.hs:4
147     Breakpoint 1 at 0x406c60: fib.hs:4. (5 locations)
148     (gdb) run
149     Starting program: /opt/exp/ghc/ghc-dwarf/Fib
150
151     Breakpoint 1, c1RV_info () at Fib.hs:4
152     4        fib n = fib (n-1) + fib (n-2)
153     (gdb) bt
154     #0  c1RV_info () at Fib.hs:4
155     #1  0x00000000006eb0c0 in ?? ()
156     #2  0x0000000000643ac8 in integerzmgmp_GHCziIntegerziType_ltIntegerzh_info () at libraries/integer-gmp/src/GHC/Integer/Type.hs:343
157     #3  0x00000000004effcc in base_GHCziShow_zdwintegerToString_info () at libraries/base/GHC/Show.hs:443
158     #4  0x00000000004f0795 in base_GHCziShow_zdfShowIntegerzuzdcshow_info () at libraries/base/GHC/Show.hs:145
159     #5  0x000000000048892b in cdGW_info () at libraries/base/GHC/IO/Handle/Text.hs:595
160     #6  0x0000000000419cb2 in base_GHCziBase_thenIO1_info () at libraries/base/GHC/Base.hs:1072
161     #7  0x00000000006ebcb0 in ?? () at rts/Exception.cmm:332
162     #8  0x00000000006e7320 in ?? ()
163     (gdb)
164
165 Due to the nature of GHC's heap and the heavy optimization that it performs, it
166 is quite difficult to probe the values of bindings at runtime. In this way, the
167 debugging experience of a Haskell program with DWARF support is still a bit
168 impoverished compared to typical imperative debuggers.
169
170 Requesting a stack trace from Haskell code
171 ------------------------------------------
172
173 GHC's runtime system has built-in support for collecting stack trace information
174 from a running Haskell program. This currently requires that the ``libdw``
175 library from the ``elfutils`` package is available. Of course, the backtrace
176 will be of little use unless debug information is available in the executable
177 and its dependent libraries.
178
179 Stack trace functionality is exposed for use by Haskell programs in the
180 :base-ref:`GHC.ExecutionStack.` module. See the Haddock
181 documentation in this module for details regarding usage.
182
183 Requesting a stack trace with ``SIGUSR2``
184 -----------------------------------------
185
186 On POSIX-compatible platforms GHC's runtime system (when built with ``libdw``
187 support) will produce a stack trace on ``stderr`` when a ``SIGUSR2`` signal is
188 received. For instance (using the same ``fib.hs`` as above),
189
190 .. code-block:: sh
191
192     $ ./fib  &  killall -SIGUSR2 fib
193     0x7f3176b15dd8    dwfl_thread_getframes (/usr/lib/x86_64-linux-gnu/libdw-0.163.so)
194     0x7f3176b1582f    (null) (/usr/lib/x86_64-linux-gnu/libdw-0.163.so)
195     0x7f3176b15b57    dwfl_getthreads (/usr/lib/x86_64-linux-gnu/libdw-0.163.so)
196     0x7f3176b16150    dwfl_getthread_frames (/usr/lib/x86_64-linux-gnu/libdw-0.163.so)
197           0x6dc857    libdwGetBacktrace (rts/Libdw.c:248.0)
198           0x6e6126    backtrace_handler (rts/posix/Signals.c:541.0)
199     0x7f317677017f    (null) (/lib/x86_64-linux-gnu/libc-2.19.so)
200           0x642e1c    integerzmgmp_GHCziIntegerziType_eqIntegerzh_info (libraries/integer-gmp/src/GHC/Integer/Type.hs:320.1)
201           0x643023    integerzmgmp_GHCziIntegerziType_eqInteger_info (libraries/integer-gmp/src/GHC/Integer/Type.hs:312.1)
202           0x406eca    roz_info (/opt/exp/ghc/ghc-dwarf//Fib.hs:2.1)
203           0x6eafc0    stg_upd_frame_info (rts/Updates.cmm:31.1)
204           0x64ee06    integerzmgmp_GHCziIntegerziType_plusInteger_info (libraries/integer-gmp/src/GHC/Integer/Type.hs:393.1)
205           0x6eafc0    stg_upd_frame_info (rts/Updates.cmm:31.1)
206     ...
207           0x6439d0    integerzmgmp_GHCziIntegerziType_ltIntegerzh_info (libraries/integer-gmp/src/GHC/Integer/Type.hs:343.1)
208           0x4efed4    base_GHCziShow_zdwintegerToString_info (libraries/base/GHC/Show.hs:442.1)
209           0x4f069d    base_GHCziShow_zdfShowIntegerzuzdcshow_info (libraries/base/GHC/Show.hs:145.5)
210           0x488833    base_GHCziIOziHandleziText_zdwa8_info (libraries/base/GHC/IO/Handle/Text.hs:582.1)
211           0x6ebbb0    stg_catch_frame_info (rts/Exception.cmm:370.1)
212           0x6e7220    stg_stop_thread_info (rts/StgStartup.cmm:42.1)
213
214
215 Implementor's notes: DWARF annotations
216 --------------------------------------
217
218 .. note::
219    Most users don't need to worry about the details described in this section.
220    This discussion is primarily targeted at tooling authors who need to
221    interpret the GHC-specific DWARF annotations contained in compiled binaries.
222
223 When invoked with the ``-g`` flag GHC will produce standard `DWARF v4
224 <http://dwarfstd.org/>`__ debugging information. This format is used by nearly
225 all POSIX-compliant targets and can be used by debugging and performance tools
226 (e.g. ``gdb``, ``lldb``, and ``perf``) to understand the structure of
227 GHC-compiled programs.
228
229 In particular GHC produces the following DWARF sections,
230
231 ``.debug_info``
232   Debug information entities (DIEs) describing all of the basic blocks in the
233   compiled program.
234
235 ``.debug_line``
236   Line number information necessary to map instruction addresses to line numbers
237   in the source program.
238
239   Note that the line information in this section is not nearly as rich as the
240   information provided in ``.debug_info``. Whereas ``.debug_line`` requires that
241   each instruction is assigned exactly one source location, the DIEs in
242   ``.debug_info`` can be used to identify all relevant sources locations.
243
244 ``.debug_frames``
245   Call frame information (CFI) necessary for stack unwinding to produce a call
246   stack trace.
247
248 ``.debug_arange``
249   Address range information necessary for efficient lookup in debug information.
250
251
252 Debugging information entities
253 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
254
255 GHC may produce the following standard DIEs in the ``.debug_info`` section,
256
257 ``DW_TAG_compile_unit``
258   Represents a compilation unit (e.g. a Haskell module).
259
260 ``DW_TAG_subprogram``
261   Represents a C-- top-level basic block.
262
263 ``DW_TAG_lexical_block``
264   Represents a C-- basic block. Note that this is a slight departure from the
265   intended meaning of this DIE type as it does not necessarily reflect
266   lexical scope in the source program.
267
268 As GHC's compilation products don't map perfectly onto DWARF constructs,
269 GHC takes advantage of the extensibility of the DWARF standard to provide
270 additional information.
271
272 Unfortunately DWARF isn't expressive enough to fully describe the code
273 that GHC produces. This is most apparent in the case of line
274 information, where GHC is forced to choose some between a variety of
275 possible originating source locations. This limits the usefulness of
276 DWARF information with traditional statistical profiling tools. For
277 profiling it is recommended that one use the extended debugging
278 information. See the *Profiling* section below.
279
280 In addition to the usual DIEs specified by the DWARF specification, GHC
281 produces a variety of others using the vendor-extensibility regions of
282 the tag and attribute space.
283
284 ``DW_TAG_ghc_src_note``
285 ^^^^^^^^^^^^^^^^^^^^^^^
286
287 ``DW_TAG_ghc_src_note`` DIEs (tag 0x5b01) are found as children of
288 ``DW_TAG_lexical_block`` DIEs. They describe source spans which gave rise to the
289 block; formally these spans are causally responsible for produced code: changes
290 to code in the given span may change the code within the block; conversely
291 changes outside the span are guaranteed not to affect the code in the block.
292
293 Spans are described with the following attributes,
294
295 ``DW_AT_ghc_span_file`` (0x2b00, string)
296   the name of the source file
297
298 ``DW_AT_ghc_span_start_line`` (0x2b01, integer)
299   the line number of the beginning of the span
300
301 ``DW_AT_ghc_span_start_col`` (0x2b02, integer)
302   the column number of the beginning of the span
303
304 ``DW_AT_ghc_span_end_line`` (0x2b03, integer)
305   the line number of the end of the span
306
307 ``DW_AT_ghc_span_end_col`` (0x2b04, integer)
308   the column number of the end of the span
309
310
311 Further Reading
312 ---------------
313
314 For more information about the debug information produced by GHC see
315 Peter Wortmann's PhD thesis, `*Profiling Optimized Haskell: Causal
316 Analysis and Implementation* <http://etheses.whiterose.ac.uk/8321/>`__.