LibFuzzer Library Builder

Standard OSS-Fuzz practice: build asan and msan separately, run both.

Output layout

The build_harness/ directory must live inside the target library's source root, not in any parent or project-level directory. This keeps the build artifacts co-located with the source they were built from and avoids cross-library confusion.

<lib_root>/               ← the library's own source tree (e.g. target_project/aom/)
├── CMakeLists.txt
├── ...
└── build_harness/        ← always here, never in a parent directory
    ├── build_<name>.sh
    ├── asan/
    │   ├── lib<name>.a          ← instrumented static archive (for harness linking)
    │   ├── lib<name>.so         ← instrumented shared library (for dynamic linking)
    │   ├── cmake_build/         ← (or autoconf_build/, etc.)
    │   └── include/             ← public headers + generated config headers
    └── msan/
        ├── lib<name>.a
        ├── lib<name>.so
        ├── cmake_build/
        └── include/

Why both .a and .so?

• .a — standard for LibFuzzer harnesses: links everything into one binary, no runtime path issues, easiest to distribute.
• .so — needed when the harness or test driver loads the library dynamically (dlopen), or when downstream consumers expect a shared object. Also required by some OSS-Fuzz build scripts that use $LIB_FUZZING_ENGINE with -shared.

Always compile with -fPIC so the same object files satisfy both formats.

Step 1 — Discover the library

Before writing anything, collect:

1. Build system — look for CMakeLists.txt, configure.ac / configure, meson.build, or a plain Makefile. Read references/build_systems.md for the exact commands per build system.

2. OSS-Fuzz reference script — if an oss-fuzz/projects/<libname>/build.sh exists in the workspace, read it first. It encodes the authoritative cmake flags, disabled features, and memory limits for that library.

3. MSan-specific cmake flags — search the library's CMakeLists.txt for options that disable assembly (e.g., DAOM_TARGET_CPU, DENABLE_ASM, DWITH_SIMD). These must be set for MSan builds.

4. Library-specific allocation limits — some libraries cap per-allocation size (e.g., libaom's DAOM_MAX_ALLOCABLE_MEMORY). Check the OSS-Fuzz script or search the source for such defines.

Step 2 — Write the build script

Write <lib_root>/build_harness/build_<libname>.sh (inside the library's own source tree) using the template in scripts/build_template.sh as a starting point. Because the script lives one level below <lib_root>, the template's LIB_SRC="$(dirname "${SCRIPT_DIR}")" already resolves correctly — do not append the library name manually.

Flags that vary by sanitizer

-fPIC is always required — it makes object files position-independent so they can be linked into both .a (static harness) and .so (shared library).

case "${SANITIZER}" in
  asan)
    SAN_FLAGS="-fsanitize=fuzzer-no-link,address -fPIC"
    HARNESS_SAN_FLAGS="-fsanitize=fuzzer,address"
    ;;
  msan)
    # -fsanitize-memory-track-origins: when MSan fires, prints the allocation
    # site of the uninitialized memory — essential for root-cause analysis.
    SAN_FLAGS="-fsanitize=fuzzer-no-link,memory -fsanitize-memory-track-origins -fPIC"
    HARNESS_SAN_FLAGS="-fsanitize=fuzzer,memory -fsanitize-memory-track-origins"
    # MUST disable inline ASM for MSan (see references/build_systems.md)
    ;;
  ubsan)
    SAN_FLAGS="-fsanitize=fuzzer-no-link,undefined -fPIC"
    HARNESS_SAN_FLAGS="-fsanitize=fuzzer,undefined"
    ;;
  none)
    SAN_FLAGS="-fsanitize=fuzzer-no-link -fPIC"
    HARNESS_SAN_FLAGS="-fsanitize=fuzzer"
    ;;
esac

Passing flags per build system

See references/build_systems.md for the exact incantation per build system. The short version:

• CMake: -DCMAKE_C_FLAGS="$SAN_FLAGS" OR library-specific -DSANITIZE=
• Autoconf: CC=clang CFLAGS="$SAN_FLAGS" ./configure ...
• Meson: CC=clang CFLAGS="$SAN_FLAGS" meson setup build/

MSan libc++ caveat

