A quick guide to getting started with LLVM

Required packages:

I'm assuming a GNU/Linux system (preferably Ubuntu) throughout this guide.
1. gcc/g++ - The gnu compiler collection. This is installed by default on every GNU/Linux system. You may need to install the libc header files, which some distributins skip by default. On Ubuntu:
     sudo apt-get install build-essentials
     sudo apt-get install g++
2. subversion - Though subversion is not really required to work on LLVM, I would recommend using it. You will learn to use a new version control system, and it does make development a little easier.
     sudo apt-get install subversion
2. cscope A good source code browsing tool.
     sudo apt-get install cscope

Pre-LLVM Setup:

You will need a directory somewhere on your hdd where in all LLVM related work will be done. Lets call that directory $LLVM_HOME. I will use this variable henceforth. If you would like to copy paste the commands as it is from this guide, define this variable in your ~/.bashrc file. For example, add a line similar to below in your ~/.bashrc file
     export LLVM_HOME=/media/data/llvm

Downloading LLVM:

Run the following commands:
     cd $LLVM_HOME
     svn co http://llvm.org/svn/llvm-project/llvm/tags/RELEASE_350/final llvm
     cd ${LLVM_HOME}/llvm/tools
     svn co http://llvm.org/svn/llvm-project/cfe/tags/RELEASE_350/final clang
"RELEASE_350" can be modified to match the latest release.

Building LLVM:

Run the following commands:
     cd $LLVM_HOME
     mkdir build
     mkdir install
     cd build
     ninja install

     - The "BUILD_SHARED_LIBS" option builds libLLVM as a shared library (.so) instead of as an archive (.a). This will reduce the link time on incremental builds and will reduce the space consumption to some extent, at the cost of extra starting time. Skip this if archive (static library) works fast on your system. (On my 1GB RAM machine, the linking time for "clang executable" came down from 15-20 min to 6-7 min).

Add the install/bin path to your ~/.bashrc file.
     export PATH=${LLVM_HOME}/install/bin:$PATH

Source Browsing/Tips:

Run the following commands to setup cscope and etags (ctags for VI is similar):
     cd ${LLVM_HOME}/llvm
     rm tags.lst
     find | grep "\.c$" >> tags.lst
     find | grep "\.cpp$" >> tags.lst
     find | grep "\.h$" >> tags.lst
     etags `cat tags.lst`
     cscope -i tags.lst
It is advisable to put these commands in a script and just run the script (may need to do often).
Also, if you are an emacs user, you might want to put the following code in your ~/.emacs file. This will ensure that the TAGS file is picked up by default (without having to specify it everytime)
      (setq tags-file-name
IMPORTANT: Please replace ${LLVM_HOME} in the previous line by the actual path.

Writing a Simple Pass:

I will not explain the details of what will be in the pass here. That is already explained well in the "How to write an LLVM pass" section of the LLVM docs. What I try to show here is to write the pass as a part of the main libLLVM library rather than as a separate shared object (as is shown in the official doc). The source file to be used for this pass is in ${LLVM_HOME}/llvm/lib/Transforms/Hello/Hello.cpp.
     cp ${LLVM_HOME}/llvm/lib/Transforms/Hello/Hello.cpp ${LLVM_HOME}/llvm/lib/Transforms/Scalar/
     cd ${LLVM_HOME}/build
     make install
You can now see the new pass if you try
     opt -help
Look at the LLVM guides on how to trigger this pass and how to make use of it.

TIPS: For non-trivial passes, you will need to initialize the pass and specify required analysis etc. Have a look at other similar passes on how they do this.
    - You may need to add your pass in Passes.cpp for it to kick in at the right place. This is better than registering your pass as is in the official guide. You can turn on/off your pass via a hidden command line flag.
    - You need to add a declaration of "initializeYourPassNamePass" to InitializePasses.h/CodeGen.cpp.


Basic regression testing can be done as follows (these are compile only tests):
     cd ${LLVM_HOME}/build/test/
The full test suite, which includes executable and performance tests can be setup and run as follows:
     sudo apt-get install virtualenvwrapper
     virtualenv ${LLVM_HOME}/sandbox
     svn co http://llvm.org/svn/llvm-project/lnt/trunk ${LLVM_HOME}/lnt
     ${LLVM_HOME}/sandbox/bin/python ${LLVM_HOME}/lnt/setup.py develop
     svn co http://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_350/final ${LLVM_HOME}/test-suite
     ${LLVM_HOME}/sandbox/bin/lnt runtest nt --sandbox ${LLVM_HOME}/test-suite-build --cc ${LLVM_HOME}/install/bin/clang --test-suite ${LLVM_HOME}/test-suite
In case you need to pass a flag to llvm (for example to enable your pass), add this argument to the command above
If you want to run only a subset of the test-suite, add something like below (this will run only the tests in "SingleSource" directory).
     --only-test SingleSource

Running SPEC benchmarks:
  Extract and place the SPEC benchmark in ${LLVM_HOME}/spec. For example, if you're using speccpu2006, ${LLVM_HOME}/spec should contain a sub directory called "speccpu2006", which contains the root of the spec suite. Note that the directory name "speccpu2006" is important as the script is programmed to automatically recognize known names (spec95, speccpu200, speccpu2006 etc).
Give the following argument to the lnt script above to run the spec benchmark suite.
To run only the spec benchmark (and avoid running the LLVM test-suite), use "--only-test External". NOTE: running SPEC like this doesn't really do a "ref" input run. So use it only as a correctness test and not really for performance numbers.

Usefule Links

      1. Official LLVM Getting Started
      2. Official How to Write an LLVM Pass
      3. LLVM Testing Guide
      4. LNT Quick Start
      5. Emacs reference
      6. A sample gdbinit file

Any suggestions and feedbacks are appreciated.
Contact: vaivaswatha[at]yahoo[dot]co[dot]in
\A9Copyright <2012> <Vaivaswatha N>