diff options
author | Max Moroz <mmoroz@chromium.org> | 2019-09-17 07:15:22 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2019-09-17 07:15:22 -0700 |
commit | d1ed6b87a740878117ce804734b92e65313d6b3c (patch) | |
tree | 60370890d81e6dd335a94d317bfaa4d9a27fb084 /docs/getting-started/new-project-guide/go_lang.md | |
parent | 8b911bf10c9249f653747a022c73e923ffbd5b28 (diff) |
[docs] Add "Integrating a Go project" documentation page (#2714). (#2837)
* [docs] Add "Integrating a Go project" documentation page (#2714).
* rephrase go-fuzz mode description
Diffstat (limited to 'docs/getting-started/new-project-guide/go_lang.md')
-rw-r--r-- | docs/getting-started/new-project-guide/go_lang.md | 82 |
1 files changed, 82 insertions, 0 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 +``` |