Commit 6bda921da0f996fc389caac77950d39cd05c855e
2015-11-02T06:53:48
[ftfuzzer] Update README file.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
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/*