How to Enable Debugging Flags When Compiling libdav1d

This article provides a practical guide on how to configure and enable debugging flags when compiling the libdav1d AV1 decoder from source. It covers standard Meson build system configurations, compiler sanitizers, and specific library options that assist in troubleshooting, stepping through code, and analyzing memory issues.

Meson Build Types for Debugging

libdav1d uses the Meson build system. To enable basic debugging features, you should configure the build type during the setup phase. Meson provides built-in options to control compiler optimization and debug symbols.

Debug Build (--buildtype=debug): This compiles the library with full debug symbols (-g) and disables compiler optimization (-O0). This is ideal for stepping through code using debuggers like GDB or LLDB.
```
meson setup build --buildtype=debug
```
Debug Optimized Build (--buildtype=debugoptimized): This compiles the library with debug symbols but keeps optimizations enabled (-O2). This is useful for debugging performance-related issues.
```
meson setup build --buildtype=debugoptimized
```

Enabling Sanitizers for Memory Debugging

To catch memory leaks, buffer overflows, and undefined behavior, you can compile libdav1d with compiler sanitizers using Meson’s built-in options.

AddressSanitizer (ASan): Detects memory errors such as out-of-bounds accesses and use-after-free bugs.
```
meson setup build -Db_sanitize=address
```
UndefinedBehaviorSanitizer (UBSan): Detects undefined behavior, such as integer overflows or null pointer dereferences.
```
meson setup build -Db_sanitize=undefined
```
Combined Sanitizers: You can enable multiple sanitizers simultaneously by separating them with a comma.
```
meson setup build -Db_sanitize=address,undefined
```

Disabling Assembly Optimizations

libdav1d relies heavily on highly optimized assembly code (x86 AVX2/AVX-512, ARM Neon) for fast decoding. Debugging raw assembly can be extremely difficult. To force the compiler to use readable C implementations instead, disable the assembly flag:

meson setup build -Denable_asm=false

Disabling assembly makes it straightforward to set breakpoints and step through the actual decoding logic in a debugger.

Enabling Helper Tools and Tests

To debug the library effectively, you often need the companion command-line tool (dav1d) and the test suite to verify changes.

Build the CLI Tool: Enable the compilation of the dav1d executable, which allows you to pass test video files directly to your debug build.
```
meson setup build -Denable_tools=true
```
Build Unit Tests: Enable compilation of the test binaries to run regression tests.
```
meson setup build -Denable_tests=true
```

Example: Full Debug Setup Command

For a comprehensive debugging environment that compiles C-only code with full debug symbols, address sanitizers, and the CLI tool enabled, use the following configuration:

meson setup build --buildtype=debug -Db_sanitize=address,undefined -Denable_asm=false -Denable_tools=true
ninja -C build