# samsung/netcoredbg architecture

> Architecture diagram of the GitHub repository samsung/netcoredbg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samsung/netcoredbg
- Repository: https://github.com/samsung/netcoredbg

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-End Layer
    subgraph "Front-End Adapters"
        direction TB
        CLI["CLI Protocol Adapter"]:::frontend
        MI["MI Protocol Adapter"]:::frontend
        VSC["VSCode Protocol Adapter"]:::frontend
    end

    %% Protocol to Engine
    CLI -->|"parses commands"| EngineCore
    MI -->|"parses commands"| EngineCore
    VSC -->|"parses commands"| EngineCore

    %% Core Engine Layer
    subgraph "Debug Engine Core"
        direction TB
        BM["Breakpoint Manager"]:::core
        SE["Stepping Engine"]:::core
        TF["Thread & Frame Manager"]:::core
        EV["Evaluator & Stack Machine"]:::core
    end
    EngineCore["Engine Core"]:::core --> BM
    EngineCore --> SE
    EngineCore --> TF
    EngineCore --> EV

    %% Interop Layer
    subgraph "Interop Layer"
        direction TB
        CCR["CoreCLR Hosting Interfaces"]:::interop
        MHE["Managed Evaluation Helpers"]:::interop
    end
    BM -->|"breakpoint events"| CCR
    SE -->|"step events"| CCR
    TF -->|"thread/frame info"| CCR
    EV -->|"invoke managed eval"| MHE
    CCR -->|"COM callbacks"| EngineCore
    MHE -->|"returns results"| EngineCore

    %% Runtime
    CoreCLRRT["CoreCLR Runtime"]:::external
    CCR -->|"host runtime"| CoreCLRRT
    CoreCLRRT -->|"callback events"| EngineCore

    %% Utilities & PAL
    subgraph "Platform & Utilities"
        direction TB
        PAL["OS Abstractions & Sync"]:::util
        IOFS["I/O Redirection & Filesystem"]:::util
        LOG["Logging & Error Utilities"]:::util
        META["Metadata & Type Printers"]:::util
        HOOK["Optional Managed Hook (ncdbhook)"]:::util
    end
    EngineCore --> PAL
    EngineCore --> IOFS
    EngineCore --> LOG
    EngineCore --> META
    EngineCore --> HOOK

    %% Third-Party Libraries
    subgraph "Third-Party Libraries"
        direction TB
        JSON["JSON"]:::third
        DWARF["DWARF & libelfin"]:::third
        CLIED["CLI Line Editing"]:::third
    end
    CLI --> CLIED
    BM --> DWARF
    VSC --> JSON
    MI --> JSON

    %% Tests
    subgraph "Test Suites"
        direction TB
        UTEST["Unit Tests"]:::test
        FTEST["Functional Tests"]:::test
    end
    UTEST --> CLI
    UTEST --> BM
    FTEST --> CLI
    FTEST --> MI
    FTEST --> VSC

    %% Build & Packaging
    subgraph "Build & Packaging"
        direction TB
        CMAKE["CMake Config & Scripts"]:::build
        SPEC["Packaging Specs"]:::build
    end
    CMAKE --> EngineCore
    CMAKE --> CLI
    CMAKE --> MI
    CMAKE --> VSC

    %% Click Events
    click CLI "https://github.com/samsung/netcoredbg/blob/master/src/protocols/cliprotocol.cpp"
    click MI "https://github.com/samsung/netcoredbg/blob/master/src/protocols/miprotocol.cpp"
    click VSC "https://github.com/samsung/netcoredbg/blob/master/src/protocols/vscodeprotocol.cpp"
    click BM "https://github.com/samsung/netcoredbg/blob/master/src/debugger/breakpoints.cpp"
    click SE "https://github.com/samsung/netcoredbg/blob/master/src/debugger/steppers.cpp"
    click TF "https://github.com/samsung/netcoredbg/blob/master/src/debugger/threads.cpp"
    click EV "https://github.com/samsung/netcoredbg/blob/master/src/debugger/evaluator.cpp"
    click CCR "https://github.com/samsung/netcoredbg/blob/master/src/coreclr/cordebug.h"
    click MHE "https://github.com/samsung/netcoredbg/blob/master/src/managed/Evaluation.cs"
    click PAL "https://github.com/samsung/netcoredbg/blob/master/src/utils/platform.h"
    click IOFS "https://github.com/samsung/netcoredbg/blob/master/src/utils/ioredirect.cpp"
    click LOG "https://github.com/samsung/netcoredbg/blob/master/src/utils/logger.cpp"
    click META "https://github.com/samsung/netcoredbg/blob/master/src/metadata/jmc.cpp"
    click HOOK "https://github.com/samsung/netcoredbg/blob/master/src/ncdbhook/ncdbhook.cs"
    click UTEST "https://github.com/samsung/netcoredbg/tree/master/src/unittests/"
    click FTEST "https://github.com/samsung/netcoredbg/tree/master/test-suite/"
    click JSON "https://github.com/samsung/netcoredbg/blob/master/third_party/json/json.hpp"
    click DWARF "https://github.com/samsung/netcoredbg/tree/master/third_party/libelfin/"
    click CLIED "https://github.com/samsung/netcoredbg/tree/master/third_party/linenoise-ng/"
    click CMAKE "https://github.com/samsung/netcoredbg/blob/master/CMakeLists.txt"
    click SPEC "https://github.com/samsung/netcoredbg/blob/master/packaging/netcoredbg.spec"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef core fill:#E6F4EA,stroke:#22863A,color:#22863A;
    classDef interop fill:#FFF5E1,stroke:#D29D2F,color:#8A4F0D;
    classDef util fill:#F0F0F0,stroke:#6A737D,color:#24292E;
    classDef third fill:#FFF5D1,stroke:#FFD33D,color:#735C0F;
    classDef test fill:#F5EEF8,stroke:#6F42C1,color:#6F42C1;
    classDef build fill:#FFE3E3,stroke:#CB2431,color:#CB2431;
    classDef external fill:#FFFFFF,stroke:#24292E,color:#24292E;
```
