1# base-builder
2> Abstract base image for project builders.
3
4Every project image supports multiple commands that can be invoked through docker after the image is built:
5
6<pre>
7docker run --rm -ti gcr.io/oss-fuzz/<b><i>$project</i></b> <i>&lt;command&gt;</i> <i>&lt;arguments...&gt;</i>
8</pre>
9
10# Supported Commands
11
12| Command | Description |
13|---------|-------------|
14| `compile` (default) | build all fuzz targets
15| `/bin/bash` | drop into shell, execute `compile` script to start build.
16
17# Build Configuration
18
19A single build image can build same set of fuzzers in many configurations.
20The configuration is picked through one or more environment variables.
21
22| Env Variable     | Description
23| -------------    | --------
24| `$SANITIZER ("address")` | Specifies predefined sanitizer configuration to use. `address` or `memory` or `undefined`.
25| `$SANITIZER_FLAGS` | Specify compiler sanitizer flags directly. Overrides `$SANITIZER`.
26| `$COVERAGE_FLAGS` | Specify compiler flags to use for fuzzer feedback coverage.
27| `$BUILD_UID` | User id to use while building fuzzers.
28
29## Examples
30
31- *building sqlite3 fuzzer with UBSan (`SANITIZER=undefined`):*
32
33
34<pre>
35docker run --rm -ti -e <i>SANITIZER</i>=<i>undefined</i> gcr.io/oss-fuzz/sqlite3
36</pre>
37
38
39# Image Files Layout
40
41| Location|Env| Description |
42|---------| -------- | ----------  |
43| `/out/` | `$OUT`         | Directory to store build artifacts (fuzz targets, dictionaries, options files, seed corpus archives). |
44| `/src/` | `$SRC`         | Directory to checkout source files |
45| `/work/`| `$WORK`        | Directory for storing intermediate files |
46| `/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.
47
48While files layout is fixed within a container, the environment variables are
49provided to be able to write retargetable scripts.
50
51
52## Compiler Flags
53
54You *must* use special compiler flags to build your project and fuzz targets.
55These flags are provided in following environment variables:
56
57| Env Variable    | Description
58| -------------   | --------
59| `$CC`           | The C compiler binary.
60| `$CXX`, `$CCC`  | The C++ compiler binary.
61| `$CFLAGS`       | C compiler flags.
62| `$CXXFLAGS`     | C++ compiler flags.
63
64Most well-crafted build scripts will automatically use these variables. If not,
65pass them manually to the build tool.
66
67
68# Child Image Interface
69
70## Sources
71
72Child image has to checkout all sources that it needs to compile fuzz targets into
73`$SRC` directory. When the image is executed, a directory could be mounted on top
74of these with local checkouts using
75`docker run -v $HOME/my_project:/src/my_project ...`.
76
77## Other Required Files
78
79Following files have to be added by child images:
80
81| File Location   | Description |
82| -------------   | ----------- |
83| `$SRC/build.sh` | build script to build the project and its fuzz targets |
84