[freetype2] master 6bda921 3/3: [ftfuzzer] Update README file.

[Werner LEMBERG]

branch: master
commit 6bda921da0f996fc389caac77950d39cd05c855e
Author: Werner Lemberg <address@hidden>
Commit: Werner Lemberg <address@hidden>

    [ftfuzzer] Update README file.
---
 src/tools/ftfuzzer/README |   67 +++++++++++++++++++++++++++++++++++----------
 1 files changed, 52 insertions(+), 15 deletions(-)

diff --git a/src/tools/ftfuzzer/README b/src/tools/ftfuzzer/README
index 7248bb7..f827d5e 100644
--- a/src/tools/ftfuzzer/README
+++ b/src/tools/ftfuzzer/README
@@ -1,23 +1,60 @@
 ftfuzzer
---------
+========
 
-ftfuzzer.cc contains a target function for FreeType fuzzing.
-It can be used with libFuzzer (http://llvm.org/docs/LibFuzzer.html)
-or potentially any other similar fuzzer.
+
+ftfuzzer.cc
+-----------
+
+This file contains a target function for FreeType fuzzing.  It can be used
+with libFuzzer (http://llvm.org/docs/LibFuzzer.html) or potentially any
+other similar fuzzer.
 
 Usage:
-  1. Build libfreetype.a and ftfuzzer.cc using the most recent clang compiler
-     with these flags:
-     -fsanitize-coverage=edge,8bit-counters # for fuzzer coverage feedback
-     -fsanitize=address,signed-integer-overflow,shift  # for bug checking
-  2. Link with libFuzzer (it contains main()).
+
+  1. Build `libfreetype.a' and `ftfuzzer.cc' using the most recent clang
+     compiler with these flags:
+
+       -fsanitize-coverage=edge,8bit-counters # for fuzzer coverage feedback
+       -fsanitize=address,signed-integer-overflow,shift  # for bug checking
+
+     You also need the header files from `libarchive' for handling tar files
+     (see `ftmutator.cc' below for more).
+
+  2. Link with `libFuzzer' (it contains main()) and `libarchive'.
+
   3. Run the fuzzer on some test corpus.
 
 The exact flags and commands may vary.
-There is a continuous fuzzing bot that runs ftfuzzer:
-https://github.com/google/libfuzzer-bot/tree/master/freetype.
-Check the bot confituration for the most current settings.
 
-runinput.cc contains a convenience main() function to run the target function
-on a set of input files. Link it with ftfuzzer.cc and libfreetype.a
-and run like "./a.out my_tests_inputs/*"
+
+There is a continuous fuzzing bot that runs ftfuzzer.
+
+  https://github.com/google/libfuzzer-bot/tree/master/freetype
+
+Check the bot configuration for the most current settings.
+
+
+ftmutator.cc
+------------
+
+FreeType has the ability to `attach' auxiliary files to a font file,
+providing additional information.  The main usage is to load AFM files for
+PostScript Type 1 fonts.
+
+However, libFuzzer currently only supports mutation of a single input file. 
+For this reason, `ftmutator.cc' contains a custom fuzzer mutator that uses
+an uncompressed tar file archive as the input.  The first file in such a
+tarball gets opened by FreeType as a font, all other files are treated as
+input for `FT_Attach_Stream'.
+
+Compilation is similar to `ftfuzzer.c'.
+
+
+runinput.cc
+-----------
+
+To run the target function on a set of input files, this file contains a
+convenience main() function.  Link it with `ftfuzzer.cc', `libfreetype.a',
+and `libarchive' and run like
+
+  ./a.out my_tests_inputs/*