docs: add native c++ windows debugging method (electron#26286)

mlaurencin · web-flow · commit d836682ee604 · 2020-11-06T16:55:55.000-08:00
diff --git a/docs/README.md b/docs/README.md
@@ -59,7 +59,7 @@ an issue:
   * [Manually Enabling Accessibility Features](tutorial/accessibility.md#manually-enabling-accessibility-features)
 * [Testing and Debugging](tutorial/application-debugging.md)
   * [Debugging the Main Process](tutorial/debugging-main-process.md)
-  * [Debugging the Main Process with Visual Studio Code](tutorial/debugging-main-process-vscode.md)
+  * [Debugging with Visual Studio Code](tutorial/debugging-vscode.md)
   * [Using Selenium and WebDriver](tutorial/using-selenium-and-webdriver.md)
   * [Testing on Headless CI Systems (Travis, Jenkins)](tutorial/testing-on-headless-ci.md)
   * [DevTools Extension](tutorial/devtools-extension.md)
diff --git a/docs/tutorial/debugging-main-process-vscode.md b/docs/tutorial/debugging-main-process-vscode.md
diff --git a/docs/tutorial/debugging-main-process.md b/docs/tutorial/debugging-main-process.md
@@ -30,4 +30,4 @@ You will need to use a debugger that supports the V8 inspector protocol.
 
 - Connect Chrome by visiting `chrome://inspect` and selecting to inspect the
   launched Electron app present there.
-- [Debugging the Main Process in VSCode](debugging-main-process-vscode.md)
+- [Debugging in VSCode](debugging-vscode.md)
diff --git a/docs/tutorial/debugging-vscode.md b/docs/tutorial/debugging-vscode.md
@@ -0,0 +1,100 @@
+# Debugging in VSCode
+
+This guide goes over how to set up VSCode debugging for both your own Electron project as well as the native Electron codebase.
+
+## Debugging your Electron app
+
+### Main process
+
+#### 1. Open an Electron project in VSCode.
+
+```sh
+$ git clone git@github.com:electron/electron-quick-start.git
+$ code electron-quick-start
+```
+
+#### 2. Add a file `.vscode/launch.json` with the following configuration:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Main Process",
+      "type": "node",
+      "request": "launch",
+      "cwd": "${workspaceFolder}",
+      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
+      "windows": {
+        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
+      },
+      "args" : ["."],
+      "outputCapture": "std"
+    }
+  ]
+}
+```
+
+
+#### 3. Debugging
+
+Set some breakpoints in `main.js`, and start debugging in the [Debug View](https://code.visualstudio.com/docs/editor/debugging). You should be able to hit the breakpoints.
+
+Here is a pre-configured project that you can download and directly debug in VSCode: https://github.com/octref/vscode-electron-debug/tree/master/electron-quick-start
+
+## Debugging the Electron codebase
+
+If you want to build Electron from source and modify the native Electron codebase, this section will help you in testing your modifications.
+
+For those unsure where to acquire this code or how to build it, [Electron's Build Tools](https://github.com/electron/build-tools) automates and explains most of this process. If you wish to manually set up the environment, you can instead use these [build instructions](https://www.electronjs.org/docs/development/build-instructions-gn).
+
+### Windows (C++)
+
+#### 1. Open an Electron project in VSCode.
+
+```sh
+$ git clone git@github.com:electron/electron-quick-start.git
+$ code electron-quick-start
+```
+
+#### 2. Add a file `.vscode/launch.json` with the following configuration:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "(Windows) Launch",
+      "type": "cppvsdbg",
+      "request": "launch",
+      "program": "${workspaceFolder}\\out\\your-executable-location\\electron.exe",
+      "args": ["your-electron-project-path"],
+      "stopAtEntry": false,
+      "cwd": "${workspaceFolder}",
+      "environment": [
+          {"name": "ELECTRON_ENABLE_LOGGING", "value": "true"},
+          {"name": "ELECTRON_ENABLE_STACK_DUMPING", "value": "true"},
+          {"name": "ELECTRON_RUN_AS_NODE", "value": ""},
+      ],
+      "externalConsole": false,
+      "sourceFileMap": {
+          "o:\\": "${workspaceFolder}",
+      },
+    },
+  ]
+}
+```
+**Configuration Notes**
+
+- `cppvsdbg` requires the [built-in C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) be enabled.
+- `${workspaceFolder}` is the full path to Chromium's `src` directory.
+- `your-executable-location` will be one of the following depending on a few items:
+  -  `Testing`: If you are using the default settings of [Electron's Build-Tools](https://github.com/electron/build-tools) or the default instructions when [building from source](https://www.electronjs.org/docs/development/build-instructions-gn#building).
+  -  `Release`: If you built a Release build rather than a Testing build.
+  -  `your-directory-name`: If you modified this during your build process from the default, this will be whatever you specified.
+- The `args` array string `"your-electron-project-path"` should be the absolute path to either the directory or `main.js` file of the Electron project you are using for testing. In this example, it should be your path to `electron-quick-start`.
+
+
+#### 3. Debugging
+
+Set some breakpoints in the .cc files of your choosing in the native Electron C++ code, and start debugging in the [Debug View](https://code.visualstudio.com/docs/editor/debugging).
