Hacking on LLVM

Some useful tips for debugging LLVM source code with VSCode on Linux (all commands below assume a bash shell). It is not a substitute for the excellent LLVM documentation

If you find this content useful and want to say thanks, consider buying me a coffee!

Compiling from source

Some packages you will need:

# optional
Compilation commands:
git clone https://github.com/llvm/llvm-project.git
mkdir build

# make sure you have cmake and build dependencies (go to llvm.org)
# LLVM will NOT build with pre-c++14 compiler
# Optionally, you can build with RelWithDebInfo for a slightly smaller build (still with debug symbols)
cmake -DLLVM_ENABLE_PROJECTS="clang;lldb;clang-tools-extra" -DCMAKE_BUILD_TYPE=Debug ../llvm-project/llvm

# build may take a couple of minutes to 1-2 hours depending on your hardware

Note if you want to also build LLDB, you should instead use -DLLVM_ENABLE_PROJECTS="clang;lldb". Note, this will default to the default CC and CXX compilers on your system. I highly advise using clang/clang++ so you can debug with LLDB

export CC=clang
export CXX=clang++

Debugging clang with VSCode

Required extensions

I highly suggest you use LLDB instead of GDB, and clangd for code navigation. You can get the LLDB/clangd extensions for free in VSCode, and configure clangd to use the executable you just built from source.


clang itself is composed of 2 parts, the driver and the actual invocation into the FE. Thus, to get the actual call into the compiler for a simple program, you need to issue the -v flag:

clang++ -v foo.cpp

This will run the driver in verbose mode and will output a call to clang with the cc1 flag and a bunch of other flags. This is the actual command you want to use as a debug target within VSCode. To quickly convert the space separated string into a JSON friendly encoding for VSCode, you can run the following:

awk -v RS='' -v OFS='","' 'NF { $1 = $1; print "\"" $0 "\"" }' command.txt
Then create a simple VSCode debug target with contents similar to:
    "version": "0.2.0",
    "configurations": [
            "type": "lldb",
            "request": "launch",
            "name": "Debug",
            "program": "/media/luis/TI10657400D/llvm/build/bin/clang++",
            "args": [
            "cwd": "${workspaceFolder}"

You should now be able to set breakpoints anywhere in the compiler. A good starting point to set a breakpoint is in CodeGenModule::CodeGenModule.

Debugging Notes

Clang notes


Backend/Code Generators

See https://releases.llvm.org/6.0.1/docs/CodeGenerator.html

Useful commands

Once you're stopped at a breakpoint in VSCode, there are a couple of useful commands you can call from LLDB to inspect the state of the IR. Some of which include:

Additional Resources

The list below is a non exhaustive list of all resources I found helpful while hacking on LLVM. I take no credit for them. They are listed in no particular order.


gem5.opt --debug-help | less gem5.opt --debug-flags=XXX sudo apt-get install libc6-armel-cross libc6-dev-armel-cross binutils-arm-linux-gnueabi Building ARM on x86 sudo apt-get install libstdc++-10- MIPS: sudo apt-get install libstdc++-10-dev-mipsel-cross apt-get install binutils-mipsel-linux-gnu sudo apt-get install gcc-mips-linux-gnu Generate code (MIPS): clang -static --target=mipsel-linux-gnu test.c Run code on GEM5: ./gem5.opt ../../configs/example/se.py -c ~/sandbox/a.out

Last modified: January 27 2021