Read LLVM 20 optimisation reports with llvm-opt-report

You will compile a small C file with Clang, save its optimisation records, and turn those records into a source listing marked with inline, unroll and vectorisation decisions. Allow about ten minutes for a first run. The examples use Ubuntu's installed LLVM 20.1.8 package, but the same workflow applies to a matching LLVM 20 installation.

1. Check the installed tools

llvm-opt-report-20 does not discover optimisation history from an object file by itself. Clang must emit an optimisation record while compiling. The report tool then reads that record, normally a YAML file ending in .opt.yaml. Check both commands before creating any files:

$ command -v clang-20
/usr/bin/clang-20
$ clang-20 --version
Ubuntu clang version 20.1.8
$ command -v llvm-opt-report-20
/usr/bin/llvm-opt-report-20
$ llvm-opt-report-20 --version
Ubuntu LLVM version 20.1.8

Exact build wording can differ, so the useful checks are that the commands resolve and report version 20.1.8, or another LLVM 20 version you have deliberately chosen. No command in this guide needs elevated privileges. Do not use sudo to read a project file or write a report in your own working directory.

2. Generate a YAML optimisation record

Make a clean working directory and compile with -fsave-optimization-record. This example gives the compiler an inline candidate and a result that can be checked without running the resulting object:

$ mkdir -p build/opt-report-demo
$ cd build/opt-report-demo
$ cat > sample.c <<'EOF'
static int add(int a, int b) { return a + b; }
int main(void) { return add(20, 22) != 42; }
EOF
$ clang-20 -O2 -fsave-optimization-record -c sample.c -o sample.o
$ ls -1
sample.c
sample.o
sample.opt.yaml

The source and object names are ordinary choices. The important parts are the optimisation level, the record flag, and the generated sample.opt.yaml. Clang writes records for the compilation unit, so a larger project normally produces one record per relevant compile rather than one universal report for the whole build.

Checkpoint: if sample.opt.yaml is absent, stop here. Check that the compiler is Clang 20, that the compile succeeded, and that the output directory is writable. Do not pass the object file to llvm-opt-report-20; it expects a serialised optimisation record.

3. Write the readable report

Give the YAML file to the command and select a new destination with -o:

$ llvm-opt-report-20 sample.opt.yaml -o sample.lst
$ sed -n '1,20p' sample.lst
< sample.c
1   | static int add(int a, int b) { return a + b; }
2 I | int main(void) { return add(20, 22) != 42; }

The report puts the source file name at the top and adds markers in the left margin. In this run, I means that a function was inlined. A loop unroll marker begins with U, followed by the unroll factor. A vectorisation marker begins with V; its numbers describe vector length and interleave factor. A report containing no markers is still a valid result: it means this input produced no displayed transformation of those kinds.

The output is text, not a replacement source file. Keep the original source beside it so line numbers and file names remain meaningful. If a line is shown more than once, the same optimisation pass was applied again and found more work on a later iteration.

4. Choose standard output or a safe destination

Omit -o when you want the report on standard output, for example when sending it to a pager:

$ llvm-opt-report-20 sample.opt.yaml | less

-o - is the explicit equivalent for standard output. Redirecting with > is convenient but can truncate an existing file before the command has finished. Use a new temporary name when replacing a report that matters:

$ llvm-opt-report-20 sample.opt.yaml -o sample.lst.new
$ test -s sample.lst.new
$ mv sample.lst.new sample.lst

The mv changes the report only after the new command has succeeded and produced a non-empty file. If the command fails, leave the old sample.lst in place and inspect the diagnostic. To recover from an accidental replacement, restore your copy from version control or your normal backup; llvm-opt-report-20 has no undo operation.

5. Handle input format and path options

The installed tool accepts yaml, yaml-strtab and bitstream through --format. Clang's normal -fsave-optimization-record output is YAML, so leave the option out unless the producer used another format:

$ llvm-opt-report-20 --format=yaml sample.opt.yaml -o sample-yaml.lst
$ test -s sample-yaml.lst && echo 'YAML report written'
YAML report written

Do not guess a format from a file name. A format mismatch produces a parser error, such as an unknown magic number when binary input is read as YAML. The -r ROOT option supplies the root used for relative input paths in the record. Use it when the record refers to source paths relative to a build root, and check the resulting file labels in the report before sharing it.

The manpage says that an omitted input or an input of - reads standard input. On the installed Ubuntu LLVM 20.1.8 binary, both forms attempt to open a file named - instead. Verify this on your own build before putting stdin into a script:

$ printf '%s\n' '---' | llvm-opt-report-20 -
error: Can't open file -: No such file or directory
$ printf '%s\n' '---' | llvm-opt-report-20
error: Can't open file -: No such file or directory

Use a real record filename in automation on this installation. This is a version-specific observed behaviour, not a reason to feed raw YAML through a shell pipeline.

6. Reduce detail only when you need to

--no-demangle leaves function names mangled, which can help when matching report entries to linker or symbol-tool output. -s suppresses vectorisation factors and similar detail. Both are presentation choices and do not change the compilation or the optimisation record:

$ llvm-opt-report-20 --no-demangle -s sample.opt.yaml -o compact.lst
$ sed -n '1,12p' compact.lst

Start with the default report. Add these options only when the extra detail is making a comparison or automated review harder. If you need to understand why an optimisation was missed, keep the original YAML record and examine the compiler's optimisation remarks as well; a compact listing is not a complete performance explanation.

7. Diagnose failures by exit status

The command returns 0 on success and 1 after an error message on standard error. A missing file is a safe diagnostic test:

$ llvm-opt-report-20 /path/to/missing.opt.yaml
error: Can't open file /path/to/missing.opt.yaml: No such file or directory
$ printf 'exit status: %s\n' "$?"
exit status: 1

For a real failure, check the path with ls -l, confirm read permission, and confirm that the producer wrote a record rather than an object or an empty file. If parsing fails, return to the compiler command and identify the record format it emitted. Keep the YAML record until the report has been reviewed, because it is the evidence needed to reproduce the conversion.