Building the S2E platform manually

The simplest way to build S2E is to use the s2e-env tool. It is the preferred method for development. See Using s2e-env for instructions. However, some build features are not exposed by s2e-env and you will have to run them manually.

Note

S2E builds and runs on Ubuntu 22.04 LTS and Debian 11/12 (64-bit). Earlier versions may still work, but we do not support them anymore.

Building using Docker

You can create a self-contained docker image that lets you analyze any supported binary. The following command builds the demo docker image.

# Checkout S2E sources (using Google Repo)
# S2EDIR must be in your home folder (e.g., /home/user/s2e)
cd $S2EDIR
repo init -u https://github.com/s2e/manifest.git
repo sync

# Create a build directory
mkdir build && cd build

# Build the docker image
make -f $S2EDIR/Makefile.docker demo

You can then run it as follows:

docker run --rm -ti -w $(pwd) -v $HOME:$HOME cyberhaven/s2e-demo /demo/run.sh $(id -u) $(id -g) /demo/CADET_00001

This command starts the s2e-demo container and creates an S2E environment in $(pwd)/s2e-demo. It then downloads a VM image and creates a default S2E configuration suitable for running the specified binary. Once configuration is done, the container starts S2E.

The S2E environment in $(pwd)/s2e-demo is persistent. It is not kept in the container. You may run the container multiple times without losing the previous settings. This is possible by mounting your home folder in the container. The command also takes your current user and group id in order to create the environment folder with the right permissions (docker uses root by default).

You may specify any binary you want and are not restricted to binaries stored inside the container. You just need to mount the folder that contains it using the -v option.

Building S2E manually

In addition to using the s2e-env tool, you can also build S2E manually.

Required packages

You must install a few packages in order to build S2E manually. Instead of giving you a list that will get out-of-date very quickly, we will give you some pointers that should be always up-to-date:

The packages for the build toolchain and S2E dependencies can be found in the S2E docker file.
The packages required to build the guest images can be found here.

Checking out S2E

The S2E source code can be obtained from the S2E git repository using the following commands. Here $S2EDIR is the directory that will hold both the S2E source and build directories.

cd $S2EDIR
repo init -u https://github.com/s2e/manifest.git
repo sync

This will set up the S2E repositories in $S2EDIR.

In order to contribute to S2E (e.g., submit new features or report bugs), please see here.

Building

The S2E Makefile can be run as follows:

mkdir $S2EDIR/build
cd $S2EDIR/build
make -f $S2EDIR/Makefile install

# Go make some coffee, this will take some time (approx. 60 mins on a 4-core machine)

By default, the make command compiles and installs S2E in release mode to $S2EDIR/build/opt. To change this location, set the S2E_PREFIX environment variable when running make.

To compile S2E in debug mode, use make install-debug.

Note that the Makefile automatically uses the maximum number of available processors in order to speed up compilation.

Updating

You can use the same Makefile to recompile S2E either when changing it yourself or when pulling new versions through repo sync. Note that the Makefile will not automatically reconfigure the packages; for deep changes you might need to either start from scratch by issuing make clean or to force the reconfiguration of specific modules by deleting the corresponding files from the stamps subdirectory.

Building the documentation

The S2E documentation is written in reStructuredText format. HTML documentation can be built as follows:

$ sudo apt-get install linkchecker
$ pip install sphinx_rtd_theme
$ cd $S2EDIR/s2e/docs/sphinx
$ ./build.sh

The documentation will be located in $S2EDIR/s2e/docs/sphinx/build/html/index.html.