blob: 4e94bb0888c92f094cfefea3b9bf70d41bb8db22 (
plain)
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
81
82
83
|
# base-builder
> Abstract base image for project builders.
Every project image supports multiple commands that can be invoked through docker after the image is built:
<pre>
docker run --rm -ti gcr.io/oss-fuzz/<b><i>$project</i></b> <i><command></i> <i><arguments...></i>
</pre>
# Supported Commands
| Command | Description |
|---------|-------------|
| `compile` (default) | build all fuzz targets
| `/bin/bash` | drop into shell, execute `compile` script to start build.
# Build Configuration
A single build image can build same set of fuzzers in many configurations.
The configuration is picked through one or more environment variables.
| Env Variable | Description
| ------------- | --------
| `$SANITIZER ("address")` | Specifies predefined sanitizer configuration to use. `address` or `memory` or `undefined`.
| `$SANITIZER_FLAGS` | Specify compiler sanitizer flags directly. Overrides `$SANITIZER`.
| `$COVERAGE_FLAGS` | Specify compiler flags to use for fuzzer feedback coverage.
| `$BUILD_UID` | User id to use while building fuzzers.
## Examples
- *building sqlite3 fuzzer with UBSan (`SANITIZER=undefined`):*
<pre>
docker run --rm -ti -e <i>SANITIZER</i>=<i>undefined</i> gcr.io/oss-fuzz/sqlite3
</pre>
# Image Files Layout
| Location|Env| Description |
|---------| -------- | ---------- |
| `/out/` | `$OUT` | Directory to store build artifacts (fuzz targets, dictionaries, options files, seed corpus archives). |
| `/src/` | `$SRC` | Directory to checkout source files |
| `/work/`| `$WORK` | Directory for storing intermediate files |
| `/usr/lib/libFuzzingEngine.a` | `$LIB_FUZZING_ENGINE` | Location of prebuilt fuzzing engine library (e.g. libFuzzer) that needs to be linked with all fuzz targets.
While files layout is fixed within a container, the environment variables are
provided to be able to write retargetable scripts.
## Compiler Flags
You *must* use special compiler flags to build your project and fuzz targets.
These flags are provided in following environment variables:
| Env Variable | Description
| ------------- | --------
| `$CC` | The C compiler binary.
| `$CXX`, `$CCC` | The C++ compiler binary.
| `$CFLAGS` | C compiler flags.
| `$CXXFLAGS` | C++ compiler flags.
Most well-crafted build scripts will automatically use these variables. If not,
pass them manually to the build tool.
# Child Image Interface
## Sources
Child image has to checkout all sources that it needs to compile fuzz targets into
`$SRC` directory. When the image is executed, a directory could be mounted on top
of these with local checkouts using
`docker run -v $HOME/my_project:/src/my_project ...`.
## Other Required Files
Following files have to be added by child images:
| File Location | Description |
| ------------- | ----------- |
| `$SRC/build.sh` | build script to build the project and its fuzz targets |
|