MSan requires that every byte of shadow memory be initialized by all code paths, including the C++ standard library. OSS-Fuzz provides a pre-built MSan-instrumented libc++ at /usr/local/lib/libcxx_msan/. If that path is absent (local environment), add this warning to the script and document that false positives from stdlib calls are expected:

if [ ! -d /usr/local/lib/libcxx_msan ]; then
  echo "WARNING: No MSan-instrumented libc++ found."
  echo "  False positives from stdlib are expected."
  echo "  For clean MSan: use the OSS-Fuzz Docker container."
fi

Step 3 — Run the build

Run from inside the library's source root (where build_harness/ lives):

cd <lib_root>
CC=clang CXX=clang++ bash build_harness/build_<libname>.sh asan
CC=clang CXX=clang++ bash build_harness/build_<libname>.sh msan

If the build fails, common causes:

• Missing cmake option to disable ASM for MSan → add -D<OPTION>=generic or =0
• CMake cache from a previous build interfering → rm -rf cmake_build/ first
• Missing dependency (e.g., yasm, nasm) → install or disable ASM as above

Step 4 — Verify instrumentation

Run these checks for each build — both asan and msan must pass for both .a and .so:

# ── ASan build ────────────────────────────────────────────────────────────────
LIB_A=build_harness/asan/lib<name>.a
LIB_SO=build_harness/asan/lib<name>.so

nm $LIB_A  | grep -c '__sanitizer_cov' || echo "FAIL .a: no SanitizerCoverage"
nm $LIB_A  | grep -c '__asan'           || echo "FAIL .a: no ASan symbols"
nm $LIB_A  | grep 'LLVMFuzzerTestOneInput' && echo "FAIL .a: library contains fuzzer main"

nm $LIB_SO | grep -c '__sanitizer_cov' || echo "FAIL .so: no SanitizerCoverage"
nm $LIB_SO | grep -c '__asan'           || echo "FAIL .so: no ASan symbols"

# ── MSan build ────────────────────────────────────────────────────────────────
LIB_A=build_harness/msan/lib<name>.a
LIB_SO=build_harness/msan/lib<name>.so

nm $LIB_A  | grep -c '__sanitizer_cov' || echo "FAIL .a: no SanitizerCoverage"
nm $LIB_A  | grep -c '__msan'           || echo "FAIL .a: no MSan symbols"
nm $LIB_A  | grep 'LLVMFuzzerTestOneInput' && echo "FAIL .a: library contains fuzzer main"

nm $LIB_SO | grep -c '__sanitizer_cov' || echo "FAIL .so: no SanitizerCoverage"
nm $LIB_SO | grep -c '__msan'           || echo "FAIL .so: no MSan symbols"

All checks must pass before proceeding to harness compilation.

Step 5 — Print the harness compile command

At the end of the build script, always print the exact commands for compiling a harness against both builds using both .a and .so, including the correct include paths:

# ASan harness — static linking (.a)
$CXX -std=c++17 -fsanitize=fuzzer,address \
    -I build_harness/asan/include \
    your_fuzzer.cc build_harness/asan/lib<name>.a -o your_fuzzer_asan

# ASan harness — dynamic linking (.so)
$CXX -std=c++17 -fsanitize=fuzzer,address \
    -I build_harness/asan/include \
    your_fuzzer.cc -L build_harness/asan -l<name> \
    -Wl,-rpath,build_harness/asan -o your_fuzzer_asan_dyn

# MSan harness — static linking (.a)
$CXX -std=c++17 -fsanitize=fuzzer,memory -fsanitize-memory-track-origins \
    -I build_harness/msan/include \
    your_fuzzer.cc build_harness/msan/lib<name>.a -o your_fuzzer_msan

# MSan harness — dynamic linking (.so)
$CXX -std=c++17 -fsanitize=fuzzer,memory -fsanitize-memory-track-origins \
    -I build_harness/msan/include \
    your_fuzzer.cc -L build_harness/msan -l<name> \
    -Wl,-rpath,build_harness/msan -o your_fuzzer_msan_dyn

This makes it easy to hand off to the harness writing step.

Reference files

• scripts/build_template.sh — copy and adapt for each library
• references/build_systems.md — per-build-system flag reference (CMake, autoconf, meson, plain make) with MSan-specific ASM disable patterns