Here I’ll present things that I learned while working on LLVM compiler. You may find here basics on how to checkout the source and how to build it, how is the source organized or how to use gdb to debug some problems.
Here is a sequence of commands which may be handy when debugging with GDB. It’s a sequence which allows you to go through the execution and log all the output into a file. And it does that automatically.
set logging file output-file.log
set height 0
set logging on
set logging redirect
while 1
si
end
with first command we set a output file where we expect our log after the execution
set height sets our screen size, overriding it to 0, so we don’t get messages like this:
“—Type <return> to continue, or q <return> to quit—“
logging on enables logging
and logging redirect doesn’t show output on the screen (which slightly speeds up the process)
while loop executes commands inside the loop while the program is running. Instead si, you can use n, ni, s or any other like p or maybe x/i $pc. Just be sure to use at least one command like s or n (which execute), so that you don’t end up with the loop running indefinitely.
Regardless I’ll explain the checkout and build procedure here in my words, emphasizing things that were unclear to me when I was checking out the Clang/LLVM for the first.
Wyvern, the LLVM logo
Checkout
So first thing is to choose a version control software which you want to use. You can choose between SNV and GIT. Checkout here a bit more on that.
At the moment of writing this text LLVM is using SVN primarily, but there is GIT repo and initiative to move it to GIT primarily (https://llvm.org/docs/Proposals/GitHubMove.html).
Anyway when you decide between SVN and GIT, you can use it to checkout the project. Use following commands in terminal:
svn co http://llvm.org/svn/llvm-project/cfe/trunk llvm-src/tools/clang
Now you have clang in your llvm-src/tools directory (just the place it should be).
So from this step, let’s try to build it for your platform (x86 I guess).
Building process
The code you have checked out is a source code. From that code you are gonna build a project into executable binaries. First, create a folder where you want your build to stay. Let’s call it llvm-build, and then enter it.
mkdir llvm-build cd llvm-build
Now execute following command, with appropriate modification if the path to your llvm-src folder is different.
First option ‘-DCMAKE_BUILD_TYPE=Debug‘ means that the project will be built in Debug mode, which will allow you to run it in gdb. If you don’t need it, replace Debug with Release.
Second option ‘-DBUILD_SHARED_LIBS=True‘ means that libraries will not be linked statically, which will result in much faster compilation and the process will be less memory hungry. If you don’t have specific reason to link it differently, use this one, trust me.
The last one i the path to the source folder.
Press enter, and watch how cmake is configuring a build. It might happen that you don’t have some libraries or necessary tools on your system; in that case cmake will result in error. Just install these tools, and then run it again. If you believe that cmake got stuck, and every time you run it, it just doesn’t work for some weird reason, you can also run this command from the llvm-build folder:
rm -rf *
Be careful with this command and take care that you are in the folder llvm-build. Then run cmake again.
Once cmake finishes successfully, hit the following command:
nice make -j6
Now go for coffee break or enjoy watching your llvm building.
Testing if everything is fine
LLVM and Clang come with a bunch of tests that verify that everything works as expected. When some developer implements a new feature, he/she also provides a test for that feature. So when someone else is working on LLVM, they can easily check if they did not break something. These tests are called Regression tests, and they don’t cover all possible functionalities, so if you implement a new feature and none of the tests fail, that does not mean you did a good job. Furthermore, you should think about test you can write that is going to test all cases of your new feature.
Anyway, to run these tests, type the following:
make check
or:
make check-all
You can also type something like this:
make check-llvm-codegen-mips
which will check only llvm, part codegen, and architecture mips. Go and check the tests folder structure to figure out what I am talking about.
When you need to test only one test, not a bunch of them like in previous cases, you can do that with llvm-lit script located under the llvm-build/bin folder. Simply type a llvm-lit and a path to a test you want to run. Example:
Please note that sometimes developers make mistakes, and freshly checked out Clang/LLVM may have some broken tests. In such situation, just update your local repo and run the build and tests again.
More testing
Beside regression tests, there is also a test suite that you can checkout, build tests and run. But I’ll write more about that in some other posts later.
