llvm/docs/DebuggingLLVM.md - llvm-project - Git at Google

 # Debugging LLVM

 This document is a collection of tips and tricks for debugging LLVM
 using a source-level debugger. The assumption is that you are trying to
 figure out the root cause of a miscompilation in the program that you
 are compiling.

 ## Extract and rerun the compile command

 Extract the Clang command that produces the buggy code. The way to do
 this depends on the build system used by your program.

 - For Ninja-based build systems, you can pass `-t commands` to Ninja
   and filter the output by the targeted source file name. For example:
   `ninja -t commands myprogram | grep path/to/file.cpp`.

 - For Bazel-based build systems using Bazel 9 or newer, you can pass
   `--output=commands` to the `bazel aquery` subcommand for
   a similar result. For example: `bazel aquery --output=commands
   'deps(//myprogram)' | grep path/to/file.cpp`. Build commands must
   generally be run from a subdirectory of the source directory named
   `bazel-$PROJECTNAME`. Bazel typically makes the target paths of
   `-o` and `-MF` read-only when running commands outside of a build,
   so it may be necessary to change or remove these flags.

 - A method that should work with any build system is to build your program
   under [Bear] and look for the
   compile command in the resulting `compile_commands.json` file.

 Once you have the command you can use the following steps to debug
 it. Note that any flags mentioned later in this document are LLVM flags
 so they must be prefixed with `-mllvm` when passed to the Clang driver,
 e.g. `-mllvm -print-after-all`.

 ## Understanding the source of the issue

 If you have a miscompilation introduced by a pass, it is
 frequently possible to identify the pass where things go wrong
 by searching a pass-by-pass printout. The following options control when IR is
 printed:

 - `-print-before-all` and `-print-after-all` print IR before or after every
   pass.
 - `-print-before=<pass-name>` and `-print-after=<pass-name>` print IR around
   selected passes. Multiple pass names can be separated by commas.
 - `-print-pass-numbers` prints the pass names and their ordinals.
   `-print-before-pass-number=<number>` and
   `-print-after-pass-number=<number>` can then select particular pass
   invocations. Multiple numbers can be separated by commas.
 - `-print-changed` prints IR only after passes that change it. Its optional
   modes include `quiet`, `diff`, `diff-quiet`, `cdiff`, `cdiff-quiet`,
   `dot-cfg`, and `dot-cfg-quiet`. `-print-before-changed` also prints the IR
   before each detected change.

 The following options reduce or organize the output:

 - `-filter-print-funcs=<function-name>` limits output to the listed functions.
   Multiple names can be separated by commas.
 - `-filter-print-source-locs=<file>:<line-list>` limits output to IR units that
   contain a matching debug location. A line list can contain individual lines
   and inclusive ranges, for example
   `-filter-print-source-locs=example.cpp:12,20-25`. The file may be a basename,
   a complete path, or a path suffix. Inlined locations are also considered.
   Repeat the option to select locations from more than one file. This option
   requires debug information, such as that produced by Clang's `-g` option. It
   selects whole functions, loops, or other IR units containing a match; it does
   not remove individual nonmatching instructions from them.
 - `-filter-passes=<pass-name>` limits `-print-changed` output to the listed
   passes. Multiple names can be separated by commas.
 - `-print-module-scope` prints the whole module instead of the IR unit on which
   a pass runs. `-print-loop-func-scope` prints the containing function for loop
   passes.
 - `-ir-dump-directory=<directory>` writes `-print-before` and `-print-after`
   output to files instead of standard error.

 For example, the following command prints the IR after every pass, but only for
 functions containing instructions associated with the selected source lines:

 ```text
 clang -O2 -g -mllvm -print-after-all \
   -mllvm -filter-print-source-locs=example.cpp:12,20-25 example.cpp -c
 ```

 By default, dumps are written to standard error. Pipe standard error into
 `less` (append `2>&1 | less` to the command line) and use text search to move
 between passes (for example, type `/Dump After<Enter>`, `n` to move to the next
 pass, and `N` to move to the previous pass).

 Metadata IDs remain stable across repeated pass and debug dumps, which makes
 nodes easier to follow between snapshots. These IDs may contain gaps or appear
 in a different order from normal complete-module LLVM IR output, where metadata
 IDs are renumbered into a contiguous canonical sequence.

 You can sometimes pass `-debug` to get useful details about what passes are
 doing. See also [PrintPasses.cpp] for the option definitions.

 ## Creating a debug build of LLVM

 The subsequent debugging steps require a debug build of LLVM. Pass the
 `-DCMAKE_BUILD_TYPE=Debug` to CMake in a separate build tree to create
 a debug build.

 ## Understanding where an instruction came from

 A common debugging task involves understanding which part of the code
 introduced a buggy instruction. The pass-by-pass dump is sometimes enough,
 but for complex or unfamiliar passes, more information is often required.

 The first step is to record a run of the debug build of Clang under [rr]
 passing the LLVM flag `-print-inst-addrs`
 together with `-print-after-all` and any desired filters. This will
 cause each instruction printed by LLVM to be suffixed with a comment
 showing the address of the `Instruction` object. You can then replay
 the run of Clang with `rr replay`. Because `rr` is deterministic,
 the instruction will receive the same address during the replay, so
 you can break on the instruction's construction using a conditional
 breakpoint that checks for the address printed by LLVM, with commands
 such as the following:

 ```text
 b Instruction::Instruction if this == 0x12345678
 ```

 When the breakpoint is hit, you will likely be at the location where
 the instruction was created, so you can unwind the stack with `bt`
 to see the stack trace. It is also possible that an instruction was
 created multiple times at the same address, so you may need to continue
 until reaching the desired location, but in the author's experience this
 is unlikely to occur.

 Similar flags exist for the backend: `-print-sdnode-addrs` for
 printing `SDNode` addresses, and `-print-mi-addrs` for printing
 `MachineInstr` addresses.

 ## Identifying the source locations of instructions

 To identify the source location that caused a particular instruction
 to be created, you can pass the LLVM flag `-print-inst-debug-locs`
 and each instruction printed by LLVM is suffixed with the file and line
 number of the instruction according to the debug information. Note that
 this requires debug information to be enabled (e.g. pass `-g` to Clang).

 ## LLDB Data Formatters

 A handful of [LLDB data formatters] are
 provided for some of the core LLVM libraries. To use them, execute the
 following (or add it to your `~/.lldbinit`):

 ```text
 command script import /path/to/llvm/utils/lldbDataFormatters.py
 ```

 ## GDB pretty printers

 A handful of [GDB pretty printers] are
 provided for some of the core LLVM libraries. To use them, execute the
 following (or add it to your `~/.gdbinit`):

 ```text
 source /path/to/llvm/utils/gdb-scripts/prettyprinters.py
 ```

 It also might be handy to enable the [print pretty]
 option to avoid data structures being printed as a big block of text.

 [Bear]: https://github.com/rizsotto/Bear
 [PrintPasses.cpp]: https://github.com/llvm/llvm-project/blob/main/llvm/lib/IR/PrintPasses.cpp
 [rr]: https://rr-project.org
 [LLDB data formatters]: https://lldb.llvm.org/resources/dataformatters.html
 [GDB pretty printers]: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html
 [print pretty]: https://sourceware.org/gdb/current/onlinedocs/gdb.html/Print-Settings.html
	# Debugging LLVM

	This document is a collection of tips and tricks for debugging LLVM
	using a source-level debugger. The assumption is that you are trying to
	figure out the root cause of a miscompilation in the program that you
	are compiling.

	## Extract and rerun the compile command

	Extract the Clang command that produces the buggy code. The way to do
	this depends on the build system used by your program.

	- For Ninja-based build systems, you can pass `-t commands` to Ninja
	and filter the output by the targeted source file name. For example:
	`ninja -t commands myprogram \| grep path/to/file.cpp`.

	- For Bazel-based build systems using Bazel 9 or newer, you can pass
	`--output=commands` to the `bazel aquery` subcommand for
	a similar result. For example: `bazel aquery --output=commands
	'deps(//myprogram)' \| grep path/to/file.cpp`. Build commands must
	generally be run from a subdirectory of the source directory named
	`bazel-$PROJECTNAME`. Bazel typically makes the target paths of
	`-o` and `-MF` read-only when running commands outside of a build,
	so it may be necessary to change or remove these flags.

	- A method that should work with any build system is to build your program
	under [Bear] and look for the
	compile command in the resulting `compile_commands.json` file.

	Once you have the command you can use the following steps to debug
	it. Note that any flags mentioned later in this document are LLVM flags
	so they must be prefixed with `-mllvm` when passed to the Clang driver,
	e.g. `-mllvm -print-after-all`.

	## Understanding the source of the issue

	If you have a miscompilation introduced by a pass, it is
	frequently possible to identify the pass where things go wrong
	by searching a pass-by-pass printout. The following options control when IR is
	printed:

	- `-print-before-all` and `-print-after-all` print IR before or after every
	pass.
	- `-print-before=<pass-name>` and `-print-after=<pass-name>` print IR around
	selected passes. Multiple pass names can be separated by commas.
	- `-print-pass-numbers` prints the pass names and their ordinals.
	`-print-before-pass-number=<number>` and
	`-print-after-pass-number=<number>` can then select particular pass
	invocations. Multiple numbers can be separated by commas.
	- `-print-changed` prints IR only after passes that change it. Its optional
	modes include `quiet`, `diff`, `diff-quiet`, `cdiff`, `cdiff-quiet`,
	`dot-cfg`, and `dot-cfg-quiet`. `-print-before-changed` also prints the IR
	before each detected change.

	The following options reduce or organize the output:

	- `-filter-print-funcs=<function-name>` limits output to the listed functions.
	Multiple names can be separated by commas.
	- `-filter-print-source-locs=<file>:<line-list>` limits output to IR units that
	contain a matching debug location. A line list can contain individual lines
	and inclusive ranges, for example
	`-filter-print-source-locs=example.cpp:12,20-25`. The file may be a basename,
	a complete path, or a path suffix. Inlined locations are also considered.
	Repeat the option to select locations from more than one file. This option
	requires debug information, such as that produced by Clang's `-g` option. It
	selects whole functions, loops, or other IR units containing a match; it does
	not remove individual nonmatching instructions from them.
	- `-filter-passes=<pass-name>` limits `-print-changed` output to the listed
	passes. Multiple names can be separated by commas.
	- `-print-module-scope` prints the whole module instead of the IR unit on which
	a pass runs. `-print-loop-func-scope` prints the containing function for loop
	passes.
	- `-ir-dump-directory=<directory>` writes `-print-before` and `-print-after`
	output to files instead of standard error.

	For example, the following command prints the IR after every pass, but only for
	functions containing instructions associated with the selected source lines:

	```text
	clang -O2 -g -mllvm -print-after-all \
	-mllvm -filter-print-source-locs=example.cpp:12,20-25 example.cpp -c
	```

	By default, dumps are written to standard error. Pipe standard error into
	`less` (append `2>&1 \| less` to the command line) and use text search to move
	between passes (for example, type `/Dump After<Enter>`, `n` to move to the next
	pass, and `N` to move to the previous pass).

	Metadata IDs remain stable across repeated pass and debug dumps, which makes
	nodes easier to follow between snapshots. These IDs may contain gaps or appear
	in a different order from normal complete-module LLVM IR output, where metadata
	IDs are renumbered into a contiguous canonical sequence.

	You can sometimes pass `-debug` to get useful details about what passes are
	doing. See also [PrintPasses.cpp] for the option definitions.

	## Creating a debug build of LLVM

	The subsequent debugging steps require a debug build of LLVM. Pass the
	`-DCMAKE_BUILD_TYPE=Debug` to CMake in a separate build tree to create
	a debug build.

	## Understanding where an instruction came from

	A common debugging task involves understanding which part of the code
	introduced a buggy instruction. The pass-by-pass dump is sometimes enough,
	but for complex or unfamiliar passes, more information is often required.

	The first step is to record a run of the debug build of Clang under [rr]
	passing the LLVM flag `-print-inst-addrs`
	together with `-print-after-all` and any desired filters. This will
	cause each instruction printed by LLVM to be suffixed with a comment
	showing the address of the `Instruction` object. You can then replay
	the run of Clang with `rr replay`. Because `rr` is deterministic,
	the instruction will receive the same address during the replay, so
	you can break on the instruction's construction using a conditional
	breakpoint that checks for the address printed by LLVM, with commands
	such as the following:

	```text
	b Instruction::Instruction if this == 0x12345678
	```

	When the breakpoint is hit, you will likely be at the location where
	the instruction was created, so you can unwind the stack with `bt`
	to see the stack trace. It is also possible that an instruction was
	created multiple times at the same address, so you may need to continue
	until reaching the desired location, but in the author's experience this
	is unlikely to occur.

	Similar flags exist for the backend: `-print-sdnode-addrs` for
	printing `SDNode` addresses, and `-print-mi-addrs` for printing
	`MachineInstr` addresses.

	## Identifying the source locations of instructions

	To identify the source location that caused a particular instruction
	to be created, you can pass the LLVM flag `-print-inst-debug-locs`
	and each instruction printed by LLVM is suffixed with the file and line
	number of the instruction according to the debug information. Note that
	this requires debug information to be enabled (e.g. pass `-g` to Clang).

	## LLDB Data Formatters

	A handful of [LLDB data formatters] are
	provided for some of the core LLVM libraries. To use them, execute the
	following (or add it to your `~/.lldbinit`):

	```text
	command script import /path/to/llvm/utils/lldbDataFormatters.py
	```

	## GDB pretty printers

	A handful of [GDB pretty printers] are
	provided for some of the core LLVM libraries. To use them, execute the
	following (or add it to your `~/.gdbinit`):

	```text
	source /path/to/llvm/utils/gdb-scripts/prettyprinters.py
	```

	It also might be handy to enable the [print pretty]
	option to avoid data structures being printed as a big block of text.

	[Bear]: https://github.com/rizsotto/Bear
	[PrintPasses.cpp]: https://github.com/llvm/llvm-project/blob/main/llvm/lib/IR/PrintPasses.cpp
	[rr]: https://rr-project.org
	[LLDB data formatters]: https://lldb.llvm.org/resources/dataformatters.html
	[GDB pretty printers]: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html
	[print pretty]: https://sourceware.org/gdb/current/onlinedocs/gdb.html/Print-Settings.html