Remill

Remill is a static binary translator that translates machine code instructions into LLVM bitcode. It translates AArch64 (64-bit ARMv8), SPARC32 (SPARCv8), SPARC64 (SPARCv9), x86 and amd64 machine code (including AVX and AVX512) into LLVM bitcode. AArch32 (32-bit ARMv8 / ARMv7) support is underway.

Remill focuses on accurately lifting instructions. It is meant to be used as a library for other tools, e.g. McSema.

Build Status

Documentation

To understand how Remill works you can take a look at the following resources:

• Step-by-step guide on how Remill lifts an instruction
• How to implement the semantics of an instruction
• The design and architecture of Remill

If you would like to contribute you can check out: How to contribute

API Documentation

Generate detailed API documentation using Doxygen:

# Install Doxygen (macOS)
brew install doxygen graphviz

# Install Doxygen (Ubuntu/Debian)
sudo apt-get install doxygen graphviz

# Generate documentation
doxygen

# Open docs/doxygen/html/index.html in your browser

See docs/DOCUMENTATION.md for more details on documentation style and contributing.

Getting Help

If you are experiencing undocumented problems with Remill then ask for help in the #binary-lifting channel of the Empire Hacking Slack.

Supported Platforms

Remill is supported on Linux platforms and has been tested on Ubuntu 22.04. Remill also works on macOS, and has experimental support for Windows.

Remill's Linux version can also be built via Docker for quicker testing.

Dependencies

Remill uses the following dependencies:

Getting and Building the Code

We will build the project using the superbuild in dependencies/. For more details on the dependency management system, see Remill Dependency Management.

Clone the repository

git clone https://github.com/lifting-bits/remill
cd remill

Linux/macOS

# Step 1: Build dependencies (including LLVM)
cmake -G Ninja -S dependencies -B dependencies/build
cmake --build dependencies/build

# Step 2: Build remill
cmake -G Ninja -B build -DCMAKE_PREFIX_PATH:PATH=$(pwd)/dependencies/install -DCMAKE_BUILD_TYPE=Release
cmake --build build

Windows (requires clang-cl)

Note: This requires running from a Visual Studio developer prompt.

# Step 1: Build dependencies
cmake -G Ninja -S dependencies -B dependencies/build -DCMAKE_C_COMPILER=clang-cl -DCMAKE_CXX_COMPILER=clang-cl
cmake --build dependencies/build

# Step 2: Build remill
cmake -G Ninja -B build -DCMAKE_PREFIX_PATH:PATH=%CD%/dependencies/install -DCMAKE_C_COMPILER=clang-cl -DCMAKE_CXX_COMPILER=clang-cl -DCMAKE_BUILD_TYPE=Release
cmake --build build

macOS with Homebrew LLVM:

# Install LLVM via Homebrew
brew install llvm@17
LLVM_PREFIX=$(brew --prefix llvm@17)

# Build dependencies with external LLVM
cmake -G Ninja -S dependencies -B dependencies/build -DUSE_EXTERNAL_LLVM=ON "-DCMAKE_PREFIX_PATH:PATH=$LLVM_PREFIX"
cmake --build dependencies/build

# Build remill
cmake -G Ninja -B build "-DCMAKE_PREFIX_PATH:PATH=$(pwd)/dependencies/install" -DCMAKE_BUILD_TYPE=Release
cmake --build build

Linux with system LLVM:

# Build dependencies with external LLVM
cmake -G Ninja -S dependencies -B dependencies/build -DUSE_EXTERNAL_LLVM=ON
cmake --build dependencies/build

# Build remill
cmake -G Ninja -B build "-DCMAKE_PREFIX_PATH:PATH=$(pwd)/dependencies/install" -DCMAKE_BUILD_TYPE=Release
cmake --build build