Compilation From Source
To build this project, the following dependencies are needed on your system:
cmake >= 3.12
ninja or make
C++17 toolchain (gcc, clang, Visual Studio 2019, …)
A local version of llvm is statically built within QBDI because QBDI uses private APIs not exported by regular LLVM installations and because our code is only compatible with a specific version of those APIs.
QBDI build system relies on CMake and requires to pass build configuration flags. To help with
this step we provide shell scripts for common build configurations which follow the naming pattern
config-OS-ARCH.sh. Modifying these scripts is necessary if you want to compile in debug mode or
Create a new directory at the root of the source tree, and execute the Linux configuration script:
mkdir build cd build ../cmake/config/config-linux-X86_64.sh ninja
You can follow the same instructions as for x86-64 but instead, use the
config-linux-X86.sh configuration script.
Compiling QBDI on macOS requires a few things:
A modern version of macOS (like Sierra)
Xcode (from the App Store or Apple Developer Tools)
the Command Line Tools (
a package manager (preferably MacPorts, but HomeBrew should also be fine)
some packages (
port install cmake wget ninja)
Once requirements are met, create a new directory at the root of the source tree, and execute the macOS configuration script:
mkdir build cd build ../cmake/config/config-macOS-X86_64.sh ninja
Building on Windows requires a pure Windows installation of Python 3 (from the official packages, this is mandatory) in order to build our dependencies (we really hope to improve this in the future). It also requires an up-to-date CMake and Ninja.
First of all, the Visual Studio environment must be set up. This can be done with a command such as:
"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x64
Then, the following commands must be run:
mkdir build cd build python ../cmake/config/config-win-X86_64.py ninja
Cross-compiling for Android requires the NDK (or the SDK) to be installed on your workstation.
For now, it has only been tested under Linux.
If not already installed, you can download the latest Android NDK package
through the official website
and extract it.
config-android-*.sh configuration script needs to be
customised to match your NDK installation directory and the target platform.:
# Configure and compile QBDI X86_64 with a NDK mkdir build && cd build NDK_PATH=<your_NDK_PATH> ../cmake/config/config-android-X86_64.sh ninja # Configure and compile QBDI X86 with a SDK mkdir build && cd build ANDROID_SDK_ROOT=<your_SDK_PATH> ../cmake/config/config-android-X86.sh ninja
The PyQDBI library (apart from the wheel package) can be built by solely passing the ‘-DQBDI_TOOLS_PYQBDI=ON’ option to the CMake build system.
However, if you want to build the wheel package, you can run these commands:
python -m pip install --upgrade pip python -m pip install setuptools wheel build python -m build -w
A 32-bit version of Python is mandatory for the X86 architecture whereas a 64-bit one is required for the X86-64 architecture.
The compilation of QBDI can be configured with the command line. Each parameter
should be placed on the command line with the form
QBDI_PLATFORM(mandatory) : Target platform of the compilation (supported:
QBDI_ARCH(mandatory) : Target architecture of the compilation (supported:
QBDI_CCACHE(default ON) : enable compilation optimisation with ccache or sccache.
QBDI_DISABLE_AVX(default OFF) : disable the support of AVX instruction on X86 and X86_64
QBDI_ASAN(default OFF) : compile with ASAN to detect memory leak in QBDI.
QBDI_LOG_DEBUG(default OFF) : enable the debug level of the logging system. Note that the support of this level has an impact on the performances, even if this log level is not enabled.
QBDI_STATIC_LIBRARY(default ON) : build the static library of QBDI. Note than some subproject need
QBDI_STATIC_LIBRARY(test, PyQBDI, …)
QBDI_SHARED_LIBRARY(default ON) : build the shared library of QBDI. Note than some subproject need
QBDI_SHARED_LIBRARY(Frida/QBDI, examples, …)
QBDI_TEST(default ON) : build the tests suite
QBDI_BENCHMARK(default OFF) : build the benchmark tools
QBDI_TOOLS_QBDIPRELOAD(default ON on supported platform) : build QBDIPreload static library (supported on Linux and OSX).
QBDI_TOOLS_VALIDATOR(default ON on supported platform) : build the validator library (supported on Linux and OSX).
QBDI_TOOLS_PYQBDI(default ON on X86_64) : build PyQBDI library. Supported on Linux, Windows and OSX.
QBDI_TOOLS_FRIDAQBDI(default ON) : add Frida/QBDI in the package.