Document building against local LLVM

[Baltoli]

I've had to do this previously for testing version changes that aren't in my distro's package manager, or for the rarer case where we've had to make changes to upstream LLVM. Each time I find myself repeating the same process of rebuilding LLVM locally, figuring out the right CMake options, and so on.

We should document the process, as well as how the build system interacts with an LLVM installation, to avoid this kind of repeated work in the future.

This issue will be a staging area for documenting my process this time round, while I work through it.

[Baltoli]

Getting the LLVM code from github:

git clone [email protected]:llvm/llvm-project.git

Checking out the version you want to build (here, in my case I want to compare the backend's behaviour on 15 vs 16)¹:

cd llvm-project
git checkout llvmorg-15.0.7 # or...
git checkout llvmorg-16.0.6

Building LLVM with Ninja²:

mkdir build
cd build
cmake ../llvm \
  -GNinja \
  -DLLVM_ENABLE_PROJECTS='clang' \
  -DCMAKE_INSTALL_PREFIX=$llvm_install_path \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  -DLLVM_TARGETS_TO_BUILD=host \
  -DLLVM_BUILD_LLVM_DYLIB=On
ninja install

The -DLLVM_BUILD_LLVM_DYLIB=On option is needed - I think - for the backend build system's use of -lLLVM rather than the old style of linking each of the LLVM components individually.

Get a cup of coffee here; it takes a long time to build even on a decent machine.

Build the backend against this custom version of LLVM:

cd $llvm_backend_dir
mkdir build
cd build
export PATH="$llvm_install_path:$PATH"
cmake .. -GNinja \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_INSTALL_PREFIX=install \
  -DGC_THRESHOLD=1 \
  -DBUILD_TESTS=On
ninja install

Note that to get the backend to accept a custom version of LLVM, the usual LLVM_DIR incantation doesn't work - this is because LLVMKompilePrelude.cmake needs to do some (non-idiomatic, but necessary) looking up of tools like clang on the PATH.

See also #808 for a related issue.

Footnotes

1. Probably won't be critical, but make sure the correct minor version is set. ↩

2. Needs a lot of disk space to build the version with debug info enabled (~60GB on my machine) ↩

[Baltoli]

Didn't end up needing this in the end.