7adcc84f13f238e334722c18a287b57884747be9
[ghc.git] / docs / users_guide / debugging.rst
1 .. _options-debugging:
2
3 Debugging the compiler
4 ======================
5
6 .. index::
7    single: debugging options (for GHC)
8
9 ..
10     It is not necessary to provide :category: tags for ``ghc-flag:``s defined in
11     this file; a default is specified in ``flags.py``.
12
13 HACKER TERRITORY. HACKER TERRITORY. (You were warned.)
14
15 .. contents:: Dump flags
16
17 .. _dumping-output:
18
19 Dumping out compiler intermediate structures
20 --------------------------------------------
21
22 .. index::
23    single: dumping GHC intermediates
24    single: intermediate passes, output
25
26 .. ghc-flag:: -ddump-to-file
27     :shortdesc: Dump to files instead of stdout
28     :type: dynamic
29
30     Causes the output from all of the flags listed below to be dumped
31     to a file. The file name depends upon the output produced; for instance,
32     output from :ghc-flag:`-ddump-simpl` will end up in
33     :file:`{module}.dump-simpl`.
34
35 .. ghc-flag:: -ddump-json
36     :shortdesc: Dump error messages as JSON documents
37     :type: dynamic
38
39     Dump error messages as JSON documents. This is intended to be consumed
40     by external tooling. A good way to use it is in conjunction with
41     :ghc-flag:`-ddump-to-file`.
42
43 .. ghc-flag:: -dshow-passes
44     :shortdesc: Print out each pass name as it happens
45     :type: dynamic
46
47     Print out each pass name, its runtime and heap allocations as it happens.
48     Note that this may come at a slight performance cost as the compiler will
49     be a bit more eager in forcing pass results to more accurately account for
50     their costs.
51
52     Two types of messages are produced: Those beginning with ``***`` do
53     denote the beginning of a compilation phase whereas those starting with
54     ``!!!`` mark the end of a pass and are accompanied by allocation and
55     runtime statistics.
56
57 .. ghc-flag:: -dfaststring-stats
58     :shortdesc: Show statistics for fast string usage when finished
59     :type: dynamic
60
61     Show statistics on the usage of fast strings by the compiler.
62
63 .. ghc-flag:: -dppr-debug
64     :shortdesc: Turn on debug printing (more verbose)
65     :type: dynamic
66
67     Debugging output is in one of several "styles." Take the printing of
68     types, for example. In the "user" style (the default), the
69     compiler's internal ideas about types are presented in Haskell
70     source-level syntax, insofar as possible. In the "debug" style
71     (which is the default for debugging output), the types are printed
72     in with explicit foralls, and variables have their unique-id
73     attached (so you can check for things that look the same but
74     aren't). This flag makes debugging output appear in the more verbose
75     debug style.
76
77 .. ghc-flag:: -ddump-timings
78     :shortdesc: Dump per-pass timing and allocation statistics
79     :type: dynamic
80
81     Show allocation and runtime statistics for various stages of compilation.
82
83 GHC is a large program consisting of a number of stages. You can tell GHC to
84 dump information from various stages of compilation using the ``-ddump-⟨pass⟩``
85 flags listed below. Note that some of these tend to produce a lot of output.
86 You can prevent them from clogging up your standard output by passing
87 :ghc-flag:`-ddump-to-file`.
88
89 Front-end
90 ~~~~~~~~~
91
92 These flags dump various information from GHC's frontend. This includes the
93 parser and interface file reader.
94
95 .. ghc-flag:: -ddump-parsed
96     :shortdesc: Dump parse tree
97     :type: dynamic
98
99     Dump parser output
100
101 .. ghc-flag:: -ddump-parsed-ast
102     :shortdesc: Dump parser output as a syntax tree
103     :type: dynamic
104
105     Dump parser output as a syntax tree
106
107 .. ghc-flag:: -ddump-if-trace
108     :shortdesc: Trace interface files
109     :type: dynamic
110
111     Make the interface loader be *real* chatty about what it is up to.
112
113
114 Type-checking and renaming
115 ~~~~~~~~~~~~~~~~~~~~~~~~~~
116
117 These flags dump various information from GHC's typechecker and renamer.
118
119 .. ghc-flag:: -ddump-tc-trace
120     :shortdesc: Trace typechecker
121     :type: dynamic
122
123     Make the type checker be *real* chatty about what it is up to.
124
125 .. ghc-flag:: -ddump-rn-trace
126     :shortdesc: Trace renamer
127     :type: dynamic
128
129     Make the renamer be *real* chatty about what it is up to.
130
131 .. ghc-flag:: -ddump-ec-trace
132     :shortdesc: Trace exhaustiveness checker
133     :type: dynamic
134
135     Make the pattern match exhaustiveness checker be *real* chatty about
136     what it is up to.
137
138 .. ghc-flag:: -ddump-rn-stats
139     :shortdesc: Renamer stats
140     :type: dynamic
141
142     Print out summary of what kind of information the renamer had to
143     bring in.
144
145 .. ghc-flag:: -ddump-rn
146     :shortdesc: Dump renamer output
147     :type: dynamic
148
149     Dump renamer output
150
151 .. ghc-flag:: -ddump-rn-ast
152     :shortdesc: Dump renamer output as a syntax tree
153     :type: dynamic
154
155     Dump renamer output as a syntax tree
156
157 .. ghc-flag:: -ddump-tc
158     :shortdesc: Dump typechecker output
159     :type: dynamic
160
161     Dump typechecker output
162
163 .. ghc-flag:: -ddump-tc-ast
164     :shortdesc: Dump typechecker output as a syntax tree
165     :type: dynamic
166
167     Dump typechecker output as a syntax tree
168
169 .. ghc-flag:: -ddump-splices
170     :shortdesc: Dump TH spliced expressions, and what they evaluate to
171     :type: dynamic
172
173     Dump Template Haskell expressions that we splice in, and what
174     Haskell code the expression evaluates to.
175
176 .. ghc-flag:: -dth-dec-file=⟨file⟩
177     :shortdesc: Show evaluated TH declarations in a .th.hs file
178     :type: dynamic
179
180     Dump expansions of all top-level Template Haskell splices into ⟨file⟩.
181
182 .. ghc-flag:: -ddump-types
183     :shortdesc: Dump type signatures
184     :type: dynamic
185
186     Dump a type signature for each value defined at the top level of
187     the module. The list is sorted alphabetically. Using
188     :ghc-flag:`-dppr-debug` dumps a type signature for all the imported and
189     system-defined things as well; useful for debugging the
190     compiler.
191
192 .. ghc-flag:: -ddump-deriv
193     :shortdesc: Dump deriving output
194     :type: dynamic
195
196     Dump derived instances
197
198
199 Core representation and simplification
200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
201
202 These flags dump various phases of GHC's Core-to-Core pipeline. This begins with
203 the desugarer and includes the simplifier, worker-wrapper transformation, the
204 rule engine, the specialiser, the strictness/occurrence analyser, and a common
205 subexpression elimination pass.
206
207 .. ghc-flag:: -ddump-core-stats
208     :shortdesc: Print a one-line summary of the size of the Core program at the
209         end of the optimisation pipeline
210     :type: dynamic
211
212     Print a one-line summary of the size of the Core program at the end
213     of the optimisation pipeline.
214
215 .. ghc-flag:: -ddump-ds -ddump-ds-preopt
216     :shortdesc: Dump desugarer output.
217     :type: dynamic
218
219     Dump desugarer output. :ghc-flag:`-ddump-ds` dumps the output after the very
220     simple optimiser has run (which discards a lot of clutter and hence is a
221     sensible default. :ghc-flag:`-ddump-ds-preopt` shows the output after
222     desugaring but before the very simple optimiser.
223
224
225 .. ghc-flag:: -ddump-simpl-iterations
226     :shortdesc: Dump output from each simplifier iteration
227     :type: dynamic
228
229     Show the output of each *iteration* of the simplifier (each run of
230     the simplifier has a maximum number of iterations, normally 4).
231
232 .. ghc-flag:: -ddump-simpl-stats
233     :shortdesc: Dump simplifier stats
234     :type: dynamic
235
236     Dump statistics about how many of each kind of transformation took
237     place. If you add :ghc-flag:`-dppr-debug` you get more detailed information.
238
239 .. ghc-flag:: -dverbose-core2core
240     :shortdesc: Show output from each core-to-core pass
241     :type: dynamic
242
243     Show the output of the intermediate Core-to-Core pass. (*lots* of output!)
244     So: when we're really desperate:
245
246     .. code-block:: sh
247
248         % ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs
249
250 .. ghc-flag:: -ddump-spec
251     :shortdesc: Dump specialiser output
252     :type: dynamic
253
254     Dump output of specialisation pass
255
256 .. ghc-flag:: -ddump-rules
257     :shortdesc: Dump rewrite rules
258     :type: dynamic
259
260     Dumps all rewrite rules specified in this module; see
261     :ref:`controlling-rules`.
262
263 .. ghc-flag:: -ddump-rule-firings
264     :shortdesc: Dump rule firing info
265     :type: dynamic
266
267     Dumps the names of all rules that fired in this module
268
269 .. ghc-flag:: -ddump-rule-rewrites
270     :shortdesc: Dump detailed rule firing info
271     :type: dynamic
272
273     Dumps detailed information about all rules that fired in this
274     module
275
276 .. ghc-flag:: -drule-check=⟨str⟩
277     :shortdesc: Dump information about potential rule application
278     :type: dynamic
279
280     This flag is useful for debugging why a rule you expect to be firing isn't.
281
282     Rules are filtered by the user provided string, a rule is kept if a prefix
283     of its name matches the string.
284     The pass then checks whether any of these rules could apply to
285     the program but which didn't file for some reason. For example, specifying
286     ``-drule-check=SPEC`` will check whether there are any applications which
287     might be subject to a rule created by specialisation.
288
289 .. ghc-flag:: -dinline-check=⟨str⟩
290     :shortdesc: Dump information about inlining decisions
291     :type: dynamic
292
293     This flag is useful for debugging why a definition is not inlined.
294
295     When a string is passed to this flag we report information
296     about all functions whose name shares a prefix with the string.
297
298     For example, if you are inspecting the core of your program and you observe
299     that ``foo`` is not being inlined. You can pass ``-dinline-check foo`` and
300     you will see a report about why ``foo`` is not inlined.
301
302 .. ghc-flag:: -ddump-simpl
303     :shortdesc: Dump final simplifier output
304     :type: dynamic
305
306     Dump simplifier output (Core-to-Core passes)
307
308 .. ghc-flag:: -ddump-inlinings
309     :shortdesc: Dump inlining info
310     :type: dynamic
311
312     Dumps inlining info from the simplifier. Note that if used in
313     conjunction with :ghc-flag:`-dverbose-core2core` the compiler will
314     also dump the inlinings that it considers but passes up, along with
315     its rationale.
316
317 .. ghc-flag:: -ddump-stranal
318     :shortdesc: Dump strictness analyser output
319     :type: dynamic
320
321     Dump strictness analyser output
322
323 .. ghc-flag:: -ddump-str-signatures
324     :shortdesc: Dump strictness signatures
325     :type: dynamic
326
327     Dump strictness signatures
328
329 .. ghc-flag:: -ddump-cse
330     :shortdesc: Dump CSE output
331     :type: dynamic
332
333     Dump common subexpression elimination (CSE) pass output
334
335 .. ghc-flag:: -ddump-worker-wrapper
336     :shortdesc: Dump worker-wrapper output
337     :type: dynamic
338
339     Dump worker/wrapper split output
340
341 .. ghc-flag:: -ddump-occur-anal
342     :shortdesc: Dump occurrence analysis output
343     :type: dynamic
344
345     Dump "occurrence analysis" output
346
347 .. ghc-flag:: -ddump-prep
348     :shortdesc: Dump prepared core
349     :type: dynamic
350
351     Dump output of Core preparation pass
352
353
354 STG representation
355 ~~~~~~~~~~~~~~~~~~
356
357 These flags dump various phases of GHC's STG pipeline.
358
359 .. ghc-flag:: -ddump-stg
360     :shortdesc: Dump final STG
361     :type: dynamic
362
363     Dump output of STG-to-STG passes
364
365 .. ghc-flag:: -dverbose-stg2stg
366     :shortdesc: Show output from each STG-to-STG pass
367     :type: dynamic
368
369     Show the output of the intermediate STG-to-STG pass. (*lots* of output!)
370
371
372 C-\\- representation
373 ~~~~~~~~~~~~~~~~~~~~
374
375 These flags dump various phases of GHC's C-\\- pipeline.
376
377 .. ghc-flag:: -ddump-cmm-verbose
378     :shortdesc: Show output from each C-\\- pipeline pass
379     :type: dynamic
380
381     Dump output from all C-\\- pipeline stages. In case of
382     ``.cmm`` compilation this also dumps the result of
383     file parsing.
384
385 .. ghc-flag:: -ddump-cmm-from-stg
386     :shortdesc: Dump STG-to-C-\\- output
387     :type: dynamic
388
389     Dump the result of STG-to-C-\\- conversion
390
391 .. ghc-flag:: -ddump-cmm-raw
392     :shortdesc: Dump raw C-\\-
393     :type: dynamic
394
395     Dump the “raw” C-\\-.
396
397 .. ghc-flag:: -ddump-cmm-cfg
398     :shortdesc: Dump the results of the C-\\- control flow optimisation pass.
399     :type: dynamic
400
401     Dump the results of the C-\\- control flow optimisation pass.
402
403 .. ghc-flag:: -ddump-cmm-cbe
404     :shortdesc: Dump the results of common block elimination
405     :type: dynamic
406
407     Dump the results of the C-\\- Common Block Elimination (CBE) pass.
408
409 .. ghc-flag:: -ddump-cmm-switch
410     :shortdesc: Dump the results of switch lowering passes
411     :type: dynamic
412
413     Dump the results of the C-\\- switch lowering pass.
414
415 .. ghc-flag:: -ddump-cmm-proc
416     :shortdesc: Dump the results of proc-point analysis
417     :type: dynamic
418
419     Dump the results of the C-\\- proc-point analysis pass.
420
421 .. ghc-flag:: -ddump-cmm-sp
422     :shortdesc: Dump the results of the C-\\- stack layout pass.
423     :type: dynamic
424
425     Dump the results of the C-\\- stack layout pass.
426
427 .. ghc-flag:: -ddump-cmm-sink
428     :shortdesc: Dump the results of the C-\\- sinking pass.
429     :type: dynamic
430
431     Dump the results of the C-\\- sinking pass.
432
433 .. ghc-flag:: -ddump-cmm-caf
434     :shortdesc: Dump the results of the C-\\- CAF analysis pass.
435     :type: dynamic
436
437     Dump the results of the C-\\- CAF analysis pass.
438
439 .. ghc-flag:: -ddump-cmm-procmap
440     :shortdesc: Dump the results of the C-\\- proc-point map pass.
441     :type: dynamic
442
443     Dump the results of the C-\\- proc-point map pass.
444
445 .. ghc-flag:: -ddump-cmm-split
446     :shortdesc: Dump the results of the C-\\- proc-point splitting pass.
447     :type: dynamic
448
449     Dump the results of the C-\\- proc-point splitting pass.
450
451 .. ghc-flag:: -ddump-cmm-info
452     :shortdesc: Dump the results of the C-\\- info table augmentation pass.
453     :type: dynamic
454
455     Dump the results of the C-\\- info table augmentation pass.
456
457 .. ghc-flag:: -ddump-cmm-cps
458     :shortdesc: Dump the results of the CPS pass
459     :type: dynamic
460
461     Dump the results of the CPS pass.
462
463 .. ghc-flag:: -ddump-cmm
464     :shortdesc: Dump the final C-\\- output
465     :type: dynamic
466
467     Dump the result of the C-\\- pipeline processing
468
469
470
471 LLVM code generator
472 ~~~~~~~~~~~~~~~~~~~~~~
473
474 .. ghc-flag:: -ddump-llvm
475     :shortdesc: Dump LLVM intermediate code.
476     :type: dynamic
477
478     :implies: :ghc-flag:`-fllvm`
479
480     LLVM code from the :ref:`LLVM code generator <llvm-code-gen>`
481
482 Native code generator
483 ~~~~~~~~~~~~~~~~~~~~~
484
485 These flags dump various stages of the :ref:`native code generator's
486 <native-code-gen>` pipeline, which starts with C-\\- and produces native
487 assembler.
488
489 .. ghc-flag:: -ddump-opt-cmm
490     :shortdesc: Dump the results of C-\\- to C-\\- optimising passes
491     :type: dynamic
492
493     Dump the results of C-\\- to C-\\- optimising passes performed by the NCG.
494
495 .. ghc-flag:: -ddump-asm-native
496     :shortdesc: Dump initial assembly
497     :type: dynamic
498
499     Dump the initial assembler output produced from C-\\-.
500
501 .. ghc-flag:: -ddump-asm-liveness
502     :shortdesc: Dump assembly augmented with register liveness
503     :type: dynamic
504
505     Dump the result of the register liveness pass.
506
507 .. ghc-flag:: -ddump-asm-regalloc
508     :shortdesc: Dump the result of register allocation
509     :type: dynamic
510
511     Dump the result of the register allocation pass.
512
513 .. ghc-flag:: -ddump-asm-regalloc-stages
514     :shortdesc: Dump the build/spill stages of the :ghc-flag:`-fregs-graph`
515                 register allocator.
516     :type: dynamic
517
518     Dump the build/spill stages of the :ghc-flag:`-fregs-graph` register
519     allocator.
520
521 .. ghc-flag:: -ddump-asm-stats
522     :shortdesc: Dump statistics from the register allocator.
523     :type: dynamic
524
525     Dump statistics from the register allocator.
526
527 .. ghc-flag:: -ddump-asm-expanded
528     :shortdesc: Dump the result of the synthetic instruction expansion pass.
529     :type: dynamic
530
531     Dump the result of the synthetic instruction expansion pass.
532
533 .. ghc-flag:: -ddump-asm
534     :shortdesc: Dump final assembly
535     :type: dynamic
536
537     Dump assembly language produced by the
538
539
540 Miscellaneous backend dumps
541 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
542
543 These flags dump various bits of information from other backends.
544
545 .. ghc-flag:: -ddump-bcos
546     :shortdesc: Dump interpreter byte code
547     :type: dynamic
548
549     Dump byte-code objects (BCOs) produced for the GHC's byte-code interpreter.
550
551 .. ghc-flag:: -ddump-foreign
552     :shortdesc: Dump ``foreign export`` stubs
553     :type: dynamic
554
555     Dump foreign export stubs.
556
557
558
559 .. _formatting dumps:
560
561 Formatting dumps
562 ----------------
563
564 .. index::
565    single: formatting dumps
566
567 .. ghc-flag:: -dppr-user-length
568     :shortdesc: Set the depth for printing expressions in error msgs
569     :type: dynamic
570
571     In error messages, expressions are printed to a certain "depth",
572     with subexpressions beyond the depth replaced by ellipses. This flag
573     sets the depth. Its default value is 5.
574
575 .. ghc-flag:: -dppr-cols=⟨n⟩
576     :shortdesc: Set the width of debugging output. For example ``-dppr-cols200``
577     :type: dynamic
578
579     Set the width of debugging output. Use this if your code is wrapping
580     too much. For example: ``-dppr-cols=200``.
581
582 .. ghc-flag:: -dppr-case-as-let
583     :shortdesc: Print single alternative case expressions as strict lets.
584     :type: dynamic
585
586     Print single alternative case expressions as though they were strict
587     let expressions. This is helpful when your code does a lot of
588     unboxing.
589
590 .. ghc-flag:: -dhex-word-literals
591     :shortdesc: Print values of type `Word#` in hexadecimal.
592     :type: dynamic
593
594     Print values of type `Word#` and `Word64#` (but not values of
595     type `Int#` and `Int64#`) in hexadecimal instead of decimal.
596     The hexadecimal is zero-padded to make the length of the
597     representation a power of two. For example: `0x0A0A##`,
598     `0x000FFFFF##`, `0xC##`. This flag may be helpful when you
599     are producing a bit pattern that to expect to work correctly on a 32-bit
600     or a 64-bit architecture. Dumping hexadecimal literals after
601     optimizations and constant folding makes it easier to confirm
602     that the generated bit pattern is correct.
603
604 .. ghc-flag:: -dno-debug-output
605     :shortdesc: Suppress unsolicited debugging output
606     :type: dynamic
607     :reverse: -ddebug-output
608
609     Suppress any unsolicited debugging output. When GHC has been built
610     with the ``DEBUG`` option it occasionally emits debug output of
611     interest to developers. The extra output can confuse the testing
612     framework and cause bogus test failures, so this flag is provided to
613     turn it off.
614
615 .. _suppression:
616
617 Suppressing unwanted information
618 --------------------------------
619
620 .. index::
621    single: suppression; of unwanted dump output
622
623 Core dumps contain a large amount of information. Depending on what you
624 are doing, not all of it will be useful. Use these flags to suppress the
625 parts that you are not interested in.
626
627 .. ghc-flag:: -dsuppress-all
628     :shortdesc: In dumps, suppress everything (except for uniques) that is
629         suppressible.
630     :type: dynamic
631
632     Suppress everything that can be suppressed, except for unique ids as
633     this often makes the printout ambiguous. If you just want to see the
634     overall structure of the code, then start here.
635
636 .. ghc-flag:: -dsuppress-ticks
637     :shortdesc: Suppress "ticks" in the pretty-printer output.
638     :type: dynamic
639
640     Suppress "ticks" in the pretty-printer output.
641
642 .. ghc-flag:: -dsuppress-uniques
643     :shortdesc: Suppress the printing of uniques in debug output (easier to use
644         ``diff``)
645     :type: dynamic
646
647     Suppress the printing of uniques. This may make the printout
648     ambiguous (e.g. unclear where an occurrence of 'x' is bound), but it
649     makes the output of two compiler runs have many fewer gratuitous
650     differences, so you can realistically apply ``diff``. Once ``diff``
651     has shown you where to look, you can try again without
652     :ghc-flag:`-dsuppress-uniques`
653
654 .. ghc-flag:: -dsuppress-idinfo
655     :shortdesc: Suppress extended information about identifiers where they
656         are bound
657     :type: dynamic
658
659     Suppress extended information about identifiers where they are
660     bound. This includes strictness information and inliner templates.
661     Using this flag can cut the size of the core dump in half, due to
662     the lack of inliner templates
663
664 .. ghc-flag:: -dsuppress-unfoldings
665     :shortdesc: Suppress the printing of the stable unfolding of a variable at
666         its binding site
667     :type: dynamic
668
669     Suppress the printing of the stable unfolding of a variable at its
670     binding site.
671
672 .. ghc-flag:: -dsuppress-module-prefixes
673     :shortdesc: Suppress the printing of module qualification prefixes
674     :type: dynamic
675
676     Suppress the printing of module qualification prefixes. This is the
677     ``Data.List`` in ``Data.List.length``.
678
679 .. ghc-flag:: -dsuppress-timestamps
680     :shortdesc: Suppress timestamps in dumps
681     :type: dynamic
682
683     Suppress the printing of timestamps.
684     This makes it easier to diff dumps.
685
686 .. ghc-flag:: -dsuppress-type-signatures
687     :shortdesc: Suppress type signatures
688     :type: dynamic
689
690     Suppress the printing of type signatures.
691
692 .. ghc-flag:: -dsuppress-type-applications
693     :shortdesc: Suppress type applications
694     :type: dynamic
695
696     Suppress the printing of type applications.
697
698 .. ghc-flag:: -dsuppress-coercions
699     :shortdesc: Suppress the printing of coercions in Core dumps to make them
700         shorter
701     :type: dynamic
702
703     Suppress the printing of type coercions.
704
705 .. ghc-flag:: -dsuppress-var-kinds
706     :shortdesc: Suppress the printing of variable kinds
707     :type: dynamic
708
709     Suppress the printing of variable kinds
710
711 .. ghc-flag:: -dsuppress-stg-free-vars
712     :shortdesc: Suppress the printing of closure free variable lists in STG output
713     :type: dynamic
714
715     Suppress the printing of closure free variable lists in STG output
716
717
718 .. _checking-consistency:
719
720 Checking for consistency
721 ------------------------
722
723 .. index::
724    single: consistency checks
725    single: lint
726
727 .. ghc-flag:: -dcore-lint
728     :shortdesc: Turn on internal sanity checking
729     :type: dynamic
730
731     Turn on heavyweight intra-pass sanity-checking within GHC, at Core
732     level. (It checks GHC's sanity, not yours.)
733
734 .. ghc-flag:: -dstg-lint
735     :shortdesc: STG pass sanity checking
736     :type: dynamic
737
738     Ditto for STG level.
739
740 .. ghc-flag:: -dcmm-lint
741     :shortdesc: C-\\- pass sanity checking
742     :type: dynamic
743
744     Ditto for C-\\- level.
745
746 .. ghc-flag:: -fllvm-fill-undef-with-garbage
747     :shortdesc: Intruct LLVM to fill dead STG registers with garbage
748     :type: dynamic
749
750     Instructs the LLVM code generator to fill dead STG registers with garbage
751     instead of ``undef`` in calls. This makes it easier to catch subtle
752     code generator and runtime system bugs (e.g. see :ghc-ticket:`11487`).
753
754 .. ghc-flag:: -falignment-sanitisation
755     :shortdesc: Compile with alignment checks for all info table dereferences.
756     :type: dynamic
757
758     Compile with alignment checks for all info table dereferences. This can be
759     useful when finding pointer tagging issues.
760
761 .. ghc-flag:: -fproc-alignment
762     :shortdesc: Align functions at given boundry.
763     :type: dynamic
764
765     Align functions to multiples of the given value. Only valid values are powers
766     of two.
767
768     ``-fproc-alignment=64`` can be used to limit alignment impact on performance
769     as each function will start at a cache line.
770     However forcing larger alignments in general reduces performance.
771
772 .. ghc-flag:: -fcatch-bottoms
773     :shortdesc: Insert ``error`` expressions after bottoming expressions; useful
774         when debugging the compiler.
775     :type: dynamic
776
777     Instructs the simplifier to emit ``error`` expressions in the continuation
778     of empty case analyses (which should bottom and consequently not return).
779     This is helpful when debugging demand analysis bugs which can sometimes
780     manifest as segmentation faults.
781
782 .. _checking-determinism:
783
784 Checking for determinism
785 ------------------------
786
787 .. index::
788    single: deterministic builds
789
790 .. ghc-flag:: -dinitial-unique=⟨s⟩
791     :shortdesc: Start ``UniqSupply`` allocation from ⟨s⟩.
792     :type: dynamic
793
794     Start ``UniqSupply`` allocation from ⟨s⟩.
795
796 .. ghc-flag:: -dunique-increment=⟨i⟩
797     :shortdesc: Set the increment for the generated ``Unique``'s to ⟨i⟩.
798     :type: dynamic
799
800     Set the increment for the generated ``Unique``'s to ⟨i⟩.
801
802     This is useful in combination with :ghc-flag:`-dinitial-unique=⟨s⟩` to test
803     if the generated files depend on the order of ``Unique``'s.
804
805     Some interesting values:
806
807     * ``-dinitial-unique=0 -dunique-increment=1`` - current sequential
808       ``UniqSupply``
809     * ``-dinitial-unique=16777215 -dunique-increment=-1`` - ``UniqSupply`` that
810       generates in decreasing order
811     * ``-dinitial-unique=1 -dunique-increment=PRIME`` - where PRIME big enough
812       to overflow often - nonsequential order