Skip to content

Commit 9ce12a0

Browse files
mrexodiakyle-elliott-tob
mrexodia
authored and
kyle-elliott-tob
committed
Update README with new dependencies
1 parent 9a6868a commit 9ce12a0

File tree

2 files changed

+93
-124
lines changed

2 files changed

+93
-124
lines changed

‎README.md‎

Lines changed: 49 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -34,157 +34,82 @@ Remill's Linux version can also be built via Docker for quicker testing.
3434

3535
## Dependencies
3636

37-
Most of Remill's dependencies can be provided by the [cxx-common](https://github.com/lifting-bits/cxx-common) repository. Trail of Bits hosts downloadable, pre-built versions of cxx-common, which makes it substantially easier to get up and running with Remill. Nonetheless, the following table represents most of Remill's dependencies.
37+
Remill uses the following dependencies:
3838

3939
| Name | Version |
4040
| ---- | ------- |
4141
| [Git](https://git-scm.com/) | Latest |
42-
| [CMake](https://cmake.org/) | 3.14+ |
43-
| [Google Flags](https://github.com/google/glog) | Latest |
44-
| [Google Log](https://github.com/google/glog) | Latest |
45-
| [Google Test](https://github.com/google/googletest) | Latest |
42+
| [CMake](https://cmake.org/) | 3.21+ |
43+
| [Ninja](https://ninja.build) | 1+ |
44+
| [Google Flags](https://github.com/google/glog) | `52e94563` |
45+
| [Google Log](https://github.com/google/glog) | v0.7.1 |
46+
| [Google Test](https://github.com/google/googletest) | v1.17.0 |
4647
| [LLVM](http://llvm.org/) | 15+ |
47-
| [Clang](http://clang.llvm.org/) | 15 |
48-
| [Intel XED](https://software.intel.com/en-us/articles/xed-x86-encoder-decoder-software-library) | Latest |
49-
| [Python](https://www.python.org/) | 2.7 |
50-
| Unzip | Latest |
51-
| [ccache](https://ccache.dev/) | Latest |
48+
| [Clang](http://clang.llvm.org/) | 15+ |
49+
| [Intel XED](https://github.com/intelxed/xed) | v2022.04.17 |
50+
| [Python](https://www.python.org/) | 3+ |
5251

5352
## Getting and Building the Code
5453

55-
### Docker Build
54+
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).
5655

57-
Remill now comes with a Dockerfile for easier testing. This Dockerfile references the [cxx-common](https://github.com/lifting-bits/cxx-common) container to have all pre-requisite libraries available.
56+
### Clone the repository
5857

59-
The Dockerfile allows for quick builds of multiple supported LLVM, and Ubuntu configurations.
60-
61-
> [!IMPORTANT]
62-
> Not all LLVM and Ubuntu configurations are supported---Please refer to the CI results to get an idea about configurations that are tested and supported. The Docker image should build on both x86_64 and ARM64, but we only test x86_64 in CI. ARM64 _should build_, but if it doesn't, please open an issue.
63-
64-
Quickstart (builds Remill against LLVM 17 on Ubuntu 22.04).
65-
66-
Clone Remill:
67-
68-
```shell
69-
git clone https://github.com/lifting-bits/remill.git
58+
```bash
59+
git clone https://github.com/lifting-bits/remill
7060
cd remill
7161
```
7262

73-
Build Remill Docker container:
74-
75-
```shell
76-
docker build . -t remill \
77-
-f Dockerfile \
78-
--build-arg UBUNTU_VERSION=22.04 \
79-
--build-arg LLVM_VERSION=17
80-
```
81-
82-
Ensure remill works:
83-
84-
Decode some AMD64 instructions to LLVM:
85-
86-
```shell
87-
docker run --rm -it remill \
88-
--arch amd64 --ir_out /dev/stdout --bytes c704ba01000000
89-
```
90-
91-
Decode some AArch64 instructions to LLVM:
92-
93-
```shell
94-
docker run --rm -it remill \
95-
--arch aarch64 --address 0x400544 --ir_out /dev/stdout \
96-
--bytes FD7BBFA90000009000601891FD030091B7FFFF97E0031F2AFD7BC1A8C0035FD6
97-
```
98-
99-
### On Linux
100-
101-
First, update aptitude and get install the baseline dependencies.
102-
103-
```shell
104-
sudo dpkg --add-architecture i386
105-
sudo apt-get update
106-
sudo apt-get upgrade
107-
108-
sudo apt-get install \
109-
git \
110-
python3 \
111-
wget \
112-
curl \
113-
build-essential \
114-
lsb-release \
115-
ccache \
116-
libc6-dev:i386 \
117-
'libstdc++-*-dev:i386' \
118-
g++-multilib \
119-
rpm
120-
```
63+
### Linux/macOS
12164

122-
Next, clone the repository. This will clone the code into the `remill` directory.
65+
```bash
66+
# Step 1: Build dependencies (including LLVM)
67+
cmake -G Ninja -S dependencies -B dependencies/build
68+
cmake --build dependencies/build
12369

124-
```shell
125-
git clone https://github.com/lifting-bits/remill.git
70+
# Step 2: Build remill
71+
cmake -G Ninja -B build -DCMAKE_PREFIX_PATH=$(pwd)/dependencies/install -DCMAKE_BUILD_TYPE=Release
72+
cmake --build build
12673
```
12774

128-
Next, we build Remill. This script will create another directory, `remill-build`,
129-
in the current working directory. All remaining dependencies needed
130-
by Remill will be built in the `remill-build` directory.
75+
### Windows (requires clang or clang-cl)
13176

132-
```shell
133-
./remill/scripts/build.sh
134-
```
77+
**Note**: This requires running from a Visual Studio developer prompt.
13578

136-
Next, we can install Remill. Remill itself is a library, and so there is no real way
137-
to try it. However, you can head on over to the [McSema](https://github.com/lifting-bits/mcsema) repository, which uses Remill for lifting instructions.
79+
```bash
80+
# Step 1: Build dependencies
81+
cmake -G Ninja -S dependencies -B dependencies/build -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
82+
cmake --build dependencies/build
13883

139-
```shell
140-
cd ./remill-build
141-
sudo make install
84+
# Step 2: Build remill
85+
cmake -G Ninja -B build -DCMAKE_PREFIX_PATH=%CD%/dependencies/install -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Release
86+
cmake --build build
14287
```
14388

144-
We can also build and run Remill's test suite.
89+
### macOS with Homebrew LLVM:
14590

146-
```shell
147-
cd ./remill-build
148-
make test_dependencies
149-
make test
150-
```
91+
```bash
92+
# Install LLVM via Homebrew
93+
brew install llvm@17
94+
LLVM_PREFIX=$(brew --prefix llvm@17)
15195

152-
### Full Source Builds
96+
# Build dependencies with external LLVM
97+
cmake -G Ninja -S dependencies -B dependencies/build -DUSE_EXTERNAL_LLVM=ON "-DCMAKE_PREFIX_PATH=$LLVM_PREFIX"
98+
cmake --build dependencies/build
15399

154-
Sometimes, you want to build everything from source, including the [cxx-common](https://github.com/lifting-bits/cxx-common) libraries remill depends on. To build against a custom cxx-common location, you can use the following `cmake` invocation:
155-
156-
```sh
157-
mkdir build
158-
cd build
159-
cmake \
160-
-DCMAKE_INSTALL_PREFIX="<path where remill will install>" \
161-
-DCMAKE_TOOLCHAIN_FILE="<path to cxx-common directory>/vcpkg/scripts/buildsystems/vcpkg.cmake" \
162-
-G Ninja \
163-
..
164-
cmake --build .
165-
cmake --build . --target install
100+
# Build remill
101+
cmake -G Ninja -B build "-DCMAKE_PREFIX_PATH=$LLVM_PREFIX;$(pwd)/dependencies/install" -DCMAKE_BUILD_TYPE=Release
102+
cmake --build build
166103
```
167104

168-
The output may produce some CMake warnings about policy CMP0003. These warnings are safe to ignore.
169-
170-
### Common Build Issues
105+
### Linux with system LLVM:
171106

172-
If you see errors similar to the following:
107+
```bash
108+
# Build dependencies with external LLVM
109+
cmake -G Ninja -S dependencies -B dependencies/build -DUSE_EXTERNAL_LLVM=ON
110+
cmake --build dependencies/build
173111

112+
# Build remill
113+
cmake -G Ninja -B build "-DCMAKE_PREFIX_PATH=$LLVM_PREFIX;$(pwd)/dependencies/install" -DCMAKE_BUILD_TYPE=Release
114+
cmake --build build
174115
```
175-
fatal error: 'bits/c++config.h' file not found
176-
```
177-
178-
Then you need to install 32-bit libstdc++ headers and libraries. On a Debian/Ubuntu based distribution, You would want to do something like this:
179-
180-
```sh
181-
sudo dpkg --add-architecture i386
182-
sudo apt-get update
183-
sudo apt-get install libc6-dev:i386 libstdc++-10-dev:i386 g++-multilib
184-
```
185-
186-
This error happens because the SPARC32 runtime semantics (the bitcode library which lives in `<install directory>/share/remill/<version>/semantics/sparc32.bc`) are built as 32-bit code, but 32-bit development libraries are not installed by default.
187-
188-
A similar situation occurs when building remill on arm64 Linux. In that case, you want to follow a similar workflow, except the architecture used in `dpkg` and `apt-get` commands would be `armhf` instead of `i386`.
189-
190-
Another alternative is to disable SPARC32 runtime semantics. To do that, use the `-DREMILL_BUILD_SPARC32_RUNTIME=False` option when invoking `cmake`.

‎docs/DEPENDENCIES.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Remill Dependency Management
2+
3+
## Overview
4+
5+
Remill uses a CMake superbuild pattern for dependency management instead of traditional package managers like vcpkg or Conan. The superbuild system is located in the `dependencies/` directory.
6+
7+
## Why Superbuild?
8+
9+
The superbuild approach was chosen for several key reasons:
10+
11+
1. **Simplicity**: Automating dependency compilation is easier for users
12+
2. **Reproducibility**: Pinned dependency versions ensure consistent builds across all environments
13+
3. **Cross-Platform Consistency**: Same build process works on Linux, macOS, and Windows
14+
15+
## How It Works
16+
17+
The superbuild uses CMake's `ExternalProject` module to:
18+
19+
1. Download dependencies from source
20+
2. Build them in the correct order (respecting inter-dependencies)
21+
3. Install everything to a common prefix: `dependencies/install/` as proper CMake packages
22+
4. The main project then uses this prefix via `CMAKE_PREFIX_PATH`
23+
24+
## Configuration Options
25+
26+
### Using External LLVM
27+
28+
The superbuild can use an externally-provided LLVM instead of building its own:
29+
30+
```bash
31+
cmake -S dependencies -B dependencies/build -DUSE_EXTERNAL_LLVM=ON
32+
```
33+
34+
This is particularly useful for:
35+
- macOS users with Homebrew LLVM
36+
- Linux distributions with packaged LLVM
37+
- CI/CD systems with pre-installed LLVM
38+
39+
### Customizing Versions
40+
41+
To modify dependency versions, edit the corresponding `.cmake` file in `dependencies/`:
42+
- `dependencies/llvm.cmake` - LLVM version and configuration
43+
- `dependencies/xed.cmake` - Intel XED configuration
44+
- Individual `simple_git()` calls for Google libraries

0 commit comments

Comments
 (0)