path: root/Documentation
diff options
Diffstat (limited to 'Documentation')
2 files changed, 13 insertions, 212 deletions
diff --git a/Documentation/building/ b/Documentation/building/
deleted file mode 100644
index 5c4b775..0000000
--- a/Documentation/building/
+++ /dev/null
@@ -1,87 +0,0 @@
-Building LLDB
-1. Clone the llvm, clang, and lldb repos like this:
- llvm
- |
- `-- tools
- |
- +-- clang
- |
- `-- lldb
- ```
- cd $HOME
- git clone
- cd $HOME/llvm/tools
- git clone
- git clone
- ```
-2. Checkout the "release_39" branches in llvm/clang/lldb:
- ```
- cd $HOME/llvm
- git checkout release_39
- cd $HOME/llvm/tools/clang
- git checkout release_39
- cd $HOME/llvm/tools/lldb
- git checkout release_39
- ```
-3. Install the prerequisites:
- For Linux (Debian or Ubuntu):
- ```
- sudo apt-get install build-essential subversion swig python2.7-dev libedit-dev libncurses5-dev
- ```
- For OSX, the latest Xcode needs to be installed and I use Homebrew to install the rest:
- ```
- brew install python swig doxygen ocaml
- ```
- There may be more prerequisites required, when building the cmake files it should let
- you know if there are any I missed.
- See for more details on these preliminaries.
-4. If building on OSX, carefully following the signing directions (before you build)
- here: $HOME/llvm/tools/lldb/docs/code-signing.txt. Even though those build directions
- say to use Xcode to build lldb, I never got it to work, but cmake/make works.
-5. Building the cmake files (you can build either debug or release or both).
- For debug:
- ```
- mkdir -p $HOME/build/debug
- cd $HOME/build/debug
- cmake -DCMAKE_BUILD_TYPE=debug $HOME/llvm
- ```
- For release:
- ```
- mkdir -p $HOME/build/release
- cd $HOME/build/release
- cmake -DCMAKE_BUILD_TYPE=release $HOME/llvm
- ```
-6. Build lldb (release was picked in this example, but can be replaced with "debug"):
- ```
- cd $HOME/build/release/tools/lldb
- make -j16
- ```
- When you build with -j16 (parallel build with 16 jobs), sometimes it fails. Just start again with just make.
- For OS X, building in remote ssh shell won't sign properly, use a terminal window on the machine itself.
-7. To use the newly built lldb and to build the coreclr SOS plugin for it, set these environment variables in your .profile:
- ```
- export LLDB_INCLUDE_DIR=$HOME/llvm/tools/lldb/include
- export LLDB_LIB_DIR=$HOME/build/release/lib
- PATH=$HOME/build/release/bin:$PATH
- ```
- For OS X also set:
- ```
- export LLDB_DEBUGSERVER_PATH=$HOME/build/release/bin/debugserver
- ```
- It also seems to be necessary to run lldb as superuser e.g. `sudo -E $HOME/build/release/bin/lldb` (the -E is necessary so the above debug server environment variable is passed) if using a remote ssh, but it isn't necessary if run it in a local terminal session.
diff --git a/Documentation/building/ b/Documentation/building/
index 86468b6..f99b498 100644
--- a/Documentation/building/
+++ b/Documentation/building/
@@ -1,7 +1,9 @@
Debugging CoreCLR
-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.
+These instructions will lead you through debugging CoreCLR.
+SOS has moved to the diagnostics repo. For more information on SOS, installation and how to use it click [here](
Debugging CoreCLR on Windows
@@ -24,29 +26,25 @@ Steps 1-8 only need to be done once, and then (9) can be repeated whenever you w
### Using SOS with windbg or cdb on Windows ###
-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.
-For more information on SOS commands click [here](
+See the SOS installation instructions [here](
-Debugging CoreCLR on OS X
+For more information on SOS commands click [here](
-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]( The rest of instructions on how to use lldb for Linux on are the same.
+Debugging CoreCLR on Linux and macOS
-Debugging CoreCLR on Linux
+See the SOS installation instructions [here]( After SOS is installed, it will automatically be loaded by lldb.
-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.
+Only lldb is supported by SOS. Gdb can be used to debug the coreclr code but with no SOS support.
1. Perform a build of the coreclr repo.
2. Install the corefx managed assemblies to the binaries directory.
3. cd to build's binaries: `cd ~/coreclr/bin/Product/Linux.x64.Debug`
-4. Start lldb (the version the plugin was built with, currently 3.9): `lldb-3.9 corerun HelloWorld.exe linux`
-5. Now at the lldb command prompt, load SOS plugin: `plugin load`
+4. Start lldb: `lldb-3.9 corerun HelloWorld.exe linux`
6. Launch program: `process launch -s`
7. To stop annoying breaks on SIGUSR1/SIGUSR2 signals used by the runtime run: `process handle -s false SIGUSR1 SIGUSR2`
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.
-9. Run a SOS command like `sos ClrStack` or `sos VerifyHeap`. The command name is case sensitive.
+9. Run a SOS command like `clrstack` or `sos VerifyHeap`. The command name is case sensitive.
You can combine steps 4-8 and pass everything on the lldb command line:
@@ -56,120 +54,10 @@ For .NET Core version 1.x and 2.0.x, is built for and will only
**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.
-### SOS commands ###
-This is the full list of commands currently supported by SOS. lldb is case-sensitive, unlike windbg.
- Type "soshelp <functionname>" for detailed info on that function.
- Object Inspection Examining code and stacks
- ----------------------------- -----------------------------
- DumpObj (dumpobj) Threads (clrthreads)
- DumpArray ThreadState
- DumpStackObjects (dso) IP2MD (ip2md)
- DumpHeap (dumpheap) u (clru)
- DumpVC DumpStack (dumpstack)
- GCRoot (gcroot) EEStack (eestack)
- PrintException (pe) ClrStack (clrstack)
- GCInfo
- EHInfo
- bpmd (bpmd)
- Examining CLR data structures Diagnostic Utilities
- ----------------------------- -----------------------------
- DumpDomain VerifyHeap
- EEHeap (eeheap) FindAppDomain
- Name2EE (name2ee) DumpLog (dumplog)
- DumpMT (dumpmt) CreateDump (createdump)
- DumpClass (dumpclass)
- DumpMD (dumpmd)
- Token2EE
- DumpModule (dumpmodule)
- DumpAssembly
- DumpRuntimeTypes
- DumpIL (dumpil)
- DumpSig
- DumpSigElem
- Examining the GC history Other
- ----------------------------- -----------------------------
- HistInit (histinit) FAQ
- HistRoot (histroot) Help (soshelp)
- HistObj (histobj)
- HistObjFind (histobjfind)
- HistClear (histclear)
-### Aliases ###
-By default you can reach all the SOS commands by using: _sos [command\_name]_
-However the common commands have been aliased so that you don't need the SOS prefix:
- bpmd -> sos bpmd
- clrstack -> sos ClrStack
- clrthreads -> sos Threads
- clru -> sos U
- createdump -> sos CreateDump
- dso -> sos DumpStackObjects
- dumpclass -> sos DumpClass
- dumpheap -> sos DumpHeap
- dumpil -> sos DumpIL
- dumplog -> sos DumpLog
- dumpmd -> sos DumpMD
- dumpmodule -> sos DumpModule
- dumpmt -> sos DumpMT
- dumpobj -> sos DumpObj
- dumpstack -> sos DumpStack
- eeheap -> sos EEHeap
- eestack -> sos EEStack
- gcroot -> sos GCRoot
- histinit -> sos HistInit
- histroot -> sos HistRoot
- histobj -> sos HistObj
- histobjfind -> sos HistObjFind
- histclear -> sos HistClear
- ip2md -> sos IP2MD
- name2ee -> sos Name2EE
- pe -> sos PrintException
- soshelp -> sos Help
### Debugging core dumps with lldb
-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:
-- 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.
-- On Linux, there is a utility called `createdump` (see [doc]( that can be setup to generate core dumps when a managed app throws an unhandled exception or faults.
-- To get matching runtime and symbol binaries for the core dump use the symbol downloader CLI extension:
- - Install the [.NET Core 2.1 SDK](
- - 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 as a source.
- - Run `dotnet symbol coredump` to download the runtime binaries and symbols.
- - Check out the coreclr and corefx repositories at the appropriate commit for the appropriate source.
- - For further information see: [dotnet-symbol](
-- lldb version 3.9. The SOS plugin (i.e. provided is now built for lldb 3.9. In order to install lldb 3.9 just run the following commands:
-~$ echo "deb llvm-toolchain-trusty-3.9 main" | sudo tee /etc/apt/sources.list.d/llvm.list
-~$ wget -O - | sudo apt-key add -
-~$ sudo apt-get update
-~$ sudo apt-get install lldb-3.9
-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 Use a command like this:
-lldb-3.9 -O "settings set target.exec-search-paths <runtime-path>" -o "plugin load <>" --core <core-file-path> <host-path>
-- `<runtime-path>`: The path containing, as well as the rest of the runtime and framework assemblies.
-- `<core-file-path>`: The path to the core dump you are attempting to debug.
-- `<host-path>`: The path to the dotnet or corerun executable, potentially in the `<runtime-path>` folder.
-- `<>`: The path to, should be in the `<runtime-path>` folder.
-lldb should start debugging successfully at this point. You should see stack traces with resolved symbols for At this point, you can run `plugin load <>`, and begin using SOS commands, as above.
-##### Example
-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/" --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
+See this [link]( in the diagnostics repo.
Disabling Managed Attach/Debugging