From d836682ee60401ee64ecccc8a1d7a551265bbb30 Mon Sep 17 00:00:00 2001
From: Michaela Laurencin <35157522+mlaurencin@users.noreply.github.com>
Date: Fri, 6 Nov 2020 16:55:55 -0800
Subject: [PATCH] docs: add native c++ windows debugging method (#26286)

---
 docs/README.md                                |   2 +-
 .../tutorial/debugging-main-process-vscode.md |  36 -------
 docs/tutorial/debugging-main-process.md       |   2 +-
 docs/tutorial/debugging-vscode.md             | 100 ++++++++++++++++++
 4 files changed, 102 insertions(+), 38 deletions(-)
 delete mode 100644 docs/tutorial/debugging-main-process-vscode.md
 create mode 100644 docs/tutorial/debugging-vscode.md

diff --git a/docs/README.md b/docs/README.md
index 3347607bd78..37ef74b4634 100644
--- 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
deleted file mode 100644
index b13d79ddf5a..00000000000
--- a/docs/tutorial/debugging-main-process-vscode.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Debugging the Main Process in VSCode
-
-### 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
diff --git a/docs/tutorial/debugging-main-process.md b/docs/tutorial/debugging-main-process.md
index ba0b317d8b0..9b0b2ae6bcb 100644
--- 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
new file mode 100644
index 00000000000..d374a23201a
--- /dev/null
+++ 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).