Create ideal_integration.md

1 files changed, 55 insertions, 0 deletions

diff --git a/docs/ideal_integration.md b/docs/ideal_integration.md
new file mode 100644
index 00000000..b244c8ef
--- /dev/null
+++ b/docs/ideal_integration.md
@@ -0,0 +1,55 @@
+# Ideal integration with OSS-Fuzz 
+OSS projects have different build and test systems and so we can not expect them
+to have a unified way of implementing and maintaining fuzz targets and integrating
+them with OSS-Fuzz. However we will still try to give recommendations on the preferred ways. 
+
+## Fuzz Target
+The code of the [fuzz target(s)](http://libfuzzer.info/#fuzz-target) should be part of the project's source code repository. 
+All fuzz targets should be easily discoverable (e.g. reside in the same directory, or follow the same naming pattern, etc). 
+
+Examples: 
+[boringssl](https://github.com/google/boringssl/tree/master/fuzz),
+[SQLite](https://www.sqlite.org/src/artifact/ad79e867fb504338),
+[s2n](https://github.com/awslabs/s2n/tree/master/tests/fuzz),
+[openssl](https://github.com/openssl/openssl/tree/master/fuzz),
+[FreeType](http://git.savannah.gnu.org/cgit/freetype/freetype2.git/tree/src/tools/ftfuzzer),
+[re2](https://github.com/google/re2/tree/master/re2/fuzzing)
+[harfbuzz](https://github.com/behdad/harfbuzz/tree/master/test/fuzzing),
+[pcre2](http://vcs.pcre.org/pcre2/code/trunk/src/pcre2_fuzzsupport.c?view=markup),
+[ffmpeg](https://github.com/FFmpeg/FFmpeg/blob/master/doc/examples/decoder_targeted.c)
+
+
+## Seed Corpus
+* The seed corpus should be available in revision control (same or different as the source code). 
+The seed corpus should be maintained by the project owners and extended every time a bug found by the fuzz target is fixed. 
+Inputs that trigger important parts of the code are also welcome.
+
+Examples: 
+[boringssl](https://github.com/google/boringssl/tree/master/fuzz),
+[openssl](https://github.com/openssl/openssl/tree/master/fuzz),
+
+
+## Regression Testing
+The fuzz targets should be regularly tested (not necessary fuzzed!) as a part
+of the project's regression testing process.
+One way to do so is to link the fuzz target with a simple driver
+(e.g. [this one](https://github.com/llvm-mirror/llvm/tree/master/lib/Fuzzer/standalone))
+that runs the provided inputs and use this driver with the seed corpus. 
+If possible, use the [sanitizers](https://github.com/google/sanitizers) during regression testing.
+
+Examples: [SQLite](https://www.sqlite.org/src/artifact/d9f1a6f43e7bab45)
+
+## Build support
+A plethora of different build systems exist in the open-source world.
+And the less OSS-Fuzz knows about them the better it can scale. 
+
+An ideal build integration for OSS-Fuzz would look like this:
+* For every fuzz target in the project there is a build rule that builds `foo_fuzzer.a`,
+an archive that contains the fuzzing entry point (`LLVMFuzzerTestOneInput`)
+and all the code it depends on, but not the `main()` function
+* The build system supports changing the compiler and passing extra compiler
+flags so that the build command for a `foo_fuzzer.a` looks like this: 
+`CC="clang $FUZZER_FLAGS" CXX="clang++ $FUZZER_FLAGS" make_or_whatever_other_command foo_fuzzer.a`.
+
+In this case linking the target with e.g. libFuzzer will look like "clang++ foo_fuzzer.a libFuzzer.a".
+This will allow to have minimal OSS-Fuzz-specific configuration and thus be more robust.