A tool for analyzing LLVM bitcode (generated either by C or C++) using Datalog.
This project uses a commercial Datalog engine, developed by LogicBlox Inc..
- A 64-bit flavor of Linux. Verify that you're running 64-bit Linux by running:
uname -mwhich should return x86_64.
- At least 4GB of available memory.
- Python 2.7 or newer (but not Python 3.x). Available from the Python Website
- Java Developer Kit version 6 or newer. Available from Oracle's Java website
Install the LogicBlox engine
The LogicBlox engine needs to be installed. We recommend the PA-Datalog engine, which is a modified LogicBlox v3 engine, intended for use in program analysis projects.
(Alternatively, you can download a full-fledged LogicBlox engine (version 3.*) from the LogicBlox Download Page. You will need to [request an academic license] (http://www.logicblox.com/learn/academic-license-request-form/).)
You must also set the environment variable
$PATH accordingly. The following additions to either
.bash_profile should suffice, assuming that you
have extracted the engine to
/opt/lb/. If not, adjust the following
export LOGICBLOX_HOME=/opt/lb/logicblox-3.10.14/logicblox export PATH=$LOGICBLOX_HOME/bin:$PATH
This step is not needed for newer Linux distributions, where you can install LLVM version 3.7 (or later) from the system's package manager.
- Download LLVM 3.7.0 pre-built binary from the LLVM Download Page.
- Untar the downloaded file to a destination path of your choice
/opt/llvm/) and modify permissions accordingly.
- Add the
$PATH(by modifying your
You will also have to install the following packages:
Fedora 20, 21, 22
# yum install boost-devel boost-python protobuf-devel python-pip python-devel
# dnf install boost-devel boost-python protobuf-devel python-pip python-devel # dnf install llvm-devel clang-devel
# apt-get install build-essential libboost-dev libboost-filesystem-dev libboost-program-options-dev libboost-python-dev libprotobuf-dev libprotoc-dev protobuf-compiler python-pip python-dev
In latest distro versions, that have switched to gcc 5, the binary compatibility between clang and gcc is broken (see bug 23529). So, the pre-built LLVM binaries will not work there.
Instead, for Ubuntu 15.10, you can:
Skip the pre-built binary download step entirely, but otherwise follow the (Ubuntu) instructions
Additionally install LLVM 3.7 and libedit from the system's package manager by running:
# apt-get install llvm-3.7 libedit-dev
When compiling the project, run
(venv)$ LLVM_CONFIG=llvm-config-3.7 make (venv)$ make install
To be able to easily customize your analysis via a configuration file,
you will also need to install the
The default user configuration will be automagically installed at
~/.config/cclyzer/config.yaml the first time you run the tool. Then,
you can tweak this config file, e.g., to change the printed statistics
and the loaded logic modules.
We recommend first to create a virtual environment by running:
$ pip install virtualenv # if not already installed $ cd /path/to/cclyzer/ $ virtualenv venv
To activate the virtual environment, run:
$ . venv/bin/activate (venv)$ # <--- your prompt should change to something like this
Now, while inside the virtualenv, build
cclyzer as follows:
(venv)$ make (venv)$ make install
Then, you should be able to run the main
cclyzer script that analyzes
LLVM Bitcode. Try:
(venv)$ cclyzer -h (venv)$ cclyzer analyze -h
The basic test suite comprises the GNU Core Utilities.
You may run all the tests with:
$ make tests.run
or a particular test, e.g.,
$ make test-stty
It is also possible to invoke a python interpreter for a more interactive experience:
$ python >>> from cclyzer import * >>> config = AnalysisConfig('./tests/coreutils-8.24/sort.bc', output_dir='./build/tests/sort') >>> analysis = Analysis(config) >>> analysis.run() ... >>> print analysis.stats # instructions : 25417 # functions : 438 # app functions : 317 ... >>>
The warnings and errors that may come up during execution are not very
informative. Instead, the log file located at
$XDG_CACHE_HOME/cclyzer/cclyzer.log (which at most systems defaults to
~/.cache/cclyzer/cclyzer.log), or the system log, can be much more