-rw-r--r-- 2992 saferewrite-20250228/README raw
0. The instructions below have been tested on an AMD EPYC 7742 server
running Debian 12. Maybe the instructions also work under Ubuntu and
other Debian-derived systems.

The instructions assume that you are running saferewrite on amd64
(64-bit AMD/Intel). The code being tested is also automatically
cross-compiled for various other architectures. However, some 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.


1. First time, as root, install system packages:

   dpkg --add-architecture arm64
   dpkg --add-architecture armel
   dpkg --add-architecture i386
   dpkg --add-architecture mips64el
   apt update
   apt install \
     python3 python3-dev python3-venv \
     build-essential clang valgrind \
     binutils-aarch64-linux-gnu crossbuild-essential-arm64 \
       libc6:arm64 libstdc++6:arm64 \
     binutils-arm-linux-gnueabi crossbuild-essential-armel \
       libc6:armel libstdc++6:armel \
     binutils-i686-linux-gnu crossbuild-essential-i386 \
       libc6:i386 libstdc++6:i386 \
     binutils-mips64el-linux-gnuabi64 crossbuild-essential-mips64el \
       libc6:mips64el libstdc++6:mips64el \
     binfmt-support qemu-user qemu-user-static

All subsequent steps are unprivileged.


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

   VENV=saferewrite
   mkdir -p $HOME/.virtualenvs
   python3 -m venv $HOME/.virtualenvs/$VENV
   export PATH=$HOME/.virtualenvs/$VENV/bin:$PATH
   for cross in aarch64-linux-gnu arm-linux-gnueabi i686-linux-gnu mips64el-linux-gnuabi64
   do
     ln -s /usr/bin/clang $HOME/.virtualenvs/$VENV/bin/${cross}-clang
     ln -s /usr/bin/clang++ $HOME/.virtualenvs/$VENV/bin/${cross}-clang++
   done


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

   pip install angr==9.2.102 setproctitle


4. Optionally: First time, as user, install elfulator as explained in
README-elfulator. Right now this matters only for testing SPARC code.


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

   VENV=saferewrite
   export PATH=$HOME/.virtualenvs/$VENV/bin:$PATH


6. 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*

See README-resources for notes on resource consumption.


7. 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 THREADS=1 ./analyze &

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


8. Look at the analysis results:

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

See README-analysis for notes on how to interpret the results.