Documentation Index Fetch the complete documentation index at: https://mintlify.com/serenityOS/serenity/llms.txt
Use this file to discover all available pages before exploring further.
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.
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
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 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
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.
