--- /dev/null
+Building LLDB
+=============
+
+1. Clone the llvm, clang, and lldb repos like this:
+
+ llvm
+ |
+ `-- tools
+ |
+ +-- clang
+ |
+ `-- lldb
+
+ ```
+ cd $HOME
+ git clone http://llvm.org/git/llvm.git
+ cd $HOME/llvm/tools
+ git clone http://llvm.org/git/clang.git
+ git clone http://llvm.org/git/lldb.git
+ ```
+
+2. Checkout the "release_38" branches in llvm/clang/lldb:
+
+ ```
+ cd $HOME/llvm
+ git checkout release_38
+ cd $HOME/llvm/tools/clang
+ git checkout release_38
+ cd $HOME/llvm/tools/lldb
+ git checkout release_38
+ ```
+
+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 http://lldb.llvm.org/build.html 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.
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.
+Debugging CoreCLR on OS X
+==========================
+
+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.
+
Debugging CoreCLR on Linux
==========================
-Currently 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 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.
1. Perform a build of the coreclr repo.
2. Install the corefx managed assemblies to the binaries directory.
DumpSig
DumpSigElem
- Other
- -----------------------------
- FAQ
- Help (soshelp)
+ 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
dso -> sos DumpStackObjects
- dumpclass -> sos DumpClass
- dumpheap -> sos DumpHeap
+ dumpclass -> sos DumpClass
+ dumpheap -> sos DumpHeap
dumpil -> sos DumpIL
dumplog -> sos DumpLog
dumpmd -> sos DumpMD
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
-### Problems and limitations of lldb and sos ###
+### Problems and limitations of lldb and SOS ###
-Many of the sos commands like clrstack or dso don't work on core dumps because lldb doesn't
+Many of the SOS commands like clrstack or dso don't work on core dumps because lldb doesn't
return the actual OS thread id for a native thread. The "setsostid" command can be used to work
around this lldb bug. Use the "clrthreads" to find the os tid and the lldb command "thread list"
to find the thread index (#1 for example) for the current thread (* in first column). The first
The "gcroot" command either crashes lldb 3.6 or returns invalid results. Works fine with lldb 3.7 and 3.8.
-Loading Linux core dumps with lldb 3.7 doesn't work. lldb 3.7 loads OSX and FreeBSD core dumps
+Loading Linux core dumps with lldb 3.7 doesn't work. lldb 3.7 loads OS X and FreeBSD core dumps
just fine. lldb 3.8 loads all the platform's core dumps without problem.
For more information on SOS commands see: https://msdn.microsoft.com/en-us/library/bb190764(v=vs.110).aspx
DumpSig
DumpSigElem
-Other
------------------------------
-FAQ
-Help (soshelp)
+Examining the GC history Other
+----------------------------- -----------------------------
+HistInit (histinit) FAQ
+HistRoot (histroot) Help (soshelp)
+HistObj (histobj)
+HistObjFind (histobjfind)
+HistClear (histclear)
\\
COMMAND: faq.
call those when an AppDomain shuts down.
\\
+COMMAND: histinit.
+HistInit
+
+Before running any of the Hist - family commands you need to initialize the SOS
+structures from the stress log saved in the debuggee. This is achieved by the
+HistInit command.
+
+Sample output:
+
+ (lldb) histinit
+ Attempting to read Stress log
+ STRESS LOG:
+ facilitiesToLog = 0xffffffff
+ levelToLog = 6
+ MaxLogSizePerThread = 0x10000 (65536)
+ MaxTotalLogSize = 0x1000000 (16777216)
+ CurrentTotalLogChunk = 9
+ ThreadsWithLogs = 3
+ Clock frequency = 3.392 GHz
+ Start time 15:26:31
+ Last message time 15:26:56
+ Total elapsed time 25.077 sec
+ .....................................
+ ---------------------------- 2407 total entries -----------------------------
+
+
+ SUCCESS: GCHist structures initialized
+
+\\
+
+COMMAND: histobjfind.
+HistObjFind <obj_address>
+
+To examine log entries related to an object whose present address is known one
+would use this command. The output of this command contains all entries that
+reference the object:
+
+ (lldb) histobjfind 028970d4
+ GCCount Object Message
+ ---------------------------------------------------------
+ 2296 028970d4 Promotion for root 01e411b8 (MT = 5b6c5cd8)
+ 2296 028970d4 Relocation NEWVALUE for root 00223fc4
+ 2296 028970d4 Relocation NEWVALUE for root 01e411b8
+ ...
+ 2295 028970d4 Promotion for root 01e411b8 (MT = 5b6c5cd8)
+ 2295 028970d4 Relocation NEWVALUE for root 00223fc4
+ 2295 028970d4 Relocation NEWVALUE for root 01e411b8
+ ...
+
+\\
+
+COMMAND: histroot.
+HistRoot <root>
+
+The root value obtained from !HistObjFind can be used to track the movement of
+an object through the GCs.
+
+HistRoot provides information related to both promotions and relocations of the
+root specified as the argument.
+
+ (lldb) histroot 01e411b8
+ GCCount Value MT Promoted? Notes
+ ---------------------------------------------------------
+ 2296 028970d4 5b6c5cd8 yes
+ 2295 028970d4 5b6c5cd8 yes
+ 2294 028970d4 5b6c5cd8 yes
+ 2293 028970d4 5b6c5cd8 yes
+ 2292 028970d4 5b6c5cd8 yes
+ 2291 028970d4 5b6c5cd8 yes
+ 2290 028970d4 5b6c5cd8 yes
+ 2289 028970d4 5b6c5cd8 yes
+ 2288 028970d4 5b6c5cd8 yes
+ 2287 028970d4 5b6c5cd8 yes
+ 2286 028970d4 5b6c5cd8 yes
+ 2285 028970d4 5b6c5cd8 yes
+ 322 028970e8 5b6c5cd8 yes Duplicate promote/relocs
+ ...
+
+\\
+
+COMMAND: histobj.
+HistObj <obj_address>
+This command examines all stress log relocation records and displays the chain
+of GC relocations that may have led to the address passed in as an argument.
+Conceptually the output is:
+
+ GenN obj_address root1, root2, root3,
+ GenN-1 prev_obj_addr root1, root2,
+ GenN-2 prev_prev_oa root1, root4,
+ ...
+
+Sample output:
+ (lldb) histobj 028970d4
+ GCCount Object Roots
+ ---------------------------------------------------------
+ 2296 028970d4 00223fc4, 01e411b8,
+ 2295 028970d4 00223fc4, 01e411b8,
+ 2294 028970d4 00223fc4, 01e411b8,
+ 2293 028970d4 00223fc4, 01e411b8,
+ 2292 028970d4 00223fc4, 01e411b8,
+ 2291 028970d4 00223fc4, 01e411b8,
+ 2290 028970d4 00223fc4, 01e411b8,
+ 2289 028970d4 00223fc4, 01e411b8,
+ 2288 028970d4 00223fc4, 01e411b8,
+ 2287 028970d4 00223fc4, 01e411b8,
+ 2286 028970d4 00223fc4, 01e411b8,
+ 2285 028970d4 00223fc4, 01e411b8,
+ 322 028970d4 01e411b8,
+ 0 028970d4
+
+\\
+
+COMMAND: histclear.
+HistClear
+
+This command releases any resources used by the Hist-family of commands.
+Generally there's no need to call this explicitly, as each HistInit will first
+cleanup the previous resources.
+
+ (lldb) histclear
+ Completed successfully.
+
+\\
projects / platform / upstream / dotnet / runtime.git / commitdiff