-# Debugger for .NET Core runtime
+# Debugger for the .NET Core Runtime
-The debugger provides [GDB/MI](https://sourceware.org/gdb/onlinedocs/gdb/GDB_002fMI.html)
-and [VSCode Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)
-and allows to debug .NET apps under .NET Core runtime. Also debugger allows debugging from
-command line (like as GDB).
+The NetCoreDbg debugger implements [GDB/MI](https://sourceware.org/gdb/onlinedocs/gdb/GDB_002fMI.html)
+and [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).
## Copyright
-You can find licensing information in file [LICENSE](LICENSE), in root directory of Netcoredbg sources.
+You can find licensing information in the [LICENSE](LICENSE) file within the root directory of the NetCoreDbg sources.
## Usage
-More details about usage of NCDB you can find in [CLI](docs/cli.md) manual.
+Further details regarding the usage of NetCoreDbg can be found in the [CLI](docs/cli.md) manual.
## Installation
NetCoreDbg is available in repositories of some Linux distributions and Windows package manager:
For other Linux distributions you can use binaries provided in github releases (https://github.com/Samsung/netcoredbg/releases) or build from source code.
-## Building from source code
-
-Currently Netcoredbg can be built on Linux, MacOS or Windows. Instructions for building Netcoredbg on each platform is shown below.
+## Building from Source Code
+Currently, NetCoreDbg can be built on Linux, MacOS, or Windows. Instructions for building NetCoreDbg on each platform is shown below.
### Unix
-Building of Netcoredbg requires Microsoft's .NET, so currently you can build Netcoredbg only in Linux. Microsoft supports at least few distributions, see details here: https://docs.microsoft.com/en-us/dotnet/core/install/linux
+NetCoreDbg'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.
#### Prerequisites
-1. You need to install `cmake`, and `make` or `ninja`.
+1. You need to install `cmake`, and either `make` or `ninja`.
-2. You need clang C++ compiler installed (Netcoredbg can't be built with gcc).
+2. You need the clang C++ compiler installed (NetCoreDbg can't be built with gcc).
-3. Microsoft's **.NET runtime** should be installed, you can download it here: https://dotnet.microsoft.com/download
+3. Microsoft's **.NET runtime** should be installed, which you can download here: https://dotnet.microsoft.com/download.
-4. May be you need to install some typical developers tools not mentioned here, like `git`, etc...
+4. You may also need to install some common developers tools not mentioned here, such as [Git](https://www.git-scm.com/downloads), etc...
-5. It is expected, that Netcoredbg sources placed to some directory;
+5. It is expected that you place the NetCoreDbg sources within a directory.
-6. Optional step: Netcoredbg requires **CoreCLR runtime source code**, which is typically downloaded automatically, but you can download it from here: https://github.com/dotnet/runtime
+6. 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.
- For example, you can check out tag v8.x.
+ *For example, you can check out tag v8.x.*
-7. Optional step: Netcoredbg requires **.NET SDK**, which can be downloaded automatically, but you can download it manually from here: https://dotnet.microsoft.com/download
+7. 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.
#### Compiling
-Configure build with the following commands:
+Configure the build with the following commands:
```
user@netcoredbg$ mkdir build
user@build$ CC=clang CXX=clang++ cmake ..
```
-For running tests after build has succeed you need to add option `-DCMAKE_INSTALL_PREFIX=$PWD/../bin`.
+In order to run tests after a successful build, you need to add the option `-DCMAKE_INSTALL_PREFIX=$PWD/../bin`.
-To enable the Source-based code coverage feature (https://clang.llvm.org/docs/SourceBasedCodeCoverage.html)
-add `-DCLR_CMAKE_ENABLE_CODE_COVERAGE` option.
+To enable the Source-Based Code Coverage feature (https://clang.llvm.org/docs/SourceBasedCodeCoverage.html),
+add the `-DCLR_CMAKE_ENABLE_CODE_COVERAGE` option.
-If you have previously downloaded .NET SDK or CoreCLR sources, then you should modify command line and add following options: `-DDOTNET_DIR=/path/to/sdk/dir -DCORECLR_DIR=/path/to/coreclr/sources`
+If you have previously downloaded the .NET SDK or CoreCLR sources, then you should modify the command line by adding the following options:
+`-DDOTNET_DIR=/path/to/sdk/dir -DCORECLR_DIR=/path/to/coreclr/sources`.
-If cmake tries to download .NET SDK or CoreCLR sources and fails -- see bullets 6 and 7 above. You can download required files manually.
+If 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*.
-After configuration has finished, you can build Netcoredbg:
+After configuration has finished, you can then build NetCoreDbg:
```
user@netcoredbg$ make
user@netcoredbg$ make install
```
-To perform build from scratch (including configuration step) again you should delete artefacts with following commands:
+To perform a build from scratch, including the configuration step, you should again delete any artifacts with the following commands:
```
user@build$ cd ..
user@netcoredbg$ rm -rf build src/debug/netcoredbg/bin bin
```
-> *Directory `bin` contains "installed" Netcoredbg's binaries for tests. If you have installed Netcoredbg in other place, for example in `/usr/local/bin`, you should remove it manually: currently Netcoredbg's build system doesn't performs "uninstalling".*
+> *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.*
-#### Prerequisites and compiling with interop mode support (Linux and Tizen OSes only)
-Prerequisites and compiling process are the same as above with following changes:
+#### Prerequisites and Compiling with Interop Mode Support (Linux and Tizen OSes only)
+The prerequisites and compiling process are the same as the aforementioned with the following changes:
-1. You need to install `libunwind-dev` or `libunwind-devel` package, depends on your distro.
+1. Depending on your distro, you need to install either the `libunwind-dev` or `libunwind-devel` packages.
-2. Configure build with the following commands:
+2. Configure the build with the following commands:
```
user@build$ CC=clang CXX=clang++ cmake .. -DINTEROP_DEBUGGING=1
```
-More details about usage of NCDB you can find in [Interop mode](docs/interop.md).
+To find more details on the usage of NetCoreDbg in Interop Mode, please see the guide doc: [Interop Mode](docs/interop.md).
### MacOS
-You need install homebrew from here: https://brew.sh/
-
-After this, build instructions are same as for Unix (including prerequisites).
+You need to install homebrew from here: https://brew.sh/
-**Note: MacOS arm64 build (M1) is community supported and may not work as expected, plus some tests might fail.**
+After this, the build instructions are the same as for Unix, including the prerequisites.
+*Note: the MacOS arm64 build (M1) is community supported and may not work as expected, as well as some tests possibly failing.*
### Windows
1. Download and install **CMake** from here: https://cmake.org/download
-2. Download and install **Microsoft's Visual Studio 2019** or newer: https://visualstudio.microsoft.com/downloads
+2. Download and install **Microsoft's Visual Studio 2019** or newer from here: https://visualstudio.microsoft.com/downloads
- During installation of Visual Studio you should install all options required
- for C# and C++ development on windows.
+ *During installation of Visual Studio you should install all of the options required
+ for C# and C++ development on Windows*.
-3. Download and install **Git**, you have few options here:
+3. Download and install **Git**; you have a few options here:
* use original Git: https://git-scm.com/download/win
* use TortoiseGit: https://tortoisegit.org/download
* or use git installed in cygwin: https://cygwin.com/install.html
-4. Checkout Netcoredbg sources to some directory by using git.
-
+4. Utilize Git to place NetCoreDbg sources in a directory.
-5. This step might be omitted, in this case cmake automatically downloads necessary files.
- But if it fails, you should then checkout **CoreCLR sources** to another directory from here: https://github.com/dotnet/runtime
+5. This step may be omitted, and in that case, cmake will automatically download all necessary files.
+ But if it fails, you then need to manually download the **CoreCLR sources** into another directory from here: https://github.com/dotnet/runtime.
- For example, you can use latest tag **v8.x**.
+ *For example, you can use the latest tag **v8.x***.
-6. This step might be omitted too, and cmake will automatically downloads that it needs.
- But in case of failure you need download and install **.NET SDK** from here: https://dotnet.microsoft.com/download
+6. This step may also be omitted, and in that case, cmake will automatically download all necessary files.
+ But if it fails, you then need to manually download and install the **.NET SDK** from here: https://dotnet.microsoft.com/download
#### Compiling
-Configure the build with the following commands given in Netcoredbg's source tree:
+Configure the build with the following commands given in NetCoreDbg's source tree:
```
C:\Users\localuser\netcoredbg> md build
C:\Users\localuser\netcoredbg\build> cmake .. -G "Visual Studio 16 2019"
```
-You should run this command from cmd.exe, *not from cygwin's shell*.
+*Note: You should run this command from cmd.exe, **not from cygwin's shell***.
Option `-G` specifies which instance of Visual Studio should build the project.
-Note, minimum requirements for netcoredbg build is `Visual Studio 2019` version.
+Note, the minimum requirements for NetCoreDbg's build is the **Visual Studio 2019** version.
+If you want to run tests after a successful build, then you should add the following option: `-DCMAKE_INSTALL_PREFIX="%cd%\..\bin"`.
-If you want to run tests after build succeed, you should add following option: `-DCMAKE_INSTALL_PREFIX="%cd%\..\bin"`
-
-If you have downloaded .NET SDK or .NET Core sources manually, you should add following options:
+If you have downloaded either the .NET SDK or .NET Core sources manually, you should add the following options:
`-DDOTNET_DIR="c:\Program Files\dotnet" -DCORECLR_DIR="path\to\coreclr"`
-
-To compile and install give command:
+To compile and install, use the following command:
```
C:\Users\localuser\netcoredbg\build> cmake --build . --target install
```
-
-To perform build from scratch (including configuration step) again you should delete artefacts with following commands:
+To perform a build from scratch, including the configuration step, you should again delete any artifacts by using the following commands:
```
C:\Users\localuser\netcoredbg\build>cd ..
C:\Users\localuser\netcoredbg>rmdir /s /q build src\debug\netcoredbg\bin bin
```
-> *Directory `bin` contains "installed" Netcoredbg's binaries for tests. If you have installed Netcoredbg in other place, you should remove it manually: currently Netcoredbg's build system doesn't performs "uninstalling".*
+> *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.*
+## Running NetCoreDbg
+In the instructions provided above, the `netcoredbg` binary and additional libraries will be installed in some directory.
+For development purposes (for running tests, debugging, etc...), the directory `bin` in NetCoreDbg's source tree is typically used.
-## Running Netcoredbg
-
-In instructions shown above `netcoredbg` binary and additional libraries will be installed in some directory.
-For developing purposes (for running tests, debugging, etc...) directory `bin` in Netcoredbg's source tree is typically used.
-
-Now running the debugger with `--help` option should look like this:
+Now, running the debugger with the `--help` option should look like this:
```
$ ../bin/netcoredbg --help
```
-Basically, to debug .NET code you should run Netcoredbg with the following command line:
+Basically, to debug .NET code, you should run NetCoreDbg with the following command line:
+
```
$ /path/to/netcoredbg --interpreter=TYPE -- /path/to/dotnet /path/to/program.dll
```
-## Notes for developers
+## Notes for Developers
-### Running the tests
+### Running the Tests
-You can find detailed instruction how to run tests in `test-suite` directory, see [test-suite/README.md](test-suite/README.md).
-Basically you just need to build and install Netcoredbg into `bin` directory (in Netcoredbg source tree) and then change directory to `test-suite` and run script `/run_tests.sh`
+Detailed instructions on how to run tests can be found in the `test-suite` directory here: [test-suite/README.md](test-suite/README.md).
+You 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`.
-If you wish to get "Source-based code coverage" report, you can add an -c or --coverage option to the command line, i.e.:
-`./run_tests.sh -c [[testname1][testname2]..]`
-Note, for that case your build configuration should be done with `-DCLR_CMAKE_ENABLE_CODE_COVERAGE` option (see above). This feature is currently supported on Unix-like platforms only.
+If you wish to get the "Source-Based Code Coverage" report, you can add a `-c` or `--coverage` option to the command line, i.e.:
+`./run_tests.sh -c [[testname1][testname2]..]`.
+Please 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*.
-### Building and running unit tests
+### Building and Running Unit Tests
-To build unit tests you need to add following option to CMake: `-DBUILD_TESTING=ON`.
+In order to build unit tests, you need to add the following option to CMake: `-DBUILD_TESTING=ON`.
-After the build, you can run unit tests by the command: `make test`.
+After a successful build, you may then run unit tests by running the command: `make test`.
-See details in [src/unittests/README.md](src/unittests/README.md).
+Please see details here: [src/unittests/README.md](src/unittests/README.md).
+### Enabling Logs
-### Enabling logs
-
-On Tizen platform Netcoredbg will send logs to the system logger. On other platforms you should specify the file to which logs will be written. This can be done by setting environment variable, example:
+On 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:
```
-export LOG_OUTPUT=/tmp/log.txt
+export LOG_OUTPUT=/tmp/log.txt
```
-Each line of the log lines has same format which is described below:
+Each line of the log file utilizes the same format which is explained below:
```
5280715.183 D/NETCOREDBG(P12036, T12036): cliprotocol.cpp: evalCommands(1309) > evaluating: 'source file.txt'
^ ^ ^ ^ ^ ^ ^ ^ ^
`--- This is time in seconds from the boot time (might be wrapped around).
```
+### Selecting between Debug and Release Builds
-### Selecting between Debug and Release builds
-
-You can select build type by providing one of the following options for CMake:
-
- * ` -DCMAKE_BUILD_TYPE=Debug ` for debug build (no optimizations, suitable for debugging);
+You can select the build type by providing one of the following options for CMake:
- * ` -DCMAKE_BUILD_TYPE=Release ` for release builds (optimized, hard to debug).
+ * ` -DCMAKE_BUILD_TYPE=Debug ` for a debug build (contains zero optimizations, but is suitable for debugging);
-By default build system create release builds.
+ * ` -DCMAKE_BUILD_TYPE=Release ` for a release build (optimized, but difficult to debug).
+By default, NetCoreDbg's build system creates release builds.
-### Using address sanitizer
+### Using the Address Sanitizer
Example:
```
CC=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
```
+### Using Clang-Tidy
-### Using clang-tidy
+First, Install clang-10.
-Install clang-10. To use clang-tidy modify command used to configure the build:
+Next, to use clang-tidy, modify the commands used to configure the build as below:
```
CC=clang-10 CXX=clang++-10 cmake .. . -DCMAKE_CXX_CLANG_TIDY=clang-tidy-10 -DCMAKE_INSTALL_PREFIX=$PWD/../bin
```
-Then just run `make`. All errors will be printed to stderr.
+Then just run `make`. Any and all errors will be printed to stderr.
See details here: https://blog.kitware.com/static-checks-with-cmake-cdash-iwyu-clang-tidy-lwyu-cpplint-and-cppcheck/
-Note: clang-analyzer (scan-build), cpplint, cppcheck, iwyu -- these tools currently will not work with Netcoredbg sources due to miscellaneous problems.
+*Note: Due to miscellaneous problems, the following tools currently will not work with NetCoreDbg: clang-analyzer (scan-build), cpplint, cppcheck, and iwyu*.
projects / sdk / tools / netcoredbg.git / commitdiff