This is an update of my previous post “How to build LLVM from source” (2018-04-16), which is now out-of-date. LLVM has moved to a “monorepo” design instead of a collection of smaller tool-specific repositories. So this new post has fewer steps!

The LLVM codebase’s official home is https://github.com/llvm/llvm-project.

(However, to submit patches to LLVM projects, you must use the official Phabricator; don’t submit GitHub pull requests against llvm/llvm-project! At least not as of November 2019.)

Step 1: Fork!

Go to your GitHub account and fork the following repository:

• llvm/llvm-project

Step 2: Get the code!

Locally clone the repo to the right place.

cd $ROOT
git clone git@github.com:llvm/llvm-project

This is a good time to set up the .git/config for the repo you just cloned (for example, $ROOT/llvm-project/.git/config). I set it up this way:

[remote "origin"]
    url = git@github.com:Quuxplusone/llvm-project.git
    fetch = +refs/heads/*:refs/remotes/origin/*
[remote "upstream"]
    url = git@github.com:llvm/llvm-project.git
    fetch = +refs/heads/*:refs/remotes/upstream/*
[branch "master"]
    remote = upstream
    merge = refs/heads/master

This gives me two remotes: one named upstream whence I can pull, and one named origin whither I can push. My local master and origin/master will both track upstream/master. Anything I do in my local repo, I will do in a feature branch; my feature branches will track origin.

Step 3: Build!

mkdir $ROOT/llvm-project/build
cd $ROOT/llvm-project/build
cmake -G 'Unix Makefiles' \
    -DLLVM_ENABLE_PROJECTS="clang;libcxx;libcxxabi" \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo ../llvm
make -j5 clang
make -j5 check-clang

If you omit -DCMAKE_BUILD_TYPE=RelWithDebInfo, this first part will still work, but you’ll produce a “debug-build” version of clang that is super slow, and then the “bootstrap” step below will take days instead of minutes. So watch out for that.

make -j5 clang takes about 96 minutes on my laptop. make -j5 check-clang takes another 38 minutes (24 minutes to build a bunch of additional tools, and then another 14 minutes to run the actual tests).

Making clang will build both clang and clang++. Making cxx will build libc++.dylib, libc++.a, and libc++abi.dylib. Making cxxabi will build libc++abi.a. Making check-cxx will build libc++experimental.a.

However, I have found that make cxx doesn’t work with the system compiler on OS X 10.13. I get errors like this (where __ZTIDu is the mangled name of typeinfo for char8_t):

[ 60%] Linking CXX shared library ../../../lib/libc++abi.dylib
Undefined symbols for architecture x86_64:
  "__ZTIDu", referenced from:
     -exported_symbol[s_list] command line option

If you get these same errors with make cxx, then you should just make clang and then follow the instructions under “Bootstrap,” below, to build cxx with your bootstrapped Clang instead of the system compiler.

If something goes wrong, you can usually recover via

rm $ROOT/llvm-project/build/CMakeCache.txt

and, absolute worst case, you can blow away $ROOT/llvm-project/build and start over.

Step 4: Run specific tests.

Running a specific test or directory-of-tests for any product is easy:

cd $ROOT/llvm-project/build
./bin/llvm-lit -sv ../llvm/test/Analysis
./bin/llvm-lit -sv ../clang/test/ARCMT
./bin/llvm-lit -sv ../libcxx/test/std/re

However, it looks like before you can successfully run one of these lines, you must have run the corresponding one of make check-{llvm,clang,cxx} at least once, to initialize the right stuff in the build directory.

(Thanks to Brian Cain for documenting this recipe.)

But watch out! Both make check-cxx and llvm-lit will by default use your system compiler to run the libc++ tests! This is not what you want! Tell llvm-lit to use your newly built Clang by passing the cxx_under_test parameter, like this:

make -j5 clang
make -j5 cxx
./bin/llvm-lit -sv --param cxx_under_test=`pwd`/bin/clang ../libcxx/test/

Step 5: Bootstrap!

Here we will not be installing Clang over top of the system compiler (super dangerous!); but we will instruct CMake to build Clang using the previously built Clang.

There is apparently an official way to bootstrap Clang (probably out-of-date).

However, when I bootstrap Clang, I use this crude approach inspired by the CMake FAQ:

mkdir $ROOT/llvm-project/build2
cd $ROOT/llvm-project/build2
CXX="$ROOT/llvm-project/build/bin/clang++" \
cmake -G 'Unix Makefiles' \
    -DLLVM_ENABLE_PROJECTS="clang;libcxx;libcxxabi" \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo ../llvm
make -j5 clang VERBOSE=1

(This takes the same 96 minutes as the original make -j5 clang did.)

Now you have built two versions of clang++: $ROOT/llvm-project/build/bin/clang++ is the version built with your system compiler, and $ROOT/llvm-project/build2/bin/clang++ is the version built with that version. You can extend this to build3, build4, etc.