Analyzing LLVM Optimization and Debugging Infrastructure

If you want just the IR for a specific function (say, you want to see why it causes an assertion or doesn't optimize correctly), you can use `llvm-extract`, e.g. ```bash $ ./build/$TRIPLE/llvm/bin/llvm-extract \ -func='_ZN11collections3str21_$LT$impl$u20$str$GT$7replace17hbe10ea2e7c809b0bE' \ -S \ < unextracted.ll \ > extracted.ll ``` ### Investigate LLVM optimization passes If you are seeing incorrect behavior due to an optimization pass, a very handy LLVM option is `-opt-bisect-limit`, which takes an integer denoting the index value of the highest pass to run. Index values for taken passes are stable from run to run; by coupling this with software that automates bisecting the search space based on the resulting program, an errant pass can be quickly determined. When an `-opt-bisect-limit` is specified, all runs are displayed to standard error, along with their index and output indicating if the pass was run or skipped. Setting the limit to an index of -1 (e.g., `RUSTFLAGS="-C llvm-args=-opt-bisect-limit=-1"`) will show all passes and their corresponding index values. If you want to play with the optimization pipeline, you can use the [`opt`] tool from `./build/<host-triple>/llvm/bin/` with the LLVM IR emitted by rustc. When investigating the implementation of LLVM itself, you should be aware of its [internal debug infrastructure][llvm-debug]. This is provided in LLVM Debug builds, which you enable for rustc LLVM builds by changing this setting in the bootstrap.toml: ``` [llvm] # Indicates whether the LLVM assertions are enabled or not assertions = true # Indicates whether the LLVM build is a Release or Debug build optimize = false ``` The quick summary is: * Setting `assertions=true` enables coarse-grain debug messaging. * beyond that, setting `optimize=false` enables fine-grain debug messaging. * `LLVM_DEBUG(dbgs() << msg)` in LLVM is like `debug!(msg)` in `rustc`. * The `-debug` option turns on all messaging; it is like setting the environment variable `RUSTC_LOG=debug` in `rustc`. * The `-debug-only=<pass1>,<pass2>` variant is more selective; it is like setting the environment variable `RUSTC_LOG=path1,path2` in `rustc`. ### Getting help and asking questions If you have some questions, head over to the [rust-lang Zulip] and specifically the `#t-compiler/wg-llvm` stream. ### Compiler options to know and love The `-C help` and `-Z help` compiler switches will list out a variety of interesting options you may find useful. Here are a few of the most common that pertain to LLVM development (some of them are employed in the tutorial above): - The `--emit llvm-ir` option emits a `<filename>.ll` file with LLVM IR in textual format - The `--emit llvm-bc` option emits in bytecode format (`<filename>.bc`) - Passing `-C llvm-args=<foo>` allows passing pretty much all the

This section focuses on advanced LLVM debugging techniques. It covers using `llvm-extract` to isolate specific functions for analysis and `opt-bisect-limit` to pinpoint problematic optimization passes. It details how to enable LLVM's internal debug infrastructure by setting `assertions = true` and `optimize = false` in `bootstrap.toml`, and using `LLVM_DEBUG` for messaging. Finally, it mentions resources for help, like the rust-lang Zulip `#t-compiler/wg-llvm` stream, and lists useful compiler options such as `--emit llvm-ir` and `-C llvm-args`.