Documentation/building/debugging-instructions.md

   1 Debugging CoreCLR
   2 =================
   3
   4 These instructions will lead you through debugging CoreCLR.
   5
   6 SOS has moved to the diagnostics repo. For more information on SOS, installation and how to use it click [here](https://github.com/dotnet/diagnostics#net-core-diagnostics-repo).
   7
   8 Debugging CoreCLR on Windows
   9 ============================
  10
  11 1. Perform a build of the repo.
  12 2. Open solution \<reporoot\>\bin\obj\Windows_NT.\<platform\>.\<configuration\>\CoreCLR.sln in Visual Studio. \<platform\> and \<configuration\> are based
  13     on type of build you did. By default they are 'x64' and 'Debug'.
  14 3. Right-click the INSTALL project and choose ‘Set as StartUp Project’
  15 4. Bring up the properties page for the INSTALL project
  16 5. Select Configuration Properties->Debugging from the left side tree control
  17 6. Set Command=`$(SolutionDir)..\..\product\Windows_NT.$(Platform).$(Configuration)\corerun.exe`
  18     1. This points to the folder where the built runtime binaries are present.
  19 7. Set Command Arguments=`<managed app you wish to run>` (e.g. HelloWorld.exe)
  20 8. Set Working Directory=`$(SolutionDir)..\..\product\Windows_NT.$(Platform).$(Configuration)`
  21     1. This points to the folder containing CoreCLR binaries.
  22 9. Press F11 to start debugging at wmain in corerun (or set a breakpoint in source and press F5 to run to it)
  23     1. As an example, set a breakpoint for the EEStartup function in ceemain.cpp to break into CoreCLR startup.
  24
  25 Steps 1-8 only need to be done once, and then (9) can be repeated whenever you want to start debugging. The above can be done with Visual Studio 2013.
  26
  27 ### Using SOS with windbg or cdb on Windows ###
  28
  29 See the SOS installation instructions [here](https://github.com/dotnet/diagnostics/blob/master/documentation/installing-sos-windows-instructions.md).
  30
  31 For more information on SOS commands click [here](https://github.com/dotnet/diagnostics/blob/master/documentation/sos-debugging-extension-windows.md).
  32
  33 Debugging CoreCLR on Linux and macOS
  34 ====================================
  35
  36 See the SOS installation instructions [here](https://github.com/dotnet/diagnostics/blob/master/documentation/installing-sos-instructions.md). After SOS is installed, it will automatically be loaded by lldb.
  37
  38 Only lldb is supported by SOS. Gdb can be used to debug the coreclr code but with no SOS support.
  39
  40 1. Perform a build of the coreclr repo.
  41 2. Install the corefx managed assemblies to the binaries directory.
  42 3. cd to build's binaries: `cd ~/coreclr/bin/Product/Linux.x64.Debug`
  43 4. Start lldb: `lldb-3.9 corerun HelloWorld.exe linux`
  44 6. Launch program: `process launch -s`
  45 7. To stop annoying breaks on SIGUSR1/SIGUSR2 signals used by the runtime run: `process handle -s false SIGUSR1 SIGUSR2`
  46 8. Get to a point where coreclr is initialized by setting a breakpoint (i.e. `breakpoint set -n LoadLibraryExW` and then `process continue`) or stepping into the runtime.
  47 9. Run a SOS command like `clrstack` or `sos VerifyHeap`.  The command name is case sensitive.
  48
  49 You can combine steps 4-8 and pass everything on the lldb command line:
  50
  51 `lldb-3.9 -o "plugin load libsosplugin.so" -o "process launch -s" -o "process handle -s false SIGUSR1 SIGUSR2" -o "breakpoint set -n LoadLibraryExW" corerun HelloWorld.exe linux`
  52
  53 For .NET Core version 1.x and 2.0.x, libsosplugin.so is built for and will only work with version 3.6 of lldb. For .NET Core 2.1, the plugin is built for 3.9 lldb and will work with 3.8 and 3.9 lldb.
  54
  55 **Note:** _corerun_ is a simple host that does not support resolving NuGet dependencies. It relies on libraries being locatable via the `CORE_LIBRARIES` environment variable or present in the same directory as the corerun executable. The instructions above are equally applicable to the _dotnet_ host, however - e.g. for step 4 `lldb-3.9 dotnet bin/Debug/netcoreapp2.1/MvcApplication.dll` will let you debug _MvcApplication_ in the same manner.
  56
  57 ### Debugging core dumps with lldb
  58
  59 See this [link](https://github.com/dotnet/diagnostics/blob/master/documentation/debugging-coredump.md) in the diagnostics repo.
  60
  61 Disabling Managed Attach/Debugging
  62 ==================================
  63
  64 The "COMPlus_EnableDiagnostics" environment variable can be used to disable managed debugging. This prevents the various OS artifacts used for debugging like the named pipes and semaphores on Linux/MacOS and shared memory on Windows from being created.
  65
  66     export COMPlus_EnableDiagnostics=0
  67
  68
  69 Using Visual Studio Code
  70 ========================
  71
  72 - Install [Visual Studio Code](https://code.visualstudio.com/)
  73 - Install the [C# Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp)
  74 - Open the folder containing the source you want to debug in VS Code
  75 - Open the debug window: `ctrl-shift-D` or click on the button on the left
  76 - Click the gear button at the top to create a launch configuration, select `.NET Core` from the selection dropdown
  77 - In the `.NET Core Launch (console)` configuration do the following
  78   - delete the `preLaunchTask` property
  79   - set `program` to the full path to corerun in the test directory
  80   - set `cwd` to the test directory
  81   - set `args` to the command line arguments to pass to the test
  82     - something like: `[ "xunit.console.netcore.exe", "<test>.dll", "-notrait", .... ]`
  83 - Set a breakpoint and launch the debugger, inspecting variables and call stacks will now work
  84
  85 Using Visual Studio
  86 ===================
  87
  88 - Install [Visual Studio](https://visualstudio.microsoft.com/vs/)
  89 - Use File->Open Project (not open file) and select the binary you want to use as your host (typically dotnet.exe or corerun.exe)
  90 - Open the project properties for the new project that was just created and set:
  91   - Arguments: Make this match whatever arguments you would have used at the command-line. For example if you would have run "dotnet.exe exec Foo.dll", then set arguments = "exec Foo.dll"
  92       (Note: you probably want 'dotnet exec' rather than 'dotnet run' because the run verb is implemented to launch the app in a child-process and the debugger won't be attached to that child process)
  93   - Working Directory: Make this match whatever you would have used on the command-line
  94   - Debugger Type: Set this to either 'Managed (CoreCLR)' or 'Native Only' depending on whether you want to debug the C+ or native code respectively.
  95   - Environment: Add any environment variables you would have added at the command-line. You may also consider adding COMPLUS_ZapDisable=1 and COMPLUS_ReadyToRun=0 which disable NGEN and R2R pre-compilation respectively and allow the JIT to create debuggable code. This will give you a higher quality C# debugging experience inside the runtime framework assemblies, at the cost of somewhat lower app performance.
  96 - For managed debugging, there are some settings in Debug->Options, Debugging->General that might be useful:
  97   - Uncheck 'Just My Code'. This will allow you debug into the framework libraries.
  98   - Check 'Enable .NET Framework Source Stepping.' This will configure the debugger to download symbols and source automatically for runtime framework binaries. If you built the framework yourself this may be irrelevant because you already have all the source on your machine but it doesn't hurt.
  99   - Check 'Suppress JIT optimzation on module load'. This tells the debugger to tell the .NET runtime JIT to generate debuggable code even for modules that may not have been compiled in a 'Debug' configuration by the C# compiler. This code is slower, but it provides much higher fidelity breakpoints, stepping, and local variable access. It is the same difference you see when debugging .NET apps in the 'Debug' project configuration vs. the 'Release' project configuration.