-rw-r--r-- 3214 saferewrite-20240807/README raw
0. These instructions assume Debian or Ubuntu.

Most of the examples of optimized code are for AVX2 (Haswell and newer)
and won't run on other platforms. saferewrite automatically skips the
implementations that don't run and analyzes the implementations that do.

Some of the current analyses use 100GB of RAM, although most use less.
Also, saferewrite will automatically run multiple analyses in parallel
if many cores are available, and has been observed using 1TB of RAM
overall. These instructions include mechanisms to select particular
analyses and to limit parallelism, but it is good to use a modern server
with a reasonable amount of RAM.


1. First time, as root, install packages:

   apt install python3 virtualenvwrapper build-essential clang valgrind

Or, if you'd like to cross-compile for 64-bit ARM CPUs:

   dpkg --add-architecture arm64
   apt update
   apt install \
     python3 virtualenvwrapper build-essential clang \
     binfmt-support qemu-user qemu-user-static \
     binutils-aarch64-linux-gnu crossbuild-essential-arm64 \
     libc6:arm64 valgrind:arm64

Or, if you'd like to cross-compile for 32-bit ARM CPUs:

   dpkg --add-architecture armel
   apt update
   apt install \
     python3 virtualenvwrapper build-essential clang \
     binfmt-support qemu-user qemu-user-static \
     binutils-arm-linux-gnueabi crossbuild-essential-armel \
     libc6:armel

All subsequent steps are unprivileged.


2. First time, as user, create a saferewrite environment:

   mkvirtualenv -p /usr/bin/python3 saferewrite

If this doesn't work, try running

   . /usr/share/virtualenvwrapper/virtualenvwrapper.sh

first, or try a new shell.

If your system has pypy3 then you can use that instead of python3 here,
and run "pypy3 ./analyze &" below. This can save a considerable fraction
of unrolling time but doesn't help for Z3 time, which is typically a
bigger bottleneck.


3. First time, as user, install angr within the saferewrite environment:

   pip install angr


4. Subsequent times, as user, switch to the saferewrite environment:

   workon saferewrite

If this doesn't work, try running

   . /usr/share/virtualenvwrapper/virtualenvwrapper.sh

first, or try a new shell, as in step 3.


5. Optionally, in this directory, narrow the analysis to cmp* (or
whichever subdirectories you're interested in under src):

   chmod +t src/*
   chmod -t src/cmp*


6. In this directory, analyze everything:

   ./analyze &

This will put results in a ./build directory, wiping out any previous
./build results.

The analysis automatically runs on as many cores as it can find. If you
want to limit the number of cores:

   env CORES=1 ./analyze &

If you want to interrupt the analysis, use SIGTERM (i.e., the "kill"
command with default options) rather than SIGINT (^C).

If you want to cross-compile for 64-bit ARM:

   env TARGET=arm64 ./analyze &

If you want to cross-compile for 32-bit ARM:

   env TARGET=arm32 ./analyze &


7. Look at the analysis results:

   ls -1 build/*/*/*/analysis/*

To see examples showing implementations are different:

   less build/*/*/*/analysis/*different*

To see what the analysis thinks each implementation is doing:

   less build/*/*/*/analysis/unrolled