Samsung NetCoreDbg for CoreCLR debugging

What NetCoreDbg debugs and who should consider it

NetCoreDbg targets managed code running under Microsoft's .NET Core runtime, also referred to as CoreCLR in the README. Its specific purpose is to provide debugger access for .NET applications without requiring the usual Microsoft Visual Studio debugging environment. The project exposes three interfaces in a unified framework: GDB/MI, VSCode Debug Adapter Protocol, and a command-line interface for debugging from a terminal.

That design makes the project relevant to runtime engineers, SDK and tooling developers, and teams that need to connect an existing editor or automation system to CoreCLR debugging. A GDB-oriented workflow is different from an IDE-oriented workflow. NetCoreDbg does not present itself as a general-purpose IDE or application profiler. It is a debugger that adapts CoreCLR debugging information to interfaces already used by command-line tools, editors, and development automation.

The project is written primarily in C#, but the build also depends on C++ tooling, CoreCLR sources, the .NET SDK or runtime, and CMake. This is a relevant constraint for evaluation. NetCoreDbg is not simply a managed library that can be added to an application. It is a runtime-facing debugging component with a source build and native compilation requirements.

The GDB/MI, VSCode DAP, and CLI architecture

The central architectural decision is the use of multiple debugger interfaces over one debugging framework. The README states that NetCoreDbg implements GDB/MI and the VSCode Debug Adapter Protocol in a unified framework. This means that the same CoreCLR debugger can serve clients using either protocol rather than requiring separate debugger implementations for each integration.

GDB/MI is the machine-oriented interface associated with GDB-style debugging. It is useful when a developer wants a debugger client that understands a text protocol, or when debugging needs to be incorporated into command-line tooling. The VSCode Debug Adapter Protocol is intended for editor integrations based on the Debug Adapter Protocol model. The CLI documentation is the project’s stated source for command-line usage, although the README does not reproduce its commands.

The available interfaces also define the project’s boundaries. NetCoreDbg focuses on CoreCLR applications and interoperation support rather than documenting a general debugger for every runtime. The repository includes a `docs/cli.md` manual and a separate `docs/interop.md` guide. The latter applies to Linux and Tizen OS builds configured with `INTEROP_DEBUGGING=1`, so the native interoperation path is optional rather than part of the basic build.

Installing NetCoreDbg on Linux from source

The README lists packages for Arch Linux, Gentoo Linux, LiGurOS, NixOS, and Windows Scoop. For other Linux distributions, it points users to the binaries attached to GitHub releases or to building from source. Those package routes are the shortest documented installation options when they match the target system. The README does not provide a single universal package command, so commands for those repositories are not interchangeable.

For a source build, the Linux prerequisites are `cmake`, either `make` or `ninja`, the clang C++ compiler, Microsoft’s .NET runtime, and common development tools such as Git. The project specifically says that it cannot be built with gcc. CoreCLR runtime sources and the .NET SDK can be downloaded automatically by the build, although the project also documents manual download when automatic fetching fails.

The following is the documented configuration sequence. It creates a build directory, enters it, and configures the project with clang as both the C and C++ compiler.

user@netcoredbg$ mkdir build
user@netcoredbg$ cd build
user@build$ CC=clang CXX=clang++ cmake ..

After configuration finishes, the README gives the build and install commands below. The installed binaries are directed to the build’s local `bin` area when the test-related install prefix option is supplied.

user@build$ make
...
user@build$ make install

The source tree is not automatically uninstalled. The documented cleanup commands remove the build directory, generated source output, and local installed binaries.

user@build$ cd ..
user@netcoredbg$ rm -rf build src/debug/netcoredbg/bin bin

The README says that binaries installed elsewhere, such as `/usr/local/bin`, must be removed manually.

Platform-specific build paths and their boundaries

The source build supports Linux, macOS, and Windows. On macOS, the project requires Homebrew and otherwise follows the Unix process. The README cautions that the macOS arm64 build for M1 is community supported and may not work as expected, and that some tests may fail. That qualification matters because the list of supported architectures includes ARM 64-bit, but the platform note limits confidence in the M1 build.

Windows requires CMake, Microsoft Visual Studio 2019 or newer, Git, and the C# and C++ development options from the Visual Studio installer. The documented configuration command uses Visual Studio’s CMake generator:

C:\Users\localuser\netcoredbg> md build
C:\Users\localuser\netcoredbg> cd build
C:\Users\localuser\netcoredbg\build> cmake .. -G "Visual Studio 16 2019"

The README says this command must be run from `cmd.exe`, not from a Cygwin shell. It also identifies Visual Studio 2019 as the minimum version for the Windows build.

Linux and Tizen OS users can add interoperation debugging by installing `libunwind-dev` or `libunwind-devel` and configuring with the following option:

user@build$ CC=clang CXX=clang++ cmake .. -DINTEROP_DEBUGGING=1

The project documents optional source-based code coverage through `-DCLR_CMAKE_ENABLE_CODE_COVERAGE`. It also documents `DOTNET_DIR` and `CORECLR_DIR` for manually supplied SDK and CoreCLR source locations. These switches make offline or customized builds possible, but they also add configuration choices that must match the source tree.

First use through the CLI documentation

The README directs users to `docs/cli.md` for detailed CLI usage, so it does not document a complete first debugging session in the text provided here. That omission prevents a safe, exact example for launching a particular .NET application, selecting a port, or attaching to a process. No such command or environment variable should be invented from another debugger’s documentation.

The documented first-use path is therefore procedural. Install a packaged NetCoreDbg version where a repository provides one, or download a release binary for an unlisted Linux distribution. Alternatively, build the project with clang and complete the build. Then open `docs/cli.md` and use the CLI syntax documented there for the intended CoreCLR application. For editor integration, consult the VSCode Debug Adapter Protocol documentation and the project’s CLI material for the supported connection behavior.

The repository includes `test-suite/`, `packaging/`, and `src/`, but the README excerpt does not map those directories to a beginner-level launch workflow. The `-DCMAKE_INSTALL_PREFIX` option is specifically tied to enabling tests after a successful build, not to a general runtime configuration. A reader who needs a scripted debugging example should first verify the exact command in `docs/cli.md` and confirm the application and runtime versions it expects.

Limitations, maintenance signals, and license effects

The clearest limitation is build complexity. NetCoreDbg requires CoreCLR sources or a build system that can obtain them, Microsoft’s .NET components, CMake, and clang on Linux. Automatic dependency downloads may fail, forcing a manual source setup. gcc is explicitly excluded on Unix. The Windows path has a separate generator and shell requirement, and the macOS arm64 path carries a community-support warning.

Another limitation is the absence of an automatic uninstall operation in the documented build system. Removing generated files is documented, but an installation made outside the local `bin` directory requires manual cleanup. This is an operational cost rather than a functional promise, and it matters when NetCoreDbg is installed repeatedly on developer machines or in controlled images.

The repository is not archived. Its last push was on 2026-06-25, and the listed releases include 3.2.0-1092 on 2026-06-25, 3.1.3-1062 on 2025-12-12, and 3.1.2-1054 on 2024-11-02. These are repository facts, not evidence that every target runtime or platform is supported. Upgrade planning should account for the project’s release numbering and for changes in CoreCLR sources or SDK dependencies, which are part of the documented build process.

NetCoreDbg uses the MIT license, with licensing information in the repository’s `LICENSE` file. That identifies the license associated with the source, but it does not answer organization-specific compliance questions. Readers should inspect the actual `LICENSE` file and any package or dependency notices for their own use.

Editorial conclusion

NetCoreDbg is a reasonable fit for engineers debugging CoreCLR applications through GDB/MI, VSCode DAP, or a command-line interface, especially where Visual Studio is not the intended workflow. It is a weaker fit for a quick binary installation on an unsupported Linux distribution or for maintainers who need an automatic uninstall path. Before adoption, verify that the target CoreCLR version and architecture are supported, choose the documented package or binary route, and confirm that your editor can speak the required protocol. The first release checked is 3.2.0-1092, published on 2026-06-25.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. Samsung/netcoredbg on GitHub