Compilation From Source¶
To build this project the following dependencies are needed on your system: cmake, make (for Linux and macOS), ninja (for Android), Visual Studio (for Windows) and a C++11 toolchain for the platform of your choice.
The compilation is a two-step process:
- A local binary distribution of the dependencies is built.
- QBDI is built using those binaries.
The current dependencies which need to be built are LLVM and Google Test. This local built of LLVM is required 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. This first step is cached and only needs to be run once, subsequent builds only need to repeat the second step.
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 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-linux-X86_64.sh
If the build script warns you of missing dependencies for your platform (in the case of a first compilation), or if you want to rebuild them, execute the following commands:
make llvm
make gtest
This will rebuild the binary distribution of those dependencies for your platform. You can then relaunch the configuration script from above and compile:
../cmake/config-linux-X86_64.sh
make -j4
Cross-compiling for ARM¶
The same step as above can be used but using the config-linux-ARM.sh
configuration script
instead. This script however needs to be customized for your cross-compilation toolchain:
- The right binaries must be exported in the
AS
,CC
,CXX
andSTRIP
environment variables. - The
-DCMAKE_C_FLAGS
and-DCMAKE_CXX_FLAGS
should contain the correct default flags for your toolchain. At least theARM_ARCH
,ARM_C_INCLUDE
andARM_CXX_INCLUDE
should be modified to match your toolchain but more might be needed.
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
)
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-macOS-X86_64.sh
If the build script warns you of missing dependencies for your platform (in the case of a first compilation), or if you want to rebuild them, execute the following commands:
make llvm
make gtest
This will rebuild the binary distribution of those dependencies for your platform. You can then relaunch the build script from above and compile:
../cmake/config-macOS-X86_64.sh
make -j4
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.
First, the config-win-X86_64.py
should be edited to use the generator (the -G
flag)
matching your Visual Studio installation. Then the following command should be run:
mkdir build
cd build
python ../cmake/config-win-X86_64.py
If the build script warns you of missing dependencies for your platform (in the case of a first compilation), or if you want to rebuild them, execute the following commands:
MSBuild.exe deps\llvm.vcxproj
MSBuild.exe deps\gtest.vcxproj
This will rebuild the binary distribution of those dependencies for your platform. You can then relaunch the build script from above and compile:
python ../cmake/config-win-X86_64.py
MSBuild.exe /p:Configuration=Release ALL_BUILD.vcxproj
Android¶
Cross-compiling for Android requires the Android NDK and has only been tested under Linux. The
config-android-ARM.sh
configuration script should be customized to match your NDK installation
and target platform:
NDK_PATH
should point to your Android NDKSDKBIN_PATH
should be completed to point to the toolchain to use inside the NDK.API_LEVEL
should match the Android API level of your target.- The right binaries must be exported in the
AS
,CC
,CXX
andSTRIP
environment variables (look at what is inside yourSDKBIN_PATH
).
From that point on the Linux guide can be followed using this configuration script.