Provided material
The complete material can be downloaded here.
This brief tutorial is intended to give you an overview on the Phasar program analysis tool. In this tutorial you can familiarize yourself with the LLVM IR, that is the intermediate representation that Phasar actually analyzes. Furthermore, you get an idea of how to execute Phasar, interpret its results and write a data-flow analysis on your own. To improve your experience with Phasar we have produced a couple of artifacts that you can download and use as starting points. These starting points include a:
- “Hello, World!”-Makefile-Project in LLVM
You can use this small Makefile project in order to get your head around LLVM and its intermediate representation. The “Hello, World!” program can be compiled using $ make. The resulting binary expects on .ll file (containing LLVM IR) as a command-line argument. The program parses the IR, validates it and iterates the instructions of the main function of your target code. If your target code does not contain a main function an error message will be reported. You can obtain LLVM IR for a given C/C++ file using the clang(++) compiler. Compile the source file you would like to analyze using $ clang(++) -emit-llvm -S <my source file .c/.cpp>
Then run your “Hello, World!” program on the resulting .ll file like $ ./hello_world <my IR file .ll>
The “Hello, World!” program iterates the instructions of main and prints them to the command-line. Within the inner-most loop you can analyze the instructions, check what kind of instruction it is and what its operands are. Feel free to change the analysis code and try to inspect the target IR as you like.
- Docker container containing an environment suitable for Phasar
We prepared a Docker container containing a UNIX-like system, all of the required dependencies as well as Phasar itself. Thus, you can code using your favorite editor and do not have to worry about VM drawbacks in terms of performance. In the running container just copy the folder pldi18_tutorial to /workspace and you can work with your favorite editor (e.g. Visual Studio Code) on your machine. You trigger compilation and execution manually in the docker container. Whenever we ask you to work in the pldi18_tutorial/analysis folder please adjust this to your workspace.
- VirtualBox machine image containing an Ubuntu OS, LLVM and Phasar
Additionally, we also prepared a VM image that can be imported into VirtualBox. This is probably the easiest way to get started as everything (including several IDEs) is already set-up for you. Running the VM can be, depending on your hardware, a bit demanding for your host machine. Make sure you check the VM parameters (like number of CPUs and the amount of RAM the VM shall use) before running it. The size of this image is roughly 9GB. This is our recommended option for systems running Windows. The super-secret password for the VM is “pldi18”. It comes as a complete working environment based on Ubuntu with pre-installed Visual Studio Code which we use, but feel free to add and use the editor of your choice.
- Build Phasar yourself
If you are feeling a bit adventurous or you would like to use Phasar more regularly, we recommend getting the source code and building it yourself. We tested it on a regular Ubuntu Linux and an Mac OS X High Sierra.
You will need the following dependencies (see below for options for specific operating systems):
* LLVM/Clang 5.0 (use the custom installation script we provided see phasar.org/download)
* SQLite 3.11.0 or newer (libsqlite3-dev)
* MySqlConnector (libmysqlcppconn-dev)
* LibCurl (libcurl4-openssl-dev)
* Zlib (zlib1g-dev)
* Boost 1.63.0 or newer (for common Linux distributions no stable package is available, it has to be self compiled, for Homebrew (MacOS) version 1.66.0 is available and it works)
* make
* CMake
* Python 3 (helpful, but not necessary)
You now clone our Git repository and its submodules:
> git clone https://github.com/secure-software-engineering/phasar.git
> cd phasar
> git submodule update --init --recursive
To install these dependencies on a Debian or Ubuntu Linux you can use these command (Please note that unless you are running a very, very recent Ubuntu installation, you still need to manually install Boost, as noted above):
> apt-get install sqlite3 libsqlite3-dev bear python3 git make cmake zlib1g-dev libncurses5-dev graphviz doxygen libcurl4-gnutls-dev libmysqlcppconn-dev
To install these dependencies on a Mac you can use Homebrew’s bundle functionality to install all dependencies (execute this directly in the cloned repository):
> brew bundle
Now you can compile using cmake:
> mkdir build
> cd build
> cmake ..
> make
> sudo make install
You can check if your installation works properly, by just typing in:
> phasar
You should see the version number and the command-line options for Phasar. If you do, you are now ready for the tutorial.