Debugging SerenityOS

Tools and techniques for debugging SerenityOS applications and kernel code

SerenityOS provides comprehensive debugging capabilities for both userspace applications and kernel development.

Debug Macros

Many parts of the SerenityOS codebase have debug functionality through component-specific macros that print additional messages to the debug console.

Enabling Debug Macros

Debug macros follow the pattern <component_name>_DEBUG and can be enabled individually at build time:

# Enable process debugging
cmake -B Build/x86_64 -DPROCESS_DEBUG=ON

# Enable multiple debug macros
cmake -B Build/x86_64 -DPROCESS_DEBUG=ON -DSCHEDULER_DEBUG=ON

Do not enable ENABLE_ALL_THE_DEBUG_MACROS in normal development. It clutters console output and makes the system run very slowly. Only enable the specific debug macros you need.

Available debug macros are listed in Meta/CMake/all_the_debug_macros.cmake.

Sanitizers

Address Sanitizer

Address Sanitizer catches memory corruption bugs including buffer overflows and memory leaks.

Enable Address Sanitizer for Lagom tests

cmake -GNinja -S Meta/Lagom -B Build/lagom \
  -DBUILD_LAGOM=ON \
  -DENABLE_ADDRESS_SANITIZER=ON

cd Build/lagom
ninja
CTEST_OUTPUT_ON_FAILURE=1 SERENITY_SOURCE_DIR=${PWD}/../.. ninja test

Enable Kernel Address Sanitizer

cmake -B Build/x86_64 -DENABLE_KERNEL_ADDRESS_SANITIZER=ON
ninja -C Build/x86_64 install

Undefined Behavior Sanitizer

Detects undefined behavior like null pointer dereferences and signed integer overflows.

Enable for userspace

cmake -B Build/x86_64 -DENABLE_UNDEFINED_SANITIZER=ON

To make errors fatal and reduce performance overhead:

cmake -B Build/x86_64 \
  -DENABLE_UNDEFINED_SANITIZER=ON \
  -DUNDEFINED_BEHAVIOR_IS_FATAL=ON

Enable for kernel

cmake -B Build/x86_64 -DENABLE_KERNEL_UNDEFINED_SANITIZER=ON

# Make UBSan errors always deadly
cmake -B Build/x86_64 \
  -DENABLE_KERNEL_UNDEFINED_SANITIZER=ON \
  -DENABLE_KERNEL_UNDEFINED_SANITIZER_ALWAYS_DEADLY=ON

Running tests with sanitizers

Ensure UBSan errors fail the test:

UBSAN_OPTIONS=halt_on_error=1 \
CTEST_OUTPUT_ON_FAILURE=1 \
SERENITY_SOURCE_DIR=${PWD}/.. \
ninja test

Memory Sanitizer

Enables runtime checks for uninitialized memory accesses in Lagom test cases:

cmake -GNinja -S Meta/Lagom -B Build/lagom \
  -DBUILD_LAGOM=ON \
  -DENABLE_MEMORY_SANITIZER=ON

Sanitizer builds take significantly longer than normal builds and will affect cache performance in tools like ccache.

Kernel Debugging

Extra Kernel Debug Symbols

For easier debugging of kernel code, enable extra debug symbols:

cmake -B Build/x86_64 -DENABLE_EXTRA_KERNEL_DEBUG_SYMBOLS=ON

This sets -Og and -ggdb3 compile options for the kernel. By default, the kernel is built with -O2.

GDB Integration

Debugging with GDB

SerenityOS supports GDB debugging through QEMU:

# The build system automatically enables KVM debugging if available
# To disable GDB socket:
SERENITY_DISABLE_GDB_SOCKET=1 ninja run

If you encounter “KVM doesn’t support guest debugging”:

• Update your host kernel to at least version 5.10
• Verify your distro has QEMU debug features enabled
• Or disable KVM debugging: SERENITY_DISABLE_GDB_SOCKET=1

Kernel Coverage Collection

For coverage-guided kernel fuzzing:

cmake -B Build/x86_64 -DENABLE_KERNEL_COVERAGE_COLLECTION=ON

This enables the KCOV API and kernel coverage collection instrumentation.

Userspace Coverage

Enable coverage collection for userspace (Clang builds only):

cmake -B Build/x86_64 -DENABLE_USERSPACE_COVERAGE_COLLECTION=ON

Running Tests

See the Testing guide for information on running and debugging tests.

CMake Cache Manipulation

Debug flags can be modified after an initial build:

# Initial build
cmake -GNinja -S Meta/CMake/Superbuild -B Build/superbuild-x86_64
cmake --build Build/superbuild-x86_64

# Enable debug options
cmake -B Build/x86_64 -DPROCESS_DEBUG=ON -DBUILD_BROWSER=OFF
ninja -C Build/x86_64 install

Use ccmake (TUI interface) or cmake-gui for interactive cache manipulation.