Add dotnet-dump documentation for the preview. (#141)

Upgrade to clrmd 1.0.5 containing the ELF dump fix.

Add official build instructions.

diff --git a/README.md b/README.md
index b58c2737dc262555c35b1559d36376ad6b176a82..7212d86544133c7cdf3a3ef2566bbe9610633a03 100644 (file)
--- a/README.md
+++ b/README.md
@@ -67,7 +67,7 @@ To test the resulting SOS and plugin:
 ```sh
 ./test.sh
 ```
-
+ 
 ## Getting lldb 
 
 Getting a version of lldb that works for your platform can be a problem sometimes. The version has to be at least 3.9 or greater because of a bug running SOS on a core dump that was fixed. Some Linux distros like Ubuntu it is easy as `sudo apt-get install lldb-3.9 python-lldb-3.9`. On other distros, you will need to build lldb. The directions below should give you some guidance.
@@ -88,6 +88,10 @@ Getting a version of lldb that works for your platform can be a problem sometime
 * [SOS debugging for Windows](documentation/sos-debugging-extension-windows.md)
 * [Debugging a core dump](documentation/debugging-coredump.md)
 
+## Tools
+
+* [dotnet-dump](documentation/dotnet-dump-instructions.md) - Dump collection and analysis utility.
+
 ## New Features
 
 Symbol server support - The `setsymbolserver` command enables downloading the symbol files (portable PDBs) for managed assemblies during commands like `clrstack`, etc. See `soshelp setsymbolserver` for more details.
@@ -104,6 +108,7 @@ Before executing the "bt" command to dump native frames to load the native symbo
 * [SOS](https://msdn.microsoft.com/en-us/library/bb190764(v=vs.110).aspx) - More information about SOS.
 * [Debugging CoreCLR](https://github.com/dotnet/coreclr/blob/master/Documentation/building/debugging-instructions.md) - Instructions for debugging .NET Core and the CoreCLR runtime.
 * [dotnet/coreclr](https://github.com/dotnet/coreclr) - Source for the .NET Core runtime.
+* [Official Build Instructions](documentation/building/official-build-instructions.md) - Internal official build instructions.
 
 [//]: # (Begin current test results)
 

diff --git a/documentation/building/official-build-instructions.md b/documentation/building/official-build-instructions.md
new file mode 100644 (file)
index 0000000..6a246ad
--- /dev/null
+++ b/documentation/building/official-build-instructions.md
@@ -0,0 +1,8 @@
+Official Build Instructions
+===========================
+
+WARNING: These instructions will only work internally at Microsoft.
+
+To kick off an official build, go to this build definition: https://devdiv.visualstudio.com/DevDiv/_build?definitionId=9462 and queue build leaving all the build variables as their defaults.
+
+This signs and publishes dotnet-dump, dotnet-sos, dotnet-trace, dotnet-counters and Microsoft.Diagnostic.TestHepers packages to https://dotnetfeed.blob.core.windows.net/dotnet-core feed.

diff --git a/documentation/dotnet-dump-instructions.md b/documentation/dotnet-dump-instructions.md
new file mode 100644 (file)
index 0000000..37dc73b
--- /dev/null
+++ b/documentation/dotnet-dump-instructions.md
@@ -0,0 +1,106 @@
+Dump collection and analysis utility (dotnet-dump)
+==================================================
+
+The dotnet-dump CLI global tool is way to collect and analyze Windows and Linux dumps all without any native debugger involved like lldb on Linux. This is important on platforms like Alpine Linux where a fully working lldb isn't available. The dotnet-dump tool will allow you to run SOS commands to analyze crashes and the GC, but it isn't a native debugger so things like displaying the native stack frames isn't supported.
+
+## Installing dotnet-dump
+
+The first step is to install the dotnet-dump CLI global tool. This requires the 2.1 .NET Core SDK to be installed. 
+
+    $ dotnet tool install -g dotnet-dump --version 1.0.2-preview3.19151.2 --add-source https://dotnetfeed.blob.core.windows.net/dotnet-core/index.json
+    You can invoke the tool using the following command: dotnet-dump
+    Tool 'dotnet-dump' (version '1.0.2-preview3.19151.2') was successfully installed.
+
+## Using dotnet-dump
+
+The next step is to collect a dump. This can be skipped if a core dump has already been generated by the operating system or [createdump](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md#configurationpolicy) on Linux.
+
+On Linux, it needs to be run as superuser:
+     
+    $ sudo -E dotnet dump collect --process-id 1902
+    Writing minidump to file ./core_20190226_135837
+    Written 98983936 bytes (24166 pages) to core file
+    Complete
+
+Now analyze the core dump. Only works on Linux for this preview.
+
+    $ dotnet-dump analyze ./core_20190226_135850
+    Loading core dump: ./core_20190226_135850
+    Ready to process analysis commands. Type 'help' to list available commands or 'help [command]' to get detailed help on a command.
+    Type 'quit' or 'exit' to exit the session.
+    >
+
+This brings up an interactive command processor that accepts commands like:
+
+    > clrstack
+    OS Thread Id: 0x573d (0)
+        Child SP               IP Call Site
+    00007FFD28B42C58 00007fb22c1a8ed9 [HelperMethodFrame_PROTECTOBJ: 00007ffd28b42c58] System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
+    00007FFD28B42DD0 00007FB1B1334F67 System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo) [/root/coreclr/src/mscorlib/src/System/Reflection/RuntimeMethodInfo.cs @ 472]
+    00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.Program.Foo4(System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 54]
+    00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.Program.Foo2(Int32, System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 29]
+    00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.Program.Foo1(Int32, System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 24]
+    00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.Program.Main(System.String[]) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 19]
+    00007FFD28B43210 00007fb22aa9cedf [GCFrame: 00007ffd28b43210]
+    00007FFD28B43610 00007fb22aa9cedf [GCFrame: 00007ffd28b43610]
+
+To see the unhandled exception if your app was terminated:
+
+    > pe -lines
+    Exception object: 00007fb18c038590
+    Exception type:   System.Reflection.TargetInvocationException
+    Message:          Exception has been thrown by the target of an invocation.
+    InnerException:   System.Exception, Use !PrintException 00007FB18C038368 to see more.
+    StackTrace (generated):
+    SP               IP               Function
+    00007FFD28B42DD0 0000000000000000 System.Private.CoreLib.dll!System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
+    00007FFD28B42DD0 00007FB1B1334F67 System.Private.CoreLib.dll!System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo)+0xa7 [/root/coreclr/src/mscorlib/src/System/Reflection/RuntimeMethodInfo.cs @ 472]
+    00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.dll!SymbolTestApp.Program.Foo4(System.String)+0x15d [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 54]
+    00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.dll!SymbolTestApp.Program.Foo2(Int32, System.String)+0x34 [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 29]
+    00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.dll!SymbolTestApp.Program.Foo1(Int32, System.String)+0x3a [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 24]
+    00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.dll!SymbolTestApp.Program.Main(System.String[])+0x6e [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 19]
+
+StackTraceString: <none>
+HResult: 80131604
+
+To display the help:
+
+    > help
+    Usage:
+      dotnet-dump [command]
+
+    Commands:
+      exit, quit                           Exit interactive mode.
+      help <command>                       Display help for a command.
+      lm, modules                          Displays the native modules in the process.
+      threads, setthread <threadid>        Sets or displays the current thread id for the SOS commands.
+      clrstack <arguments>                 Provides a stack trace of managed code only.
+      clrthreads <arguments>               List the managed threads running.
+      dumpasync <arguments>                Displays info about async state machines on the garbage-collected heap.
+      dumpassembly <arguments>             Displays details about an assembly.
+      dumpclass <arguments>                Displays information about a EE class structure at the specified address.
+      dumpdelegate <arguments>             Displays information about a delegate.
+      dumpdomain <arguments>               Displays information all the AppDomains and all assemblies within the domains.
+      dumpheap <arguments>                 Displays info about the garbage-collected heap and collection statistics about objects.
+      dumpil <arguments>                   Displays the Microsoft intermediate language (MSIL) that is associated with a managed method.
+      dumplog <arguments>                  Writes the contents of an in-memory stress log to the specified file.
+      dumpmd <arguments>                   Displays information about a MethodDesc structure at the specified address.
+      dumpmodule <arguments>               Displays information about a EE module structure at the specified address.
+      dumpmt <arguments>                   Displays information about a method table at the specified address.
+      dumpobj <arguments>                  Displays info about an object at the specified address.
+      dso, dumpstackobjects <arguments>    Displays all managed objects found within the bounds of the current stack.
+      eeheap <arguments>                   Displays info about process memory consumed by internal runtime data structures.
+      finalizequeue <arguments>            Displays all objects registered for finalization.
+      gcroot <arguments>                   Displays info about references (or roots) to an object at the specified address.
+      gcwhere <arguments>                  Displays the location in the GC heap of the argument passed in.
+      ip2md <arguments>                    Displays the MethodDesc structure at the specified address in code that has been JIT-compiled.
+      name2ee <arguments>                  Displays the MethodTable structure and EEClass structure for the specified type or method in the specified module.
+      pe, printexception <arguments>       Displays and formats fields of any object derived from the Exception class at the specified address.
+      syncblk <arguments>                  Displays the SyncBlock holder info.
+      histclear <arguments>                Releases any resources used by the family of Hist commands.
+      histinit <arguments>                 Initializes the SOS structures from the stress log saved in the debuggee.
+      histobj <arguments>                  Examines all stress log relocation records and displays the chain of garbage collection relocations that may have led to the address passed in as an argument.
+      histobjfind <arguments>              Displays all the log entries that reference an object at the specified address.
+      histroot <arguments>                 Displays information related to both promotions and relocations of the specified root.
+      setsymbolserver <arguments>          Enables the symbol server support
+      soshelp <arguments>                  Displays all available commands when no parameter is specified, or displays detailed help information about the specified command. soshelp <command>

diff --git a/eng/Versions.props b/eng/Versions.props
index a17e8bc06e7142beef8f66588ab650d85d662892..bdeb7c9f23ba532007feb680fb7fce7d34a3d7cb 100644 (file)
--- a/eng/Versions.props
+++ b/eng/Versions.props
@@ -20,7 +20,7 @@
 
     <!-- Other libs -->
     <MicrosoftSymbolStoreVersion>1.0.0-dev-63716-01</MicrosoftSymbolStoreVersion>
-    <MicrosoftDiagnosticsRuntimeVersion>1.0.3</MicrosoftDiagnosticsRuntimeVersion>
+    <MicrosoftDiagnosticsRuntimeVersion>1.0.5</MicrosoftDiagnosticsRuntimeVersion>
   </PropertyGroup>
 
   <PropertyGroup>

diff --git a/src/Tools/dotnet-dump/Analyzer.cs b/src/Tools/dotnet-dump/Analyzer.cs
index 69939f3b7c125cd0498b8bec24a43afe8e17c21b..d011926d71fcf75d6636469d6182c0651c2fc80f 100644 (file)
--- a/src/Tools/dotnet-dump/Analyzer.cs
+++ b/src/Tools/dotnet-dump/Analyzer.cs
@@ -33,7 +33,8 @@ namespace Microsoft.Diagnostic.Tools.Dump
                     target = DataTarget.LoadCoreDump(dump_path.FullName);
                 }
                 else if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows)) {
-                    target = DataTarget.LoadCrashDump(dump_path.FullName, CrashDumpReader.ClrMD);
+                    //target = DataTarget.LoadCrashDump(dump_path.FullName, CrashDumpReader.ClrMD);
+                    throw new PlatformNotSupportedException("Preview build: This is not yet implemented on Windows");
                 }
                 else {
                     throw new PlatformNotSupportedException($"Unsupported operating system: {RuntimeInformation.OSDescription}");