Documentation/building/debugging-instructions.md

   1 Debugging CoreCLR
   2 =================
   3
   4 These instructions will lead you through debugging CoreCLR on Windows and Linux. They will be expanded to support macOS when we have good instructions for that.
   5
   6 Debugging CoreCLR on Windows
   7 ============================
   8
   9 1. Perform a build of the repo.
  10 2. Open solution \<reporoot\>\bin\obj\Windows_NT.\<platform\>.\<configuration\>\CoreCLR.sln in Visual Studio. \<platform\> and \<configuration\> are based
  11     on type of build you did. By default they are 'x64' and 'Debug'.
  12 3. Right-click the INSTALL project and choose ‘Set as StartUp Project’
  13 4. Bring up the properties page for the INSTALL project
  14 5. Select Configuration Properties->Debugging from the left side tree control
  15 6. Set Command=`$(SolutionDir)..\..\product\Windows_NT.$(Platform).$(Configuration)\corerun.exe`
  16     1. This points to the folder where the built runtime binaries are present.
  17 7. Set Command Arguments=`<managed app you wish to run>` (e.g. HelloWorld.exe)
  18 8. Set Working Directory=`$(SolutionDir)..\..\product\Windows_NT.$(Platform).$(Configuration)`
  19     1. This points to the folder containing CoreCLR binaries.
  20 9. Press F11 to start debugging at wmain in corerun (or set a breakpoint in source and press F5 to run to it)
  21     1. As an example, set a breakpoint for the EEStartup function in ceemain.cpp to break into CoreCLR startup.
  22
  23 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.
  24
  25 ### Using SOS with windbg or cdb on Windows ###
  26
  27 If you know the path of the `sos.dll` for the version of your runtime, load it like `.load c:\path\to\sos\sos.dll`. Use can use the `lm` command to find the path of the "coreclr.dll" module. `.loadby sos coreclr` should also work.
  28
  29 For more information on SOS commands click [here](https://msdn.microsoft.com/en-us/library/bb190764(v=vs.110).aspx).
  30
  31 Debugging CoreCLR on OS X
  32 ==========================
  33
  34 To use lldb on OS X, you first need to build it and the SOS plugin on the machine you intend to use it. See the instructions in [building lldb](buildinglldb.md). The rest of instructions on how to use lldb for Linux on are the same.
  35
  36 Debugging CoreCLR on Linux
  37 ==========================
  38
  39 Only lldb is supported by the SOS plugin. gdb can be used to debug the coreclr code but with no SOS support. Visual Studio 2015 RTM remote debugging isn't currently supported.
  40
  41 1. Perform a build of the coreclr repo.
  42 2. Install the corefx managed assemblies to the binaries directory.
  43 3. cd to build's binaries: `cd ~/coreclr/bin/Product/Linux.x64.Debug`
  44 4. Start lldb (the version the plugin was built with, currently 3.9): `lldb-3.9 corerun HelloWorld.exe linux`
  45 5. Now at the lldb command prompt, load SOS plugin: `plugin load libsosplugin.so`
  46 6. Launch program: `process launch -s`
  47 7. To stop annoying breaks on SIGUSR1/SIGUSR2 signals used by the runtime run: `process handle -s false SIGUSR1 SIGUSR2`
  48 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.
  49 9. Run a SOS command like `sos ClrStack` or `sos VerifyHeap`.  The command name is case sensitive.
  50
  51 You can combine steps 4-8 and pass everything on the lldb command line:
  52
  53 `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`
  54
  55 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.
  56
  57 ### SOS commands ###
  58
  59 This is the full list of commands currently supported by SOS. lldb is case-sensitive, unlike windbg.
  60
  61     Type "soshelp <functionname>" for detailed info on that function.
  62
  63     Object Inspection                  Examining code and stacks
  64     -----------------------------      -----------------------------
  65     DumpObj (dumpobj)                  Threads (clrthreads)
  66     DumpArray                          ThreadState
  67     DumpStackObjects (dso)             IP2MD (ip2md)
  68     DumpHeap (dumpheap)                u (clru)
  69     DumpVC                             DumpStack (dumpstack)
  70     GCRoot (gcroot)                    EEStack (eestack)
  71     PrintException (pe)                ClrStack (clrstack)
  72                                        GCInfo
  73                                        EHInfo
  74                                        bpmd (bpmd)
  75
  76     Examining CLR data structures      Diagnostic Utilities
  77     -----------------------------      -----------------------------
  78     DumpDomain                         VerifyHeap
  79     EEHeap (eeheap)                    FindAppDomain
  80     Name2EE (name2ee)                  DumpLog (dumplog)
  81     DumpMT (dumpmt)                    CreateDump (createdump)
  82     DumpClass (dumpclass)
  83     DumpMD (dumpmd)
  84     Token2EE
  85     DumpModule (dumpmodule)
  86     DumpAssembly
  87     DumpRuntimeTypes
  88     DumpIL (dumpil)
  89     DumpSig
  90     DumpSigElem
  91
  92     Examining the GC history           Other
  93     -----------------------------      -----------------------------
  94     HistInit (histinit)                FAQ
  95     HistRoot (histroot)                Help (soshelp)
  96     HistObj  (histobj)
  97     HistObjFind (histobjfind)
  98     HistClear (histclear)
  99
 100 ### Aliases ###
 101
 102 By default you can reach all the SOS commands by using: _sos [command\_name]_
 103 However the common commands have been aliased so that you don't need the SOS prefix:
 104
 105     bpmd            -> sos bpmd
 106     clrstack        -> sos ClrStack
 107     clrthreads      -> sos Threads
 108     clru            -> sos U
 109     createdump      -> sos CreateDump
 110     dso             -> sos DumpStackObjects
 111     dumpclass       -> sos DumpClass
 112     dumpheap        -> sos DumpHeap
 113     dumpil          -> sos DumpIL
 114     dumplog         -> sos DumpLog
 115     dumpmd          -> sos DumpMD
 116     dumpmodule      -> sos DumpModule
 117     dumpmt          -> sos DumpMT
 118     dumpobj         -> sos DumpObj
 119     dumpstack       -> sos DumpStack
 120     eeheap          -> sos EEHeap
 121     eestack         -> sos EEStack
 122     gcroot          -> sos GCRoot
 123     histinit        -> sos HistInit
 124     histroot        -> sos HistRoot
 125     histobj         -> sos HistObj
 126     histobjfind     -> sos HistObjFind
 127     histclear       -> sos HistClear
 128     ip2md           -> sos IP2MD
 129     name2ee         -> sos Name2EE
 130     pe              -> sos PrintException
 131     soshelp         -> sos Help
 132
 133 ### Debugging core dumps with lldb
 134
 135 It is also possible to debug .NET Core crash dumps using lldb and SOS. In order to do this, you need all of the following:
 136
 137 - The crash dump file. We have a service called "Dumpling" which collects, uploads, and archives crash dump files during all of our CI jobs and official builds.
 138 - On Linux, there is a utility called `createdump` (see [doc](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md#configurationpolicy)) that can be setup to generate core dumps when a managed app throws an unhandled exception or faults.
 139 - To get matching runtime and symbol binaries for the core dump use the symbol downloader CLI extension:
 140   - Install the [.NET Core 2.1 SDK](https://www.microsoft.com/net/download/).
 141   - Install the symbol downloader extension: `dotnet tool install -g dotnet-symbol`. Make sure you are not in any project directory with a NuGet.Config that doesn't include nuget.org as a source.
 142   - Run `dotnet symbol coredump` to download the runtime binaries and symbols.
 143   - Check out the coreclr and corefx repositories at the appropriate commit for the appropriate source.
 144   - For further information see: [dotnet-symbol](https://github.com/dotnet/symstore/blob/master/src/dotnet-symbol/README.md).
 145 - lldb version 3.9. The SOS plugin (i.e. libsosplugin.so) provided is now built for lldb 3.9. In order to install lldb 3.9 just run the following commands:
 146 ```
 147 ~$ echo "deb http://llvm.org/apt/trusty/ llvm-toolchain-trusty-3.9 main" | sudo tee /etc/apt/sources.list.d/llvm.list
 148 ~$ wget -O - http://llvm.org/apt/llvm-snapshot.gpg.key | sudo apt-key add -
 149 ~$ sudo apt-get update
 150 ~$ sudo apt-get install lldb-3.9
 151 ```
 152
 153 Once you have everything listed above, you are ready to start debugging. You need to specify an extra parameter to lldb in order for it to correctly resolve the symbols for libcoreclr.so. Use a command like this:
 154
 155 ```
 156 lldb-3.9 -O "settings set target.exec-search-paths <runtime-path>" -o "plugin load <path-to-libsosplugin.so>" --core <core-file-path> <host-path>
 157 ```
 158
 159 - `<runtime-path>`: The path containing libcoreclr.so.dbg, as well as the rest of the runtime and framework assemblies.
 160 - `<core-file-path>`: The path to the core dump you are attempting to debug.
 161 - `<host-path>`: The path to the dotnet or corerun executable, potentially in the `<runtime-path>` folder.
 162 - `<path-to-libsosplugin.so>`: The path to libsosplugin.so, should be in the `<runtime-path>` folder.
 163
 164 lldb should start debugging successfully at this point. You should see stack traces with resolved symbols for libcoreclr.so. At this point, you can run `plugin load <libsosplugin.so-path>`, and begin using SOS commands, as above.
 165
 166 ##### Example
 167
 168 ```
 169 lldb-3.9 -O "settings set target.exec-search-paths /home/parallels/Downloads/System.Drawing.Common.Tests/home/helixbot/dotnetbuild/work/2a74cf82-3018-4e08-9e9a-744bb492869e/Payload/shared/Microsoft.NETCore.App/9.9.9/" -o "plugin load /home/parallels/Downloads/System.Drawing.Common.Tests/home/helixbot/dotnetbuild/work/2a74cf82-3018-4e08-9e9a-744bb492869e/Payload/shared/Microsoft.NETCore.App/9.9.9/libsosplugin.so" --core /home/parallels/Downloads/System.Drawing.Common.Tests/home/helixbot/dotnetbuild/work/2a74cf82-3018-4e08-9e9a-744bb492869e/Work/f6414a62-9b41-4144-baed-756321e3e075/Unzip/core /home/parallels/Downloads/System.Drawing.Common.Tests/home/helixbot/dotnetbuild/work/2a74cf82-3018-4e08-9e9a-744bb492869e/Payload/shared/Microsoft.NETCore.App/9.9.9/dotnet
 170 ```
 171 Disabling Managed Attach/Debugging
 172 ==================================
 173
 174 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.
 175
 176     export COMPlus_EnableDiagnostics=0
 177
 178
 179 Using Visual Studio Code
 180 ========================
 181
 182 - Install [Visual Studio Code](https://code.visualstudio.com/)
 183 - Install the [C# Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp)
 184 - Open the folder containing the source you want to debug in VS Code
 185 - Open the debug window: `ctrl-shift-D` or click on the button on the left
 186 - Click the gear button at the top to create a launch configuration, select `.NET Core` from the selection dropdown
 187 - In the `.NET Core Launch (console)` configuration do the following
 188   - delete the `preLaunchTask` property
 189   - set `program` to the full path to corerun in the test directory
 190   - set `cwd` to the test directory
 191   - set `args` to the command line arguments to pass to the test
 192     - something like: `[ "xunit.console.netcore.exe", "<test>.dll", "-notrait", .... ]`
 193 - Set a breakpoint and launch the debugger, inspecting variables and call stacks will now work