-
Notifications
You must be signed in to change notification settings - Fork 1.7k
Add documentation for WSL #626
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
- Loading branch information
There are no files selected for viewing
| 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. | ||
|
|
||
| ``` | ||
| { | ||
|
|
@@ -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 | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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?
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||
|
|
||
| ``` | ||
| { | ||
|
|
@@ -83,6 +83,4 @@ This is similar to the launch process for the same app above. I have changed the | |
| "/mnt/z": "z:\\" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
| ``` | ||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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