mirror of https://github.com/google/oss-fuzz.git
84 lines
2.9 KiB
Markdown
84 lines
2.9 KiB
Markdown
# 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 |
|