DOCSEARCHbyAlgolia
Submit Docs

NetCoreDbg Documentation

repository·master·Indexed 23 days ago

https://github.com/samsung/netcoredbg

NetCoreDbg is a debugger for the .NET Core runtime that implements both GDB/MI and the VSCode Debug Adapter Protocol (DAP). It enables debugging of .NET applications via the command line or modern IDEs like VS Code. The documentation covers installation via package managers (Arch, Gentoo, LiGurOS, NixOS, Scoop), building from source on Linux and Windows using CMake and Clang/Visual Studio, CLI reference, and running the comprehensive test suite.

Tokens
10.8K
Snippets
25
Records
53
Agent score
78%

What's inside NetCoreDbg

  1. Overview of Libelfin

    master

    Libelfin is a C++11 library designed for reading ELF binaries and DWARFv4 debug information. It provides a syntactic layer for parsing the bytes of DWARF and ELF, making the data structures accessible through a native C++11 interface.

    Note: This specific version is a maintained fork within the netcoredbg repository and is not supported in the upstream libelfin repository.

  3. Overview of Linenoise Next Generation

    master

    Linenoise Next Generation is a small, portable GNU readline replacement designed for Linux, Windows, and MacOS. It is a zero-config, BSD-licensed library that provides a pure C interface (despite using C++ internally) for line editing.

    Key Features:

    • Single-line and multi-line editing modes with standard key bindings.
    • History handling and command completion.
    • UTF-8 awareness.
    • Support for Linux, MacOS, and Windows.
    • Uses only a subset of VT100 escapes (ANSI.SYS compatible).
    • BSD license, making it suitable for use in Apache2 or BSD licensed programs, including commercial software.

  4. Understand the Libelfin Semantic Limitation

    master

    It is important to distinguish between the syntactic and semantic layers when using Libelfin.

    Libelfin implements a syntactic layer, meaning it handles the parsing of bytes into structured data. However, it does not implement a semantic layer. To interpret the actual meaning of the information stored within the DWARF DIE trees, the developer must still possess a deep understanding of the DWARF specification.

  5. Understanding Yield and Resume Offsets

    master

    In the context of async method stepping, two specific IL offsets are used to manage the transition through an await block:

    1. Yield offset: The point at the beginning of the await block code. It is used to detect the start of await-related code.
    2. Resume offset: The point at the end of the await block code. The debugger uses this offset to finish a step (moving from internal await code to the closest user code line IL offset) using ICorDebugStepper.

    For example, in a compiled async Task Main method, the PDB might specify a yield offset of 0x3C and a resume offset of 0x57 to manage the transition around the Task.Delay call.

  6. How async/await stepping works in NetcoreDBG

    master

    When debugging asynchronous methods in .NET, NetcoreDBG handles the fact that async methods are compiled into state machines. Because the execution can jump between different threads during an await operation, the debugger cannot rely solely on ICorDebugStepper.

    Key mechanisms used for async stepping:

    • State Machine Conversion: User code is moved into a MoveNext method within a generated state machine.
    • PDB Metadata: The PDB file provides an asyncMethodSteppingInformationBlob containing yield and resume offsets.
    • Async ID Tracking: To track the correct execution context across thread changes, the debugger calls the ObjectIdForDebugger property getter on the state machine's task builder at both yield and resume offsets.
    • Hybrid Stepping: The debugger uses breakpoints at the yield and resume offsets, combined with ICorDebugStepper to finish the step from internal await code back to the closest user code line IL offset.

  7. How interop mode works in NetCoreDbg

    master

    Interop mode (or mixed native/managed mode) allows you to debug sessions involving both C# (managed) and C/C++ (native) code. There are two primary scenarios supported:

    1. Native app calling managed DLL: Supported via the attach debug session type.
    2. Managed app calling native dynamic library: Supported via both launch and attach debug session types.

    Platform and Architecture Restrictions: Interop mode is currently implemented only for Linux and Tizen OS on the following architectures:

    • amd64
    • x86
    • arm64
    • arm32
    • riscv64
    • loongarch64

  8. Use get-vscodecmd.py to extract VS Code client commands

    master

    The get-vscodecmd.py script is an experimental tool used to extract VS Code client commands from the debugger output. This is useful for developers who need to reproduce issues or inspect the VS Code protocol communication.

    Note that the debugger side can be sensitive to certain temporary object values in the VS Code protocol, and using this method may result in unstable debugger behavior.

    $ get-vscodecmd.py vscode_output > cmd
$ unix2dos cmd

$ netcoredbg --interpreter=vscode --engineLogging=/tmp < cmd

  9. Start a debug session in interop mode

    master

    To enable interop debugging, you must include the --interop-debugging flag. You can either attach to an existing process or launch a new process using the CLI interpreter.

    Attach to an existing process:

    $ netcoredbg --interpreter=cli --interop-debugging --attach PID

    Launch a new program:

    $ netcoredbg --interpreter=cli --interop-debugging -- dotnet hello.dll param1 param2

  10. Start NetCoreDbg in CLI mode

    master

    You can start NetCoreDbg in two ways:

    1. Fast Start: Run the debugger and the target program in a single command using the --interpreter=cli flag.
    2. Interactive Mode: Start the interactive CLI shell and load the executable and arguments manually using file and set args commands.

    Note: To debug Release builds of DLLs with PDBs, you must disable 'Just-My-Code' using set just-my-code 0.

    # Fast start
$ netcoredbg --interpreter=cli -- dotnet hello.dll param1 param2

# Interactive mode
$ netcoredbg --interpreter=cli

  11. Build and run unit tests

    master
    To include unit tests in your build, you must pass the -DBUILD_TESTING=ON option to CMake. After a successful build, you can execute the unit tests using the make test command. For more detailed information, refer to src/unittests/README.md.

  12. Run a single unit test for detailed output

    master

    If the full test suite fails, you can run an individual test binary directly from the build directory to see more granular details. The tests use the Catch v2.6.1 framework. Running a specific test binary will show which specific assertions failed and the exact line numbers in the source code.

    netcoredbg/build$ ./src/unittests/iosystem