Skip to content

Building

We mostly rely on a build container, but some dependencies are still needed outside that container: our fork of LLVM20, a local copy of lld, and LLVM LIT.

In order to set up those and build Patchestry, please follow the first-time instructions for your development environment of choice: - macOS - Linux

See also: Development

First Time Development Setup: MacOS

  1. Install Xcode from the App Store and set up the command line tools: 

    xcode-select --install

  2. Install the required dependencies using Homebrew: 

    # basics
brew install colima docker docker-buildx docker-credential-helper cmake lit
# to run tests, we need to cross-compile for x86-64/Linux and aarch64/Linux
brew install FiloSottile/musl-cross/musl-cross

  3. Configure Docker BuildX to work with Colima: 

    mkdir -p ~/.docker/cli-plugins
ln -s $(which docker-buildx) ~/.docker/cli-plugins/docker-buildx
colima restart
docker buildx version

  4. Log into Docker Hub (this may not be needed - it is not needed on Linux): 

    docker login -u <username>

  5. For building ClangIR, clone the project and compile with the following CMake configuration: 

    cmake -G Ninja ../../llvm \
    -DCMAKE_INSTALL_PREFIX="/path/to/installdir" \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DLLVM_ENABLE_PROJECTS="clang;mlir;clang-tools-extra" \
    -DLLVM_ENABLE_ASSERTIONS=ON \
    -DCLANG_ENABLE_CIR=ON \
    -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
    -DLLVM_ENABLE_RTTI=ON \
    -DLLVM_INSTALL_UTILS=ON \
    -DLLVM_TARGETS_TO_BUILD="host;AArch64;ARM;X86"

The targets list of "host;AArch64;ARM;X86" is intentional (to always build host arch, AArch64, ARM, and x86), even if host arch is almost certainly either AArch64 or X86.

  1. Build with: 
    CC=$(which clang) CXX=$(which clang++) cmake \
   --preset default \
   -DCMAKE_PREFIX_PATH=<path_to_llvm_install>/lib/cmake/ \
   -DLLVM_EXTERNAL_LIT=$(which lit)

This setup provides a complete development environment for building and running the project on MacOS. The configuration uses Colima as a Docker backend, which provides better performance and resource management compared to Docker Desktop on MacOS.

First Time Development Setup: Linux

If you'd like to either follow step by step instructions or run a script to automatically follow them in a fresh Linux instance, here's a Gist that sets everything up from zero in a fresh VM for you and runs the Patchestry tests to confirm the setup works. This Gist should stay reasonably up to date since it's used to initialize ephemeral coding environments. It's been tested on Ubuntu 24.04. The only thing that should be different for other Ubuntus or for Debian is the apt package naming.

Steps followed in the Gist to get to a working install: 1. Base dependency install (Docker, lld, build tools such as CMake) 2. Acquire LLVM LIT from Python Pip 3. Build and install LLVM 4. Build and install Patchestry 5. Build the headless container in the Patchestry repository (this should set up and install Ghidra and everything else) 6. Run tests for Patchestry, which requires the container / occurs in the container

Development

CMake Commands

  • to build, see the command referenced in step 6 above or the commands used for Linux. You'll use the default preset to configure and most likely the debug or release presets for the subsequent build command after configuration.
  • to run tests, ensure the headless container is available first by running scripts/ghidra/build-headless-docker.sh, then you may cmake --build builds/default/ -j$((nproc+1)) --preset debug --target test (using the preset of your choice but selecting the test target)

Ghidra

Installing Ghidra Locally

You shouldn't need to do this directly in the current build most of the time. Prefer working in the headless container. You may want Ghidra locally for Ghidra script debugging.

Get Java JDK (x64) 

wget -c https://download.oracle.com/java/22/latest/jdk-22_linux-x64_bin.tar.gz -O jdk.tar.gz
tar xvf jdk.tar.gz
mv jdk-22.0.1 ~/jdk
echo "export PATH=\$PATH:~/jdk/bin" >> ~/.bashrc

Get Ghidra 

wget -c https://github.com/NationalSecurityAgency/ghidra/releases/download/Ghidra_11.1.1_build/ghidra_11.1.1_PUBLIC_20240614.zip -O ghidra.zip
unzip ghidra.zip
mv ghidra_11.1.1_PUBLIC ~/ghidra