From cc8842c6316abdd9e40b013671c8c771821c2759 Mon Sep 17 00:00:00 2001
From: Andrew Schwartzmeyer <andrew@schwartzmeyer.com>
Date: Tue, 4 Oct 2016 13:10:19 -0700
Subject: [PATCH] Add .NET Core debug build instructions (#2410)

These are thanks to Eric St John from .NET Core.
---
 docs/debugging/README.md | 57 +++++++++++++++++++++++++++++++++++-----
 1 file changed, 50 insertions(+), 7 deletions(-)

diff --git a/docs/debugging/README.md b/docs/debugging/README.md
index 53fa3911ab..e946d9aa7e 100644
--- a/docs/debugging/README.md
+++ b/docs/debugging/README.md
@@ -1,8 +1,5 @@
-Debugging
-=========
-
 Visual Studio Code
-=======
+==================
 
 [Experimental .NET Core Debugging in VS Code][core-debug] enables
 cross-platform debugging with the [Visual Studio Code][vscode] editor.
@@ -90,8 +87,9 @@ Then trace it like this:
 Trace-Command -Expression { Get-ChildItem . } -Name PathResolution -PSHost
 ```
 
-The `-PSHost` specifies the sink, in this case the console host, so we can see
-the tracing messages.
+The `-PSHost` specifies the sink, in this case the console host,
+so we can see the tracing messages.
+The `-Name` chooses the list of tracers to enable.
 
 LLDB with SOS plugin
 ====================
@@ -120,4 +118,49 @@ information to the console. These are controlled by the
 `PAL_DBG_CHANNELS`, e.g., `export PAL_DBG_CHANNELS="+all.all"`, as
 detailed in the `dbgmsg.h` [header][].
 
-[header]: https://github.com/dotnet/coreclr/blob/release/1.0.0-rc2/src/pal/src/include/pal/dbgmsg.h
+Enabling `+all.all` is *incredibly* noisy;
+you will need to narrow your scope.
+
+[header]: https://github.com/dotnet/coreclr/blob/release/1.0.0/src/pal/src/include/pal/dbgmsg.h
+
+Debugging .NET Core
+===================
+
+The .NET Core libraries downloaded from NuGet and shipped with PowerShell are release versions.
+This means that `PAL_DBG_CHANNELS` will not work with them,
+and instead you must build and deploy .NET Core built in debug mode.
+These instructions are not meant to be comprehensive,
+but should prove useful.
+
+They are currently written for Linux and are meant only as a shortcut means to debug.
+
+Build and deploy CoreCLR
+------------------------
+
+* Clone CoreCLR: `git clone -b release/1.0.0 https://github.com/dotnet/coreclr.git`
+* Follow [building instructions](https://github.com/dotnet/coreclr/blob/release/1.0.0/Documentation/building/linux-instructions.md)
+* Wait for `./build.sh` to finish
+* Overwrite PowerShell libraries: `cp bin/Product/Linux.x64.Debug/*{so,dll} /path/to/powershell/`
+
+Build and deploy CoreFX
+-----------------------
+
+* Clone CoreFX: `git clone -b release/1.0.0 https://github.com/dotnet/corefx.git`
+* Follow [building instructions](https://github.com/dotnet/corefx/blob/release/1.0.0/Documentation/building/unix-instructions.md)
+* Wait for `./build.sh skiptests` to finish
+* Overwrite PowerShell libraries:
+
+> This must be done in a particular order to get the most specific build,
+> and each phase must be allowed to overwrite both the previous phase
+> and any files previously found (hence the use of `-exec cp`).
+> The glob cannot go more than one directory deep,
+> as subdirectories can have alternative and unwanted implementations
+> of libraries with the same name.
+
+```sh
+dest=/path/to/powershell/
+find bin/AnyOS.AnyCPU.Debug/*/*.dll -exec cp -p {} $dest \;
+find bin/Unix.AnyCPU.Debug/*/*.dll -exec cp -p {} $dest \;
+find bin/Linux.AnyCPU.Debug/*/*.dll -exec cp -p {} $dest \;
+find bin/Linux.x64.Debug/ -name *.so -exec cp -p {} $dest \;
+```