[docs] Add "Integrating a Go project" documentation page (#2714). (#2837)

* [docs] Add "Integrating a Go project" documentation page (#2714).

* rephrase go-fuzz mode description

2 files changed, 101 insertions, 15 deletions

diff --git a/docs/getting-started/new-project-guide/go_lang.md b/docs/getting-started/new-project-guide/go_lang.md
new file mode 100644
index 00000000..800485ca
--- /dev/null
+++ b/docs/getting-started/new-project-guide/go_lang.md
@@ -0,0 +1,82 @@
+---
+layout: default
+title: Integrating a Go project
+parent: Setting up a new project
+grand_parent: Getting started
+nav_order: 1
+permalink: /getting-started/new-project-guide/go-lang/
+---
+
+# Integrating a Go project
+{: .no_toc}
+
+- TOC
+{:toc}
+---
+
+The process of integrating a project written in Go with OSS-Fuzz is very similar
+to the general
+[Setting up a new project]({{ site.baseurl }}/getting-started/new-project-guide/)
+process. The key specifics of integrating a Go project are outlined below.
+
+## Go-fuzz support
+
+OSS-Fuzz supports **go-fuzz** in the
+[libFuzzer compatible mode](https://github.com/dvyukov/go-fuzz#libfuzzer-support)
+only. In that mode, fuzz targets for Go use the libFuzzer engine with native Go
+coverage instrumentation. Binaries compiled in this mode provide the same
+libFuzzer command line interface as non-Go fuzz targets.
+
+## Project files
+
+The structure of the project directory in OSS-Fuzz repository doesn't differ for
+projects written in Go. The project files have the following Go specific aspects.
+
+### project.yaml
+
+For projects written in Go, we use only `libfuzzer` fuzzing engine and `address`
+sanitizer.
+[Example](https://github.com/google/oss-fuzz/blob/356f2b947670b7eb33a1f535c71bc5c87a60b0d1/projects/syzkaller/project.yaml#L7):
+
+```yaml
+fuzzing_engines:
+  - libfuzzer
+sanitizers:
+  - address
+```
+
+### Dockerfile
+
+The OSS-Fuzz builder image has the latest stable release of Golang installed. In
+order to install dependencies of your project, add `RUN go get ...` command to
+your Dockerfile.
+[Example](https://github.com/google/oss-fuzz/blob/356f2b947670b7eb33a1f535c71bc5c87a60b0d1/projects/syzkaller/Dockerfile#L23):
+
+```dockerfile
+# Dependency for one of the fuzz targets.
+RUN go get github.com/ianlancetaylor/demangle
+```
+
+### build.sh
+
+In order to build a Go fuzz target, you need to call `go-fuzz-build -libfuzzer`
+command first, and then link the resulting `.a` file against
+`$LIB_FUZZING_ENGINE` using the `$CXX $CXXFLAGS ...` command.
+[Example](https://github.com/google/oss-fuzz/blob/356f2b947670b7eb33a1f535c71bc5c87a60b0d1/projects/syzkaller/build.sh#L19):
+
+```sh
+function compile_fuzzer {
+  path=$1
+  function=$2
+  fuzzer=$3
+
+   # Instrument all Go files relevant to this fuzzer
+  go-fuzz-build -libfuzzer -func $function -o $fuzzer.a $path 
+
+   # Instrumented, compiled Go ($fuzzer.a) + fuzzing engine = fuzzer binary
+  $CXX $CXXFLAGS $LIB_FUZZING_ENGINE $fuzzer.a -lpthread -o $OUT/$fuzzer
+}
+
+compile_fuzzer ./pkg/compiler Fuzz compiler_fuzzer
+compile_fuzzer ./prog/test FuzzDeserialize prog_deserialize_fuzzer
+```
diff --git a/docs/getting-started/new_project_guide.md b/docs/getting-started/new_project_guide.md
index 317025ad..8018c605 100644
--- a/docs/getting-started/new_project_guide.md
+++ b/docs/getting-started/new_project_guide.md
@@ -2,6 +2,7 @@
 layout: default
 title: Setting up a new project
 parent: Getting started
+has_children: true
 nav_order: 2
 permalink: /getting-started/new-project-guide/
 ---
@@ -21,15 +22,11 @@ Before you can start setting up your new project for fuzzing, you must do the fo
   with the project you want to fuzz.
 
   For examples, see
-[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), and
-[ffmpeg](https://github.com/FFmpeg/FFmpeg/blob/master/tools/target_dec_fuzzer.c).
+[boringssl](https://github.com/google/boringssl/tree/master/fuzz) or
+[SQLite](https://www.sqlite.org/src/artifact/ad79e867fb504338) (C/C++),
+[go-fuzz](https://github.com/dvyukov/go-fuzz-corpus/tree/86a5af9d6842f80b205a082538ea28f61bbb8ccb) or
+[syzkaller](https://github.com/google/syzkaller/tree/7c7ded697e6322b0975f061b7e268fe44f585dab/prog/test)
+(Go).
 
 - [Install Docker](https://docs.docker.com/engine/installation)
   (Googlers can visit [go/installdocker](https://goto.google.com/installdocker)).
@@ -164,16 +161,20 @@ reproducing and fixing bugs than the standard one outlined in the reproducing gu
 This configuration file defines the Docker image for your project. Your [build.sh](#build.sh) script will be executed in inside the container you define.
 For most projects, the image is simple:
 ```docker
-FROM gcr.io/oss-fuzz-base/base-builder    # base image with clang toolchain
-MAINTAINER YOUR_EMAIL                     # maintainer for this file
+FROM gcr.io/oss-fuzz-base/base-builder       # base image with clang toolchain
+MAINTAINER YOUR_EMAIL                        # maintainer for this file
 RUN apt-get update && apt-get install -y ... # install required packages to build your project
-RUN git clone <git_url> <checkout_dir>    # checkout all sources needed to build your project
-WORKDIR <checkout_dir>                    # current directory for build script
-COPY build.sh fuzzer.cc $SRC/             # copy build script and other fuzzer files in src dir
+RUN go get ...                               # install dependencies to build your Go project
+RUN git clone <git_url> <checkout_dir>       # checkout all sources needed to build your project
+WORKDIR <checkout_dir>                       # current directory for the build script
+COPY build.sh fuzzer.cc $SRC/                # copy build script and other fuzzer files in src dir
 ```
 In the above example, the git clone will check out the source to `$SRC/<checkout_dir>`.
 
-For an example in Expat, see [expat/Dockerfile](https://github.com/google/oss-fuzz/tree/master/projects/expat/Dockerfile) 
+For an example, see
+[expat/Dockerfile](https://github.com/google/oss-fuzz/tree/master/projects/expat/Dockerfile)
+or
+[syzkaller/Dockerfile](https://github.com/google/oss-fuzz/blob/master/projects/syzkaller/Dockerfile).
 
 ## build.sh
 
@@ -206,6 +207,9 @@ $CXX $CXXFLAGS -std=c++11 -Ilib/ \
 
 cp $SRC/*.dict $SRC/*.options $OUT/
 ```
+
+If your project is written in Go, check out the [Integrating a Go project]({{ site.baseurl }}//getting-started/new-project-guide/go-lang/) page.
+
 **Notes:**
 
 1. Don't assume the fuzzing engine is libFuzzer by default, because we generate builds for both libFuzzer and AFL fuzzing engine configurations. Instead, link the fuzzing engine using $LIB_FUZZING_ENGINE.