Sanitizer Builds Of PDFWriter

PDFWriter supports compile-time integration with Clang sanitizers (AddressSanitizer, UndefinedBehaviorSanitizer, ThreadSanitizer, MemorySanitizer) through the PDFHUMMUS_SANITIZER CMake option. The flags are applied globally so that bundled dependencies (zlib, freetype, libpng, libjpeg, libtiff, libaesgm) are also instrumented.

This is an opt-in build for occasional auditing and bug-hunting. It is not part of CI.

Build Prerequisites

• Clang compiler (sanitizers are a Clang/LLVM feature; GCC's coverage is partial).
• A build directory.

Building with AddressSanitizer + UndefinedBehaviorSanitizer

The recommended combination for general audit work:

mkdir build
cd build
cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
  -DPDFHUMMUS_SANITIZER=address,undefined ..
cmake --build . -- -j$(nproc)

address catches heap/stack overflow, use-after-free, and double-free. undefined catches signed-integer overflow, null deref, alignment issues, and other C/C++ undefined behavior. Both run together with modest overhead.

Running the Test Suite Under Sanitizers

ctest --output-on-failure

Any sanitizer hit aborts the offending test and prints a stack trace. ASan and UBSan default to fail-fast — the first error in a test stops that test process.

Other Sanitizers

ThreadSanitizer (data race detection):

cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
  -DPDFHUMMUS_SANITIZER=thread ..

MemorySanitizer (uninitialized reads):

cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
  -DPDFHUMMUS_SANITIZER=memory ..

Note: MemorySanitizer requires every linked library (including the C++ standard library) to be MSan-instrumented to avoid false positives. Without an MSan-instrumented libc++, the noise typically drowns real findings. Build instrumented libc++ separately if you need MSan signal.

Notes

• Sanitizers cannot be combined freely — ASan, MSan, and TSan are mutually exclusive. UBSan composes with each of them.
• The build is slower and the binaries are larger; do not use sanitizer builds for benchmarking.
• -fno-omit-frame-pointer -g is always included with PDFHUMMUS_SANITIZER to ensure usable stack traces.
• The same option can be combined with BUILD_FUZZING_HARNESS=ON. The harness already enables -fsanitize=fuzzer,address; the runtime unions both sanitizer sets.