Skip to content

Commit

Permalink
Comment updates
Browse files Browse the repository at this point in the history
  • Loading branch information
pieandcakes committed Apr 11, 2017
1 parent 74ed228 commit 2498dbf
Showing 1 changed file with 7 additions and 9 deletions.
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.**

### 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

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:\\"
}
}
```


```

0 comments on commit 2498dbf

Please sign in to comment.