[ion] Fix and comment the UI comparison tool

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

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);
 }