Move debugging docs

README.md

@@ -66,38 +66,6 @@ contributing guidelines and learn about submodules. Not every
 submodule is required on every system; see the individual build
 instructions for the necessary subsets.
 
-## Debugging
-
-To enable debugging on Linux, follow the installation instructions for
-[Experimental .NET Core Debugging in VS Code][VS Code]. You will also
-want to review their [detailed instructions][vscclrdebugger].
-
-VS Code will place a `.vscode` directory in the PowerShell folder.
-This contains the `launch.json` file, which you will customize using
-the instructions below. You will also be prompted to create a
-`tasks.json` file.
-
-Currently, debugging supports attaching to a currently running
-powershell process. Assuming you've created a `launch.json` file
-correctly, within the "configuration" section, use the below settings:
-
-```json
-"configurations": [
-    {
-        "name": "powershell",
-        "type": "coreclr",
-        "request": "attach",
-        "processName": "powershell"
-    }
-]
-```
-
-VS Code will now attach to a running `powershell` process. Start
-powershell, then (in VS Code) press `F5` to begin the debugger.
-
-[VS Code]: https://blogs.msdn.microsoft.com/visualstudioalm/2016/03/10/experimental-net-core-debugging-in-vs-code/
-[vscclrdebugger]: http://aka.ms/vscclrdebugger
-
 ### FullCLR PowerShell
 
 ## Running from CI server

docs/debugging/README.md

@@ -0,0 +1,44 @@
+Debugging
+=========
+
+VS Code
+-------
+
+[Experimental .NET Core Debugging in VS Code][core-debug] enables
+cross-platform debugging with the [Visual Studio Code][vscode] editor.
+This is made possible by the [OmniSharp][] extension for VS Code.
+
+Please review their [detailed instructions][vscclrdebugger]. In
+addition to being able to build PowerShell, you need:
+
+- C# Extension for VS Code installed
+- `powershell` executable in your path (self-host if not on Windows)
+
+The committed `.vscode` folder in the root of this repository contains
+the `launch.json` and `tasks.json` files which provide Core PowerShell
+debugging configurations and a build task.
+
+The "build" task will run `Start-PSBuild`.
+
+The ".NET Core Launch" configuration will build and start a
+`powershell` process, with `justMyCode` disabled, and `stopAtEntry`
+enabled. The debugger is highly experimental, so if it does not break
+at `Main`, try again.
+
+Note that the debugger does not yet provide `stdin` handles, so once
+`ReadKey` is called in the `ReadLine` loop, `System.Console` will
+throw exceptions. The options around this are 1) provide
+`[ "-c", "... ; exit" ]` to the "Launch" configuration's `args` so
+that the `ReadLine` listener is never called, 2) ignore the exceptions
+and only debug code before the listener, or 3) use the "Attach"
+configuration.
+
+The ".NET Core Attach" configuration will start listening for a
+process named `powershell`, and will attach to it. If you need more
+fine grained control, replace `processName` with `processId` and
+provide a PID. (Please be careful not to commit such a change).
+
+[core-debug]: https://blogs.msdn.microsoft.com/visualstudioalm/2016/03/10/experimental-net-core-debugging-in-vs-code/
+[vscode]: https://code.visualstudio.com/
+[OmniSharp]: https://github.com/OmniSharp/omnisharp-vscode
+[vscclrdebugger]: http://aka.ms/vscclrdebugger