From 544b8601088c3cf244fd4692f7bbc16b9acd4f6d Mon Sep 17 00:00:00 2001 From: "Pierson Lee (PIE)" Date: Mon, 10 Apr 2017 13:56:45 -0700 Subject: [PATCH 1/3] Add documentation for WSL --- .../gdb/Windows Subsystem for Linux.md | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 Documentation/Debugger/gdb/Windows Subsystem for Linux.md diff --git a/Documentation/Debugger/gdb/Windows Subsystem for Linux.md b/Documentation/Debugger/gdb/Windows Subsystem for Linux.md new file mode 100644 index 000000000..9777ac472 --- /dev/null +++ b/Documentation/Debugger/gdb/Windows Subsystem for Linux.md @@ -0,0 +1,88 @@ +# 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. + +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. +* [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 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. + +``` + { + "name": "C++ Launch", + "type": "cppdbg", + "request": "launch", + "program": "/mnt/z/Bash/kitchensink/a.out", + "args": ["-fThreading"], + "stopAtEntry": false, + "cwd": "/mnt/z/Bash/kitchensink", + "environment": [], + "externalConsole": true, + "windows": { + "MIMode": "gdb", + "setupCommands": [ + { + "description": "Enable pretty-printing for gdb", + "text": "-enable-pretty-printing", + "ignoreFailures": true + } + ] + }, + "pipeTransport": { + "pipeCwd": "", + "pipeProgram": "c:\\windows\\sysnative\\bash.exe", + "pipeArgs": ["-c"], + "debuggerPath": "/usr/bin/gdb" + }, + "sourceFileMap": { + "/mnt/z": "z:\\" + } + } +``` + +### 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. + +``` + { + "name": "C++ Attach", + "type": "cppdbg", + "request": "attach", + "program": "/mnt/z/Bash/kitchensink/a.out", + "processId": "${command:pickRemoteProcess}", + "windows": { + "MIMode": "gdb", + "setupCommands": [ + { + "description": "Enable pretty-printing for gdb", + "text": "-enable-pretty-printing", + "ignoreFailures": true + } + ] + }, + "pipeTransport": { + "pipeCwd": "", + "pipeProgram": "c:\\windows\\sysnative\\bash.exe", + "pipeArgs": ["-c"], + "debuggerPath": "/usr/bin/gdb" + }, + "sourceFileMap": { + "/mnt/z": "z:\\" + } + } +``` + + From 74ed2281c3f7bd1aacfcde979c6062ff4bf909a3 Mon Sep 17 00:00:00 2001 From: "Pierson Lee (PIE)" Date: Mon, 10 Apr 2017 14:29:44 -0700 Subject: [PATCH 2/3] PR comments --- Documentation/Debugger/gdb/Windows Subsystem for Linux.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/Debugger/gdb/Windows Subsystem for Linux.md b/Documentation/Debugger/gdb/Windows Subsystem for Linux.md index 9777ac472..b9b200c0e 100644 --- a/Documentation/Debugger/gdb/Windows Subsystem for Linux.md +++ b/Documentation/Debugger/gdb/Windows Subsystem for Linux.md @@ -11,7 +11,7 @@ Code can be written on Windows itself using VSCode and debugged through `bash.ex * [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 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 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. **NOTE: Applications will need to be compiled in the `Windows Subsystem for Linux (WSL)` prior to debugging.** From 2498dbf7528684b1273d70da7c0342a1d2ab4180 Mon Sep 17 00:00:00 2001 From: "Pierson Lee (PIE)" Date: Mon, 10 Apr 2017 17:43:42 -0700 Subject: [PATCH 3/3] Comment updates --- .../Debugger/gdb/Windows Subsystem for Linux.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/Documentation/Debugger/gdb/Windows Subsystem for Linux.md b/Documentation/Debugger/gdb/Windows Subsystem for Linux.md index b9b200c0e..929d6c5d4 100644 --- a/Documentation/Debugger/gdb/Windows Subsystem for Linux.md +++ b/Documentation/Debugger/gdb/Windows Subsystem for Linux.md @@ -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 -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:\\" } } -``` - - +``` \ No newline at end of file