Skip to content
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Comment updates
  • Loading branch information
pieandcakes committed Apr 11, 2017
commit 2498dbf7528684b1273d70da7c0342a1d2ab4180
16 changes: 7 additions & 9 deletions Documentation/Debugger/gdb/Windows Subsystem for Linux.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
# Windows 10's Windows Subsystem for Linux
With the release of Windows 10 Creator's Update, you will now be able to use Visual Studio Code and the Microsoft C/C++ extension to debug your `Windows Subsystem for Linux (WSL)` Bash on Ubuntu projects.
With the release of Windows 10 Creators Update, you will now be able to use Visual Studio Code and the Microsoft C/C++ extension to debug your `Windows Subsystem for Linux (WSL)` [Bash on Ubuntu](https://msdn.microsoft.com/en-us/commandline/wsl/about) projects.

Code can be written on Windows itself using VSCode and debugged through `bash.exe` to the Bash on Windows layer.

**NOTE: Creator's Update is required due to bugfixes within the subsystem that we rely on to provide debugging. Debugging using a previous version of WSL is unsupported and likely will not work.**

## Prerequisites
* [Windows 10 Creator's Update with Windows Subsystem for Linux and Bash.](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide)
* Install g++/gcc and gdb to allow compiling and debugging.
* [Windows 10 Creators Update with Windows Subsystem for Linux and Bash](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide) installed.
* Install g++/gcc and gdb within `WSL` to allow compiling and debugging. You can use the package manager to do this. For example, to install g++, you can run `sudo apt install g++` in the Bash window.
* [Visual Studio Code](https://code.visualstudio.com) + Microsoft C/C++ extension for VSCode.

## How-To
To debug, commands will be routed from Windows through `bash.exe` to setup debugging. Because our extension runs as a 32-bit process, it will need to use the `C:\Windows\SysNative` folder to access the `bash.exe` executable that is normally in `C:\Windows\System32`. We will be using the `"pipeTransport"` ability within the extension to do debugging and `"sourceFileMap"` to map the source from the subsystem's paths back to Windows path.
To debug, commands will be routed from Windows through `bash.exe` to set up debugging. Because our extension runs as a 32-bit process, it will need to use the `C:\Windows\SysNative` folder to access the `bash.exe` executable that is normally in `C:\Windows\System32`. We will be using the `"pipeTransport"` ability within the extension to do debugging and `"sourceFileMap"` to map the source from the subsystem's paths back to Windows path.

**NOTE: Applications will need to be compiled in the `Windows Subsystem for Linux (WSL)` prior to debugging.**

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably worth a link back to https://code.visualstudio.com/Docs/editor/debugging so users who aren't familiar with launch.json and debugging in Visual Studio Code in general have a point of reference...? This page also explains how to create a launch.json and the various elements contained within it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@timsneath This isn't a tutorial but an addition of documentation within our repo for debugging. As such, I'm assuming that the user knows launch.json

### Example `launch.json` for Launching

In the following example, I have a local drive, `Z:\` that has my source code within windows for an app called kitchensink. I have setup the `"program"` and `"cwd"` paths to point to the directory within `WSL`. I have setup the `"pipeTransport"` to use `bash.exe`. I have also setup a `"sourceFileMap"` to have everything that is returned by `gdb` that starts with `/mnt/z` to point to `Z:\\` in Windows.
In the following example, I have a local drive, `Z:\` that has my source code within windows for an app called kitchensink. I have set up the `"program"` and `"cwd"` paths to point to the directory within `WSL`. I have set up the `"pipeTransport"` to use `bash.exe`. I have also set up a `"sourceFileMap"` to have everything that is returned by `gdb` that starts with `/mnt/z` to point to `Z:\\` in Windows.

```
{
Expand Down Expand Up @@ -54,7 +54,7 @@ In the following example, I have a local drive, `Z:\` that has my source code wi

### Example `launch.json` for Attaching to an Existing Process

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe I'm dumb, but I don't understand when I'd use the latter? This is like Debug / Attach to Process in 'full' VS, right?

Copy link
Contributor Author

@pieandcakes pieandcakes Apr 11, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you have a process already running in Bash on Windows and want to debug it, this is how you do it.


This is similar to the launch process for the same app above. I have changed the `"processID"` to use the remote process picker by specifying the command `"${command:pickRemoteProcess}"` and setup the same `"sourceFileMap"`. When I press F5 to attach, I get a picker drop down showing the running processes within `WSL` that I can find the process to which I want to attach.
This configuration similar to the launch process above. I have chosen to start the same application above from the Bash command line and now I want to attach to it for debugging. I have changed the `"processID"` to use the remote process picker by specifying the command `"${command:pickRemoteProcess}"` and set up the same `"sourceFileMap"`. When I press F5 to attach, I get a picker drop down showing the running processes within `WSL`. I can scroll or search for the process I want to attach to and start debugging.

```
{
Expand Down Expand Up @@ -83,6 +83,4 @@ This is similar to the launch process for the same app above. I have changed the
"/mnt/z": "z:\\"
}
}
```


```