How samsung/netcoredbg works
Project Type and Purpose
• This is an open-source native debugger tool for the .NET Core runtime.
• It implements multiple front-ends (GDB/MI and VSCode Debug Adapter Protocol) over a unified debugging engine, enabling both CLI and IDE-based debugging of managed .NET applications.
File Structure
• Top-level:
– CMake build system files (CMakeLists.txt, *.cmake)
– src/ – main source code
– test-suite/ – functional tests using real .NET apps
– third_party/ – bundled libs (Catch2, JSON, libelfin, linenoise-ng)
– docs/, packaging/, tools/
• src/ subdivisions:
– protocols/ – parsers/serializers for CLI, MI, VSCode protocols
– debugger/ – core debugging engine (breakpoints, steppers, threads, frames, evaluator)
– coreclr/, managed/ – interop definitions and managed helper code for evaluation
– interfaces/ – abstract interfaces (IDebugger, IProtocol)
– utils/ – platform abstractions, file I/O, logging
– metadata/ – metadata extraction, JMC, type printers
– ncdbhook/ – optional managed preload hook for interop mode
– unittests/ – Catch2 unit tests for internal modules
• Deployment & packaging: scripts and spec files in packaging/ and rpmbuild.cmake.
a. Main Components
1. Front-End Adapters
• CLI Interpreter (cliprotocol)
• MI Interpreter (miprotocol)
• VSCode Debug Adapter (vscodeprotocol)
2. Debug Engine Core
• Breakpoint Manager
• Stepping Engine
• Thread/Frame Manager
• Evaluator & Stack Machine
3. Interop Layer
• CoreCLR hosting interfaces (cordebug, corhdr)
• Managed evaluation helpers (Evaluation.cs, StackMachine.cs)
4. Platform Abstraction (PAL) & Utilities
• File system, threading, synchronization (rwlock, ioredirect)
• Logging, error utilities
5. Third-Party Libraries
• JSON for message formatting
• libelfin for DWARF symbol/libelf parsing
• linenoise-ng for CLI line editing
6. Build & Packaging
• CMake configuration modules
• Packaging scripts (NuGet, RPM, Spec files)
7. Test Suite
• Functional tests driving NetCoreDbg via CLI/MI/VSC interfaces
• Unit tests for core modules
b. Interactions and Data Flow
• Protocol Input → Protocol Parser → Debug Engine Core
• Core → Interop Layer → CoreCLR runtime → Event callbacks (breakpoint hit, step complete)
• Callback → Core Engine updates state → Protocol Serializer → Protocol Output
• Managed evaluation calls cross via P/Invoke layer to enable complex expression evaluation
• Platform layer abstracts OS calls for portability (signals, threads, memory)
c. Architectural Patterns & Principles
• Adapter pattern for pluggable protocol front-ends (IProtocol)
• Facade for the debug engine managing low-level interop and state machines
• Strategy for platform-specific implementations (PAL)
• Separation of concerns: protocol parsing, debugging logic, interop, and utilities
d. Key Technologies & Frameworks
• C++17, CMake for build
• .NET (managed) for evaluation support
• GDB/MI protocol, Debug Adapter Protocol (DAP)
• Third-party: Catch2 (unit testing), JSON for Modern C++
Detailed Capture of Architectural Elements
• How the managed helper assembly (ManagedPart.csproj) is loaded and invoked.
• IProtocol interface boundary that allows adding future protocols.