From 1983369b8e9066888dd15d4fab4f7d4b246a6486 Mon Sep 17 00:00:00 2001
From: Samuel Aubertin <samuel.aubertin@gmail.com>
Date: Wed, 13 Apr 2022 17:49:04 +0200
Subject: [PATCH] More compilation documentation

---
 README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 50 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 6dda44b..4e42829 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ It measures and uploads the success rate of the Spectre attacks on your CPU usin
 - Optimisation levels (```-O```).
 - Static/dynamic linking.
 
-and mitigations:
+... and mitigations:
 
 - [Masking](https://github.com/torvalds/linux/blob/cb6416592bc2a8b731dabcec0d63cda270764fc6/arch/x86/include/asm/barrier.h#L27) and [lfence](https://www.intel.com/content/www/us/en/developer/articles/troubleshooting/using-intel-compilers-to-mitigate-speculative-execution-side-channel-issues.html) against Spectre V1.
 - [RETPOLINE](https://support.google.com/faqs/answer/7625886) against Spectre V2.
@@ -28,11 +28,46 @@ and mitigations:
 
 ## Supported distributions
 
-- _Alpine 3.15_
-- _RHEL 8_
-- _Fedora 35_
-- _Ubuntu 20.04_
 - _OpenBSD 7.0_ 
+- _Alpine 3.15_
+- _Fedora 35_
+- _RHEL 8_
+- _Ubuntu 20.04_
+
+## Source support 
+
+Experiment is the most complete when compiled from source:
+
+### OpenBSD
+
+```
+$ doas pkg_add git gmake clang gcc
+$ git clone https://gitlab.eurecom.fr/aubertin/octopus.git
+$ gmake -C octopus all
+```
+
+### Alpine
+
+```
+$ apk add make git openssh-client-default util-linux-misc util-linux-dev gcc clang musl-dev lld coreutils
+$ git clone https://gitlab.eurecom.fr/aubertin/octopus.git
+$ make -C octopus all
+```
+
+### Fedora/RHEL
+
+```
+$ sudo yum install -y git make clang gcc glibc-static lld uuid
+$ git clone https://gitlab.eurecom.fr/aubertin/octopus.git
+$ make -C octopus all
+```
+
+### Debian/Ubuntu
+```
+$ sudo apt install -y git make gcc clang lld uuid
+$ git clone https://gitlab.eurecom.fr/aubertin/octopus.git
+$ make -C octopus all
+```
 
 ## Docker support 
 
@@ -45,14 +80,16 @@ You **have** to build the image on the actual CPU you want to test, otherwise yo
 The code runs on _WSL2_ using the default distribution (Ubuntu).
 
 To install WSL, from a priviledged PowerShell prompt:
-```PS C:\Users\user> wsl --install```.
+
+```
+PS C:\Users\user> wsl --install
+```
 
 Once the installation is complete, you can install the dependencies and run the experiment from the WSL console:
 ```
-$ sudo apt update && sudo apt upgrade -y && sudo apt install git make gcc clang lld
-$ git clone https://gitlab.eurecom.fr/aubertin/octopus.github
-$ cd octopus 
-$ make all
+$ sudo apt update && sudo apt upgrade -y && sudo apt install -y git make gcc clang lld uuid
+$ git clone https://gitlab.eurecom.fr/aubertin/octopus.git
+$ make -C octopus all
 ```
 
 ## Results
@@ -66,7 +103,7 @@ Results are stored as JSON objects in an unique file for each run, following thi
 - For upload: ```openssh``` and ```uuid```
 - The C library static symbols, on Fedora: ```glibc-static```
 
-## Running the experiment
+## Running the experiment with `Make`
 
 ```make``` will build, execute and upload the experiment results.
 
@@ -105,8 +142,9 @@ Here is an exhaustive list of the data sent:
 - Kernel version and compilation date.
 - GCC and clang versions.
 - The list of mitigations enabled at runtime.
-- The cache timings of the processor computed by the ```calibrate_threshold()``` function.
+- The cache timings of the processor computed by the ```calibrate_threshold()``` function and the experiment duration.
 - Each spectre execution success rate.
+- The code version.
 
 **NONE** of this data will be used for anyhting else except this experiment.