mirror of
https://github.com/lifting-bits/remill
synced 2026-06-21 13:56:07 +00:00
wizardengineer
135 lines
4.5 KiB
Markdown
135 lines
4.5 KiB
Markdown
# Remill [](https://slack.empirehacking.nyc/)
|
|
|
|
<p align="center">
|
|
<img src="docs/images/remill_logo.png" />
|
|
</p>
|
|
|
|
Remill is a static binary translator that translates machine code instructions into [LLVM bitcode](http://llvm.org/docs/LangRef.html). 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](https://github.com/lifting-bits/mcsema).
|
|
|
|
## Build Status
|
|
|
|
[](https://github.com/lifting-bits/remill/actions/workflows/build.yml)
|
|
|
|
## 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](docs/LIFE_OF_AN_INSTRUCTION.md)
|
|
- [How to implement the semantics of an instruction](docs/ADD_AN_INSTRUCTION.md)
|
|
- [The design and architecture of Remill](docs/DESIGN.md)
|
|
|
|
If you would like to contribute you can check out: [How to contribute](docs/CONTRIBUTING.md)
|
|
|
|
### API Documentation
|
|
|
|
Generate detailed API documentation using Doxygen:
|
|
|
|
```bash
|
|
# 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](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](https://slack.empirehacking.nyc/).
|
|
|
|
## 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:
|
|
|
|
| Name | Version |
|
|
| ---- | ------- |
|
|
| [Git](https://git-scm.com/) | Latest |
|
|
| [CMake](https://cmake.org/) | 3.21+ |
|
|
| [Ninja](https://ninja.build) | 1+ |
|
|
| [Google Flags](https://github.com/google/glog) | `52e94563` |
|
|
| [Google Log](https://github.com/google/glog) | v0.7.1 |
|
|
| [Google Test](https://github.com/google/googletest) | v1.17.0 |
|
|
| [LLVM](http://llvm.org/) | 15+ |
|
|
| [Clang](http://clang.llvm.org/) | 15+ |
|
|
| [Intel XED](https://github.com/intelxed/xed) | v2025.06.08 |
|
|
| [Python](https://www.python.org/) | 3+ |
|
|
|
|
## 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](docs/DEPENDENCIES.md).
|
|
|
|
### Clone the repository
|
|
|
|
```bash
|
|
git clone https://github.com/lifting-bits/remill
|
|
cd remill
|
|
```
|
|
|
|
### Linux/macOS
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
```
|