Debugging

Tools and techniques for debugging sharp-runtime code.

Build for Debug

cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build

Debug builds include debug symbols and disable optimizations, making GDB/LLDB much more useful.

Debug and Trace Utilities

include/System/Diagnostics/Debug.hpp | Trace.hpp

Static assertion and trace output methods — header-only, no link dependencies:

#include <System/Diagnostics/Debug.hpp>
#include <System/Diagnostics/Trace.hpp>

// Assertion (aborts if condition is false in debug builds)
System::Diagnostics::Debug::Assert(ptr != nullptr);
System::Diagnostics::Debug::Assert(count > 0, "Count must be positive");

// Output messages
System::Diagnostics::Debug::WriteLine("Starting process...");
System::Diagnostics::Debug::Fail("Unexpected branch reached");

// Trace (similar, but typically for release/logging)
System::Diagnostics::Trace::WriteLine("Operation completed");

Stopwatch

include/System/Diagnostics/Stopwatch.hpp

Measures elapsed time using std::chrono:

#include <System/Diagnostics/Stopwatch.hpp>

System::Diagnostics::Stopwatch sw;
sw.Start();

// ... code to measure ...

sw.Stop();
long ms = sw.ElapsedMilliseconds;
long us = sw.ElapsedMicroseconds;   // if available — needs verification
std::cout << "Elapsed: " << ms << "ms\n";

// Reset and restart
sw.Reset();
sw.Restart(); // Reset + Start in one call

Debugger Breakpoints

include/System/Diagnostics/Debugger.hpp

#include <System/Diagnostics/Debugger.hpp>

// Programmatic breakpoint
System::Diagnostics::Debugger::Break();

// Check if debugger is attached
if (System::Diagnostics::Debugger::IsAttached) {
    // special debugger-only behavior
}

Using GDB / LLDB

Standard C++ debuggers work well with sharp-runtime since it is plain C++ code:

# Build with debug symbols
cmake -B build -DCMAKE_BUILD_TYPE=Debug && cmake --build build

# GDB
gdb ./build/tests/sharp_runtime_tests
(gdb) run
(gdb) bt         # backtrace after crash
(gdb) p myObj    # print variable

# LLDB
lldb ./build/tests/sharp_runtime_tests
(lldb) run
(lldb) bt        # backtrace
(lldb) po myObj  # print object

Address Sanitizer

cmake -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined"
cmake --build build
./build/tests/sharp_runtime_tests

AddressSanitizer detects buffer overflows, use-after-free, and other memory errors. Highly recommended when adding new code.

Running Specific Tests

# Run a single test suite
./build/tests/sharp_runtime_tests --gtest_filter=StringTest.*

# Run all tests matching a pattern
./build/tests/sharp_runtime_tests --gtest_filter=*Array*

# Show full output (don't suppress passing test output)
./build/tests/sharp_runtime_tests --gtest_filter=ListTest.* -v

StackTrace Limitations

System::Diagnostics::StackTrace and StackFrame are stub classes. Stack unwinding information is not captured at runtime. For stack traces, use GDB/LLDB or -g debug symbols with crash handlers.