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 cross-compile QBDI.

Linux

x86-64

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

x86

You can follow the same instructions as for x86-64 but instead, use the config-linux-X86.sh configuration script.

macOS

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 (xcode-select --install)

  • 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

Windows

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

Android

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. Afterwards, the 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

PyQBDI compilation

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.

CMake Parameters

The compilation of QBDI can be configured with the command line. Each parameter should be placed on the command line with the form -D<param>=<value>.

  • QBDI_PLATFORM (mandatory) : Target platform of the compilation (supported: windows, linux, android, osx)

  • QBDI_ARCH (mandatory) : Target architecture of the compilation (supported: X86_64, X86)

  • 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.