{"id":21644456,"url":"https://github.com/samsung/netcoredbg","last_synced_at":"2025-05-14T20:07:42.473Z","repository":{"id":37548489,"uuid":"113926796","full_name":"Samsung/netcoredbg","owner":"Samsung","description":"NetCoreDbg is a managed code debugger with GDB/MI, VSCode DAP and CLI interfaces for CoreCLR.","archived":false,"fork":false,"pushed_at":"2024-11-02T11:46:35.000Z","size":4036,"stargazers_count":952,"open_issues_count":44,"forks_count":114,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-04-10T09:58:44.009Z","etag":null,"topics":["csharp","debugger","dotnet"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Samsung.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-12T01:15:07.000Z","updated_at":"2025-04-09T06:29:24.000Z","dependencies_parsed_at":"2024-12-17T19:03:15.335Z","dependency_job_id":"7d458330-bc1f-4168-9825-beaf5d2201ca","html_url":"https://github.com/Samsung/netcoredbg","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samsung%2Fnetcoredbg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samsung%2Fnetcoredbg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samsung%2Fnetcoredbg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samsung%2Fnetcoredbg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Samsung","download_url":"https://codeload.github.com/Samsung/netcoredbg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254219373,"owners_count":22034397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csharp","debugger","dotnet"],"created_at":"2024-11-25T05:40:18.963Z","updated_at":"2025-05-14T20:07:42.455Z","avatar_url":"https://github.com/Samsung.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Debugger for the .NET Core Runtime\n\nThe NetCoreDbg debugger implements [GDB/MI](https://sourceware.org/gdb/onlinedocs/gdb/GDB_002fMI.html)\nand [VSCode Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) in a unified framework, allowing the debugging of .NET apps under the .NET Core runtime as well as facilitating debugging from the command line (such as in GDB).\n\n## Copyright\n\nYou can find licensing information in the [LICENSE](LICENSE) file within the root directory of the NetCoreDbg sources.\n\n## Usage\nFurther details regarding the usage of NetCoreDbg can be found in the [CLI](docs/cli.md) manual.\n\n## Installation\nNetCoreDbg is available in repositories of some Linux distributions and Windows package manager:\n- Arch Linux (https://aur.archlinux.org/packages/netcoredbg)\n- Gentoo Linux (https://packages.gentoo.org/packages/dev-dotnet/netcoredbg)\n- LiGurOS (https://gitlab.com/liguros/liguros-repo/-/tree/develop/dev-dotnet/netcoredbg?ref_type=heads)\n- NixOS (https://mynixos.com/nixpkgs/package/netcoredbg)\n- Scoop (Windows) (https://github.com/ScoopInstaller/Main/blob/master/bucket/netcoredbg.json)\n\nFor other Linux distributions you can use binaries provided in github releases (https://github.com/Samsung/netcoredbg/releases) or build from source code.\n\n## Building from Source Code\n\nCurrently, NetCoreDbg can be built on Linux, MacOS, or Windows. Instructions for building NetCoreDbg on each platform is shown below.\n\n### Supported Architectures\n\n- ARM 32-bit\n- ARM 64-bit\n- x64\n- x86\n- RISC-V 64-bit\n\n### Unix\n\nNetCoreDbg's build requires Microsoft's .NET, and as such, NetCoreDbg can only be built in Linux. Microsoft supports a few distributions, the details of which can be found here: https://docs.microsoft.com/en-us/dotnet/core/install/linux.\n\n#### Prerequisites\n\n1. You need to install `cmake`, and either `make` or `ninja`.\n\n2. You need the clang C++ compiler installed (NetCoreDbg can't be built with gcc).\n\n3. Microsoft's **.NET runtime** should be installed, which you can download here: https://dotnet.microsoft.com/download.\n\n4. You may also need to install some common developers tools not mentioned here, such as [Git](https://www.git-scm.com/downloads), etc...\n\n5. It is expected that you place the NetCoreDbg sources within a directory.\n\n6. Optional step: NetCoreDbg requires the **CoreCLR runtime source code**, which is typically downloaded automatically, but can also be downloaded manually from here: https://github.com/dotnet/runtime.\n\n   *For example, you can check out tag v8.x.*\n\n7. Optional step: NetCoreDbg requires the **.NET SDK**, which is typically downloaded automatically, but can also be downloaded manually from here: https://dotnet.microsoft.com/download.\n\n#### Compiling\n\nConfigure the build with the following commands:\n\n```\nuser@netcoredbg$ mkdir build\nuser@netcoredbg$ cd build\nuser@build$ CC=clang CXX=clang++ cmake ..\n```\n\nIn order to run tests after a successful build, you need to add the option `-DCMAKE_INSTALL_PREFIX=$PWD/../bin`.\n\nTo enable the Source-Based Code Coverage feature (https://clang.llvm.org/docs/SourceBasedCodeCoverage.html),\nadd the `-DCLR_CMAKE_ENABLE_CODE_COVERAGE` option.\n\nIf you have previously downloaded the .NET SDK or CoreCLR sources, then you should modify the command line by adding the following options: \n`-DDOTNET_DIR=/path/to/sdk/dir -DCORECLR_DIR=/path/to/coreclr/sources`.\n\nIf cmake tries to download the .NET SDK or CoreCLR sources and fails, then please see bullet numbers 6 and 7 above. *You can download any required files manually*.\n\nAfter configuration has finished, you can then build NetCoreDbg:\n\n```\nuser@build$ make\n...\nuser@build$ make install\n```\n\nTo perform a build from scratch, including the configuration step, you should again delete any artifacts with the following commands:\n\n```\nuser@build$ cd ..\nuser@netcoredbg$ rm -rf build src/debug/netcoredbg/bin bin\n```\n\n\u003e *Directory `bin` contains \"installed\" NetCoreDbg's binaries for tests. If you have installed NetCoreDbg in other places, for example in `/usr/local/bin`, you should remove it manually because NetCoreDbg's build system doesn't currently implement automatic uninstalling.*\n\n#### Prerequisites and Compiling with Interop Mode Support (Linux and Tizen OSes only)\nThe prerequisites and compiling process are the same as the aforementioned with the following changes:\n\n1. Depending on your distro, you need to install either the `libunwind-dev` or `libunwind-devel` packages.\n\n2. Configure the build with the following commands:\n\n```\nuser@build$ CC=clang CXX=clang++ cmake .. -DINTEROP_DEBUGGING=1\n```\nTo find more details on the usage of NetCoreDbg in Interop Mode, please see the guide doc: [Interop Mode](docs/interop.md).\n\n### MacOS\n\nYou need to install homebrew from here: https://brew.sh/\n\nAfter this, the build instructions are the same as for Unix, including the prerequisites.\n\n*Note: the MacOS arm64 build (M1) is community supported and may not work as expected, as well as some tests possibly failing.*\n\n### Windows\n\n#### Prerequisites:\n\n1. Download and install **CMake** from here: https://cmake.org/download\n\n2. Download and install **Microsoft's Visual Studio 2019** or newer from here: https://visualstudio.microsoft.com/downloads\n\n   *During installation of Visual Studio you should install all of the options required\n   for C# and C++ development on Windows*.\n\n3. Download and install **Git**; you have a few options here:\n\n * use original Git: https://git-scm.com/download/win\n * use TortoiseGit: https://tortoisegit.org/download\n * or use git installed in cygwin: https://cygwin.com/install.html\n\n4. Utilize Git to place NetCoreDbg sources in a directory.\n\n5. This step may be omitted, and in that case, cmake will automatically download all necessary files.\n   But if it fails, you then need to manually download the **CoreCLR sources** into another directory from here: https://github.com/dotnet/runtime.\n\n   *For example, you can use the latest tag **v8.x***.\n\n6. This step may also be omitted, and in that case, cmake will automatically download all necessary files.\n   But if it fails, you then need to manually download and install the **.NET SDK** from here: https://dotnet.microsoft.com/download\n\n#### Compiling\n\nConfigure the build with the following commands given in NetCoreDbg's source tree:\n\n```\nC:\\Users\\localuser\\netcoredbg\u003e md build\nC:\\Users\\localuser\\netcoredbg\u003e cd build\nC:\\Users\\localuser\\netcoredbg\\build\u003e cmake .. -G \"Visual Studio 16 2019\"\n```\n\n*Note: You should run this command from cmd.exe, **not from cygwin's shell***.\n\nOption `-G` specifies which instance of Visual Studio should build the project.\nNote, the minimum requirements for NetCoreDbg's build is the **Visual Studio 2019** version.\n\nIf you want to run tests after a successful build, then you should add the following option: `-DCMAKE_INSTALL_PREFIX=\"%cd%\\..\\bin\"`.\n\nIf you have downloaded either the .NET SDK or .NET Core sources manually, you should add the following options:\n`-DDOTNET_DIR=\"c:\\Program Files\\dotnet\" -DCORECLR_DIR=\"path\\to\\coreclr\"`\n\nTo compile and install, use the following command:\n\n```\nC:\\Users\\localuser\\netcoredbg\\build\u003e cmake --build . --target install\n```\n\nTo perform a build from scratch, including the configuration step, you should again delete any artifacts by using the following commands:\n\n```\nC:\\Users\\localuser\\netcoredbg\\build\u003ecd ..\nC:\\Users\\localuser\\netcoredbg\u003ermdir /s /q build src\\debug\\netcoredbg\\bin bin\n```\n\n\u003e *Directory `bin` contains the \"installed\" NetCoreDbg's binaries for tests. If you have installed NetCoreDbg in other places, you should remove it manually because NetCoreDbg's build system doesn't currently perform automatic uninstalling.*\n\n## Running NetCoreDbg\n\nIn the instructions provided above, the `netcoredbg` binary and additional libraries will be installed in some directory.\nFor development purposes (for running tests, debugging, etc...), the directory `bin` in NetCoreDbg's source tree is typically used.\n\nNow, running the debugger with the `--help` option should look like this:\n\n```\n$ ../bin/netcoredbg --help\n.NET Core debugger\n\nOptions:\n--buildinfo                           Print build info.\n--attach \u003cprocess-id\u003e                 Attach the debugger to the specified process id.\n--interpreter=cli                     Runs the debugger with Command Line Interface.\n--interpreter=mi                      Puts the debugger into MI mode.\n--interpreter=vscode                  Puts the debugger into VS Code Debugger mode.\n--command=\u003cfile\u003e                      Interpret commands file at the start.\n-ex \"\u003ccommand\u003e\"                       Execute command at the start\n--run                                 Run program without waiting commands\n--engineLogging[=\u003cpath to log file\u003e]  Enable logging to VsDbg-UI or file for the engine.\n                                      Only supported by the VsCode interpreter.\n--server[=port_num]                   Start the debugger listening for requests on the\n                                      specified TCP/IP port instead of stdin/out. If port is not specified\n                                      TCP 4711 will be used.\n--log[=\u003ctype\u003e]                        Enable logging. Supported logging to file and to dlog (only for Tizen)\n                                      File log by default. File is created in 'current' folder.\n--version                             Displays the current version.\n\n```\n\nBasically, to debug .NET code, you should run NetCoreDbg with the following command line:\n\n```\n$ /path/to/netcoredbg --interpreter=TYPE -- /path/to/dotnet /path/to/program.dll\n```\n\n## Notes for Developers\n\n### Running the Tests\n\nDetailed instructions on how to run tests can be found in the `test-suite` directory here: [test-suite/README.md](test-suite/README.md).\nYou simply need to build and install NetCoreDbg into the `bin` directory (in the NetCoreDbg source tree) and then change the directory to `test-suite` and run the following script `/run_tests.sh`.\n\nIf you wish to get the \"Source-Based Code Coverage\" report, you can add a `-c` or `--coverage` option to the command line, i.e.:\n`./run_tests.sh -c [[testname1][testname2]..]`.\n\nPlease note, for that case your build configuration should be implemented with the `-DCLR_CMAKE_ENABLE_CODE_COVERAGE` option (please see above). *This feature is currently only supported on Unix-like platforms*.\n\n### Building and Running Unit Tests\n\nIn order to build unit tests, you need to add the following option to CMake: `-DBUILD_TESTING=ON`.\n\nAfter a successful build, you may then run unit tests by running the command: `make test`.\n\nPlease see details here: [src/unittests/README.md](src/unittests/README.md).\n\n### Enabling Logs\n\nOn the Tizen platform, NetCoreDbg will send logs to the system logger. On other platforms, you should specify the file to which any logs will be written. This can be done by setting the environment variable, for example:\n```\nexport LOG_OUTPUT=/tmp/log.txt\n```\n\nEach line of the log file utilizes the same format which is explained below:\n```\n5280715.183 D/NETCOREDBG(P12036, T12036): cliprotocol.cpp: evalCommands(1309) \u003e evaluating: 'source file.txt'\n      ^     ^  ^          ^       ^        ^               ^            ^       ^\n      |     |  |          |       |        |               |            |       `-- Message itself.\n      |     |  |          |       |        |               |            |   \n      |     |  |          |       |        |               |            `-- Source line number.\n      |     |  |          |       |        |               |    \n      |     |  |          |       |        |               `-- This is function name.\n      |     |  |          |       |        |\n      |     |  |          |       |        `-- This is file name in which logging is performed.\n      |     |  |          |       |\n      |     |  |          |       `-- This is thread ID.\n      |     |  |          |      \n      |     |  |          `-- This is process PID\n      |     |  |         \n      |     |  `-- This program name (always NETCOREDBG).\n      |     |\n      |     `-- This is log level: E is for error, W is for warnings, D is for debug...\n      |\n      `--- This is time in seconds from the boot time (might be wrapped around).\n```\n\n### Selecting between Debug and Release Builds\n\nYou can select the build type by providing one of the following options for CMake:\n\n  * ` -DCMAKE_BUILD_TYPE=Debug ` for a debug build (contains zero optimizations, but is suitable for debugging);\n\n  * ` -DCMAKE_BUILD_TYPE=Release ` for a release build (optimized, but difficult to debug).\n\nBy default, NetCoreDbg's build system creates release builds.\n\n### Using the Address Sanitizer\n\nExample:\n```\nCC=clang-10 CXX=clang++-10 cmake .. -DCMAKE_INSTALL_PREFIX=$PWD/../bin  -DCMAKE_BUILD_TYPE=Debug  -DCORECLR_DIR=/path/to/coreclr -DDOTNET_DIR=/usr/share/dotnet -DASAN=1\n```\n\n### Using Clang-Tidy\n\nFirst, Install clang-10.\n\nNext, to use clang-tidy, modify the commands used to configure the build as below:\n\n```\nCC=clang-10 CXX=clang++-10   cmake .. . -DCMAKE_CXX_CLANG_TIDY=clang-tidy-10 -DCMAKE_INSTALL_PREFIX=$PWD/../bin\n```\n\nThen just run `make`. Any and all errors will be printed to stderr.\n\nSee details here: https://blog.kitware.com/static-checks-with-cmake-cdash-iwyu-clang-tidy-lwyu-cpplint-and-cppcheck/\n\n*Note: Due to miscellaneous problems, the following tools currently will not work with NetCoreDbg: clang-analyzer (scan-build), cpplint, cppcheck, and iwyu*.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamsung%2Fnetcoredbg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamsung%2Fnetcoredbg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamsung%2Fnetcoredbg/lists"}