From ae476f922cbf6d58a162728b7f4494d355655395 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=A9a=20Saviot?= <lea.saviot@numworks.com>
Date: Thu, 15 Nov 2018 15:46:48 +0100
Subject: [PATCH] [ion] Fix and comment the UI comparison tool

---
 build/targets.blackbox.mak   | 14 ++++++++++++--
 ion/src/blackbox/compare.cpp | 22 +++++++++++++++++-----
 2 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/build/targets.blackbox.mak b/build/targets.blackbox.mak
index 1ba0af179..858a22887 100644
--- a/build/targets.blackbox.mak
+++ b/build/targets.blackbox.mak
@@ -14,9 +14,9 @@ libepsilon_%.o: $(libepsilon_objs) $(app_objs) $(app_image_objs) ion/src/blackbo
 	@echo "LD      $@"
 	$(Q) $(LD) $^ $(LDFLAGS) -r -s -o $@
 
-compare: ion/src/blackbox/compare.o libepsilon_first.o libepsilon_second.o
+compare: ion/src/blackbox/compare.o
 	@echo "LD      $@"
-	$(Q) $(LD) $^ $(LDFLAGS) -L. -o $@
+	$(Q) $(LD) $^ libepsilon_first.o libepsilon_second.o $(LDFLAGS) -L. -o $@
 
 # Integration tests
 
@@ -48,3 +48,13 @@ else
 epsilon_fuzz:
 	@echo "Fuzzing requires TOOLCHAIN=afl"
 endif
+
+.PHONY: compare_fuzz
+ifeq ($(TOOLCHAIN),afl)
+compare_fuzz: compare
+	@echo "FUZZ    $<"
+	@afl-fuzz -t 3000 -i tests -o afl ./compare
+else
+compare_fuzz:
+	@echo "Fuzzing requires TOOLCHAIN=afl"
+endif
diff --git a/ion/src/blackbox/compare.cpp b/ion/src/blackbox/compare.cpp
index 308ac946b..791ccfd2a 100644
--- a/ion/src/blackbox/compare.cpp
+++ b/ion/src/blackbox/compare.cpp
@@ -1,10 +1,21 @@
 /* Compare two Epsilon versions
  *
- * git checkout first_hash
- * make -j8 PLATFORM=blackbox clean libepsilon_first.dylib
- * git checkout second_hash
- * make -j8 PLATFORM=blackbox clean libepsilon_second.dylib
- * make PLATFORM=blackbox compare
+ * This tool compares the frames step-by-step of scenarios played on two
+ * different epsilon versions, and shows the first frame where pixels differ
+ * between the versions.
+ *
+ * To use it, first create the two epsilon versions to compare, in a library
+ * format:
+ *      git checkout first_hash
+ *      make -j8 PLATFORM=blackbox clean libepsilon_first.o
+ *      git checkout second_hash
+ *      make -j8 PLATFORM=blackbox clean libepsilon_second.o
+ *
+ * To compare the versions on a given scenario:
+ *      make -j8 PLATFORM=blackbox compare
+ *      ./compare path/to/scenario
+ * To fuzz over scenarios that are in a folder named "tests":
+ *      make -j8 PLATFORM=blackbox TOOLCHAIN=afl compare_fuzz
  */
 
 #undef EPSILON_LIB_PREFIX
@@ -49,4 +60,5 @@ int main(int argc, char * argv[]) {
 
   first.join();
   second.join();
+  exit(0);
 }