From 542fa7cf75b63702bcac8038f439ced0ecefa5ff Mon Sep 17 00:00:00 2001 From: Mike McLaughlin Date: Tue, 30 Apr 2019 22:35:45 -0700 Subject: [PATCH] Update docs for preview 5. (#238) (#239) Update the tools version to 1.0.3-preview5.19251.2. --- README.md | 58 ++++++------------- .../building/windows-instructions.md | 24 ++++++++ documentation/dotnet-dump-instructions.md | 16 ++--- documentation/dotnet-trace-instructions.md | 4 +- documentation/installing-sos-instructions.md | 10 ++-- .../installing-sos-windows-instructions.md | 6 +- 6 files changed, 55 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index a830cffa5c..30a100763a 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ The details of installing the components differ depending on the operating syste pages based on your OS. There is no cross-building across OS (only for ARM, which is built on X64). You have to be on the particular platform to build that platform. -To install the platform's prerequisites: +To install the platform's prerequisites and build: * [Windows Instructions](documentation/building/windows-instructions.md) * [Linux Instructions](documentation/building/linux-instructions.md) @@ -28,46 +28,6 @@ To install the platform's prerequisites: * [FreeBSD Instructions](documentation/building/freebsd-instructions.md) * [NetBSD Instructions](documentation/building/netbsd-instructions.md) -To build under Windows, run build.cmd from the root of the repository: - -```bat -build.cmd - -[Lots of build spew] - -BUILD: Repo sucessfully built. -BUILD: Product binaries are available at c:\git\diagnostics\artifacts\Debug\bin\Windows_NT.x64 -``` - -To build for x86: - -```bat -build.cmd -architecture x86 -``` - -To test the resulting SOS: - -```bat -test.cmd -``` - -To build under Linux, MacOS, FreeBSD, or NetBSD, run build.sh from the root of the repository: - -```sh -./build.sh - -[Lots of build spew] - -BUILD: Repo sucessfully built. -BUILD: Product binaries are available at /home/mikem/diagnostics/artifacts/Debug/bin/Linux.x64 -``` - -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. @@ -103,6 +63,22 @@ Before executing the "bt" command to dump native frames to load the native symbo (lldb) loadsymbols +## Release Notes + +### dotnet-dump + +* Does not work on alpine and other MUSL based distros. Issue [#195](https://github.com/dotnet/diagnostics/issues/195). +* Not supported ARM32 or ARM64. Issue [#168](https://github.com/dotnet/diagnostics/issues/168). +* Not supported on MacOS. +* Dump collection (dotnet dump collect) requires SYS\_PTRACE docker capabilities (--cap-add=SYS\_PTRACE or --privileged). +* Dump analysis (dotnet dump analyze) in on Microsoft SDK Linux docker images throws `Unhandled exception: System.DllNotFoundException: Unable to load shared library 'libdl.so' or one of its dependencies` exception. Issue [#201](https://github.com/dotnet/diagnostics/issues/201). A work around is to install the "libc6-dev" package. +* Dump analysis on Windows is not supported. Minidump collection is support. Issue [#157](https://github.com/dotnet/diagnostics/issues/157). + +### dotnet-sos + +* Does not work on alpine and other MUSL based distros. Issue [#195](https://github.com/dotnet/diagnostics/issues/195). +* Not supported ARM32 or ARM64. Issue [#168](https://github.com/dotnet/diagnostics/issues/168). + ## Useful Links * [The LLDB Debugger](http://lldb.llvm.org/index.html) - More information about lldb. diff --git a/documentation/building/windows-instructions.md b/documentation/building/windows-instructions.md index 8a789ff2b8..64c95ae15d 100644 --- a/documentation/building/windows-instructions.md +++ b/documentation/building/windows-instructions.md @@ -105,3 +105,27 @@ the PATH variable persistent by going to Control Panel -> System And Security - and select the 'Path' variable in the 'System variables' (if you want to change it for all users) or 'User variables' (if you only want to change it for the current user). Simply edit the PATH variable's value and add the directory (with a semicolon separator). +## Building + +To build under Windows, run build.cmd from the root of the repository: + +```bat +build.cmd + +[Lots of build spew] + +BUILD: Repo sucessfully built. +BUILD: Product binaries are available at c:\git\diagnostics\artifacts\Debug\bin\Windows_NT.x64 +``` + +To build for x86: + +```bat +build.cmd -architecture x86 +``` + +To test the resulting SOS: + +```bat +test.cmd +``` diff --git a/documentation/dotnet-dump-instructions.md b/documentation/dotnet-dump-instructions.md index 9d92737af3..55bee2d43c 100644 --- a/documentation/dotnet-dump-instructions.md +++ b/documentation/dotnet-dump-instructions.md @@ -7,9 +7,9 @@ The dotnet-dump CLI global tool is way to collect and analyze Windows and Linux The first step is to install the dotnet-dump CLI global tool. This requires the 2.1 .NET Core SDK to be installed. If you see the error message `Tool 'dotnet-dump' is already installed`, you will need to uninstall the global tool (see below). - $ dotnet tool install -g dotnet-dump --version 1.0.3-preview5.19228.1 + $ dotnet tool install -g dotnet-dump --version 1.0.3-preview5.19251.2 You can invoke the tool using the following command: dotnet-dump - Tool 'dotnet-dump' (version '1.0.3-preview5.19228.1') was successfully installed. + Tool 'dotnet-dump' (version '1.0.3-preview5.19251.2') was successfully installed. ## Using dotnet-dump @@ -17,7 +17,7 @@ The next step is to collect a dump. This can be skipped if a core dump has alrea On Linux, it needs to be run as superuser: - $ sudo -E PATH=$PATH dotnet dump collect --process-id 1902 + $ sudo $HOME/.dotnet/tools/dotnet-dump collect --process-id 1902 Writing minidump to file ./core_20190226_135837 Written 98983936 bytes (24166 pages) to core file Complete @@ -108,12 +108,4 @@ To display the help: ## Uninstalling dotnet-dump $ dotnet tool uninstall -g dotnet-dump - Tool 'dotnet-dump' (version '1.0.3-preview5.19228.1') was successfully uninstalled. - -## Release Notes - -Preview5 - -* dotnet-dump does not work on alpine and other MUSL based distros. Issue [#195](https://github.com/dotnet/diagnostics/issues/195). -* dotnet-dump collect requires SYS\_PTRACE docker capabilities (--cap-add=SYS\_PTRACE or --privileged). -* dotnet-dump analyze in Microsoft SDK docker images throws `Unhandled exception: System.DllNotFoundException: Unable to load shared library 'libdl.so' or one of its dependencies` exception. Issue [#201](https://github.com/dotnet/diagnostics/issues/201). + Tool 'dotnet-dump' (version '1.0.3-preview5.19251.2') was successfully uninstalled. diff --git a/documentation/dotnet-trace-instructions.md b/documentation/dotnet-trace-instructions.md index 15bb077a86..b7fef5122d 100644 --- a/documentation/dotnet-trace-instructions.md +++ b/documentation/dotnet-trace-instructions.md @@ -7,9 +7,9 @@ The dotnet-trace tool is a cross-platform CLI global tool that enables the colle The first step is to install the dotnet-trace CLI global tool. This requires at least version 2.1 of the SDK to be installed. ```cmd -$ dotnet tool install --global dotnet-trace --version 1.0.3-preview5.19228.1 +$ dotnet tool install --global dotnet-trace --version 1.0.3-preview5.19251.2 You can invoke the tool using the following command: dotnet-trace -Tool 'dotnet-trace' (version '1.0.3-preview5.19228.1') was successfully installed. +Tool 'dotnet-trace' (version '1.0.3-preview5.19251.2') was successfully installed. ``` ## Using dotnet-trace diff --git a/documentation/installing-sos-instructions.md b/documentation/installing-sos-instructions.md index 97a8590fff..f3198d6a33 100644 --- a/documentation/installing-sos-instructions.md +++ b/documentation/installing-sos-instructions.md @@ -3,16 +3,16 @@ Installing SOS on Linux and MacOS The first step is to install the dotnet-sos CLI global tool. This requires the 2.1 .NET Core SDK to be installed. If you see the error message `Tool 'dotnet-sos' is already installed`, you will need to uninstall the global tool (see below). - $ dotnet tool install -g dotnet-sos --version 1.0.3-preview5.19228.1 + $ dotnet tool install -g dotnet-sos --version 1.0.3-preview5.19251.2 You can invoke the tool using the following command: dotnet-sos - Tool 'dotnet-sos' (version '1.0.3-preview5.19228.1') was successfully installed. + Tool 'dotnet-sos' (version '1.0.3-preview5.19251.2') was successfully installed. The next step is use this global tool to install SOS. $ dotnet sos install - Installing SOS to /home/mikem/.dotnet/sos from /home/mikem/.dotnet/tools/.store/dotnet-sos/1.0.3-preview5.19228.1/dotnet-sos/1.0.3-preview5.19228.1/tools/netcoreapp2.1/any/linux-x64 + Installing SOS to /home/mikem/.dotnet/sos from /home/mikem/.dotnet/tools/.store/dotnet-sos/1.0.3-preview5.19251.2/dotnet-sos/1.0.3-preview5.19251.2/tools/netcoreapp2.1/any/linux-x64 Creating installation directory... Copying files... Updating existing /home/mikem/.lldbinit file - LLDB will load SOS automatically at startup @@ -74,7 +74,7 @@ Now any time you run lldb, SOS will automatically be loaded and the symbol downl The installer needs to be run again: $ dotnet sos install - Installing SOS to /home/mikem/.dotnet/sos from /home/mikem/.dotnet/tools/.store/dotnet-sos/1.0.3-preview5.19228.1/dotnet-sos/1.0.3-preview5.19228.1/tools/netcoreapp2.1/any/linux-x64 + Installing SOS to /home/mikem/.dotnet/sos from /home/mikem/.dotnet/tools/.store/dotnet-sos/1.0.3-preview5.19251.2/dotnet-sos/1.0.3-preview5.19251.2/tools/netcoreapp2.1/any/linux-x64 Installing over existing installation... Creating installation directory... Copying files... @@ -94,4 +94,4 @@ To uninstall and remove the lldb configuration run this command: To remove the SOS installer global tool: $ dotnet tool uninstall -g dotnet-sos - Tool 'dotnet-sos' (version '1.0.3-preview5.19228.1') was successfully uninstalled. + Tool 'dotnet-sos' (version '1.0.3-preview5.19251.2') was successfully uninstalled. diff --git a/documentation/installing-sos-windows-instructions.md b/documentation/installing-sos-windows-instructions.md index 6cd7b1b8bb..61ecd0f904 100644 --- a/documentation/installing-sos-windows-instructions.md +++ b/documentation/installing-sos-windows-instructions.md @@ -47,14 +47,14 @@ SOS will automatically be loaded from the internal Microsoft extension gallery. It is recommended that you update to the newer versions of the Windows debugger, but you can still use the latest SOS with older Windows debuggers by using the dotnet-sos CLI global tool to install. It is not as convenient. You may have to ".unload" the SOS that is loaded from the "runtime" directory. - C:\Users\mikem>dotnet tool install -g dotnet-sos --version 1.0.3-preview5.19228.1 + C:\Users\mikem>dotnet tool install -g dotnet-sos --version 1.0.3-preview5.19251.2 You can invoke the tool using the following command: dotnet-sos - Tool 'dotnet-sos' (version '1.0.3-preview5.19228.1') was successfully installed. + Tool 'dotnet-sos' (version '1.0.3-preview5.19251.2') was successfully installed. Run the installer: C:\Users\mikem>dotnet sos install - Installing SOS to C:\Users\mikem\.dotnet\sos from C:\Users\mikem\.dotnet\tools\.store\dotnet-sos\1.0.3-preview5.19228.1\dotnet-sos\1.0.3-preview5.19228.1\tools\netcoreapp2.1\any\win-x64 + Installing SOS to C:\Users\mikem\.dotnet\sos from C:\Users\mikem\.dotnet\tools\.store\dotnet-sos\1.0.3-preview5.19251.2\dotnet-sos\1.0.3-preview5.19251.2\tools\netcoreapp2.1\any\win-x64 Creating installation directory... Copying files... Execute '.load C:\Users\mikem\.dotnet\sos\sos.dll' to load SOS in your Windows debugger.