Split up debugging-main-process.md, add electron-inspector guide

- Move the debugging guides for VSCode and node-inspector into separate
  files.
- Add instructions for using electron-inspector to the node-inspector
  guide.
- Remove note in node-inspector guide about crashing when inspecting
  `process` (it was fixed a long time ago:
  https://github.com/nodejs/node-v0.x-archive/issues/8205)

diff --git a/docs/tutorial/debugging-main-process-node-inspector.md b/docs/tutorial/debugging-main-process-node-inspector.md
new file mode 100644 (file)
index 0000000..2c42ef3
--- /dev/null
+++ b/docs/tutorial/debugging-main-process-node-inspector.md
@@ -0,0 +1,131 @@
+# Debugging the Main Process in node-inspector
+
+[`node-inspector`][node-inspector] provides a familiar DevTools GUI that can
+be used in Chrome to debug Electron's main process, however, because
+`node-inspector` relies on some native Node modules they must be rebuilt to
+target the version of Electron you wish to debug. You can either rebuild
+the `node-inspector` dependencies yourself, or let
+[`electron-inspector`][electron-inspector] do it for you, both approaches are
+covered in this document.
+
+**Note**: At the time of writing the latest release of `node-inspector`
+(0.12.8) can't be rebuilt to target Electron 1.3.0 or later without patching
+one of its dependencies. If you use `electron-inspector` it will take care of
+this for you.
+
+
+## Use `electron-inspector` for Debugging
+
+### 1. Install the [node-gyp required tools][node-gyp-required-tools]
+
+### 2. Install [`electron-rebuild`][electron-rebuild], if you haven't done so already.
+
+```shell
+npm install electron-rebuild --save-dev
+```
+
+### 3. Install [`electron-inspector`][electron-inspector]
+
+```shell
+npm install electron-inspector --save-dev
+```
+
+### 4. Start Electron
+
+Launch Electron with the `--debug` switch:
+
+```shell
+electron --debug=5858 your/app
+```
+
+or, to pause execution on the first line of JavaScript:
+
+```shell
+electron --debug-brk=5858 your/app
+```
+
+### 5. Start electron-inspector
+
+On macOS / Linux:
+
+```shell
+node_modules/.bin/electron-inspector
+```
+
+On Windows:
+
+```shell
+node_modules\\.bin\\electron-inspector
+```
+
+`electron-inspector` will need to rebuild `node-inspector` dependencies on the
+first run, and any time you change your Electron version. The rebuild process
+may require an internet connection to download Node headers and libs, and may
+take a few minutes.
+
+### 6. Load the debugger UI
+
+Open http://127.0.0.1:8080/debug?ws=127.0.0.1:8080&port=5858 in the Chrome
+browser. You may have to click pause if starting with `--debug-brk` to force
+the UI to update.
+
+
+## Use `node-inspector` for Debugging
+
+### 1. Install the [node-gyp required tools][node-gyp-required-tools]
+
+### 2. Install [`node-inspector`][node-inspector]
+
+```bash
+$ npm install node-inspector
+```
+
+### 3. Install [`node-pre-gyp`][node-pre-gyp]
+
+```bash
+$ npm install node-pre-gyp
+```
+
+### 4. Recompile the `node-inspector` `v8` modules for Electron
+
+**Note:** Update the target argument to be your Electron version number
+
+```bash
+$ node_modules/.bin/node-pre-gyp --target=1.2.5 --runtime=electron --fallback-to-build --directory node_modules/v8-debug/ --dist-url=https://atom.io/download/atom-shell reinstall
+$ node_modules/.bin/node-pre-gyp --target=1.2.5 --runtime=electron --fallback-to-build --directory node_modules/v8-profiler/ --dist-url=https://atom.io/download/atom-shell reinstall
+```
+
+See also [How to install native modules][how-to-install-native-modules].
+
+### 5. Enable debug mode for Electron
+
+You can either start Electron with a debug flag like:
+
+```bash
+$ electron --debug=5858 your/app
+```
+
+or, to pause your script on the first line:
+
+```bash
+$ electron --debug-brk=5858 your/app
+```
+
+### 6. Start the [`node-inspector`][node-inspector] server using Electron
+
+```bash
+$ ELECTRON_RUN_AS_NODE=true path/to/electron.exe node_modules/node-inspector/bin/inspector.js
+```
+
+### 7. Load the debugger UI
+
+Open http://127.0.0.1:8080/debug?ws=127.0.0.1:8080&port=5858 in the Chrome
+browser. You may have to click pause if starting with `--debug-brk` to see the
+entry line.
+
+[electron-inspector]: https://github.com/enlight/electron-inspector
+[electron-rebuild]: https://github.com/electron/electron-rebuild
+[node-inspector]: https://github.com/node-inspector/node-inspector
+[node-pre-gyp]: https://github.com/mapbox/node-pre-gyp
+[node-gyp-required-tools]: https://github.com/nodejs/node-gyp#installation
+[how-to-install-native-modules]: using-native-node-modules.md#how-to-install-native-modules

diff --git a/docs/tutorial/debugging-main-process-vscode.md b/docs/tutorial/debugging-main-process-vscode.md
new file mode 100644 (file)
index 0000000..55b525a
--- /dev/null
+++ b/docs/tutorial/debugging-main-process-vscode.md
@@ -0,0 +1,34 @@
+# Debugging the Main Process in VSCode
+
+### 1. Open an Electron project in VSCode.
+
+```bash
+$ 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": "${workspaceRoot}",
+      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron",
+      "program": "${workspaceRoot}/main.js"
+    }
+  ]
+}
+```
+
+**Note:** For Windows, use `"${workspaceRoot}/node_modules/.bin/electron.cmd"` for `runtimeExecutable`.
+
+### 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 eea6a92..9bd8d21 100644 (file)
--- a/docs/tutorial/debugging-main-process.md
+++ b/docs/tutorial/debugging-main-process.md
@@ -1,115 +1,29 @@
 # Debugging the Main Process
 
-The browser window DevTools can only debug the renderer process scripts (i.e.
-the web pages). In order to provide a way to debug the scripts from the main
-process, Electron has provided the `--debug` and `--debug-brk` switches.
+The DevTools in an Electron browser window can only debug JavaScript that's
+executed in that window (i.e. the web pages). To debug JavaScript that's
+executed in the main process you will need to use an external debugger and
+launch Electron with the `--debug` or `--debug-brk` switch.
 
 ## Command Line Switches
 
-Use the following command line switches to debug Electron's main process:
+Use one of the following command line switches to enable debugging of the main
+process:
 
 ### `--debug=[port]`
 
-When this switch is used Electron will listen for V8 debugger protocol
-messages on the `port`. The default `port` is `5858`.
+Electron will listen for V8 debugger protocol messages on the specified `port`,
+an external debugger will need to connect on this port. The default `port` is
+`5858`.
 
 ### `--debug-brk=[port]`
 
-Like `--debug` but pauses the script on the first line.
+Like `--debug` but pauses execution on the first line of JavaScript.
 
-## Use VSCode for Debugging
+## External Debuggers
 
-### 1. Open an Electron project in VSCode.
+You will need to use a debugger that supports the V8 debugger protocol,
+the following guides should help you to get started:
 
-```bash
-$ 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": "${workspaceRoot}",
-      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron",
-      "program": "${workspaceRoot}/main.js"
-    }
-  ]
-}
-```
-
-**Note:** For Windows, use `"${workspaceRoot}/node_modules/.bin/electron.cmd"` for `runtimeExecutable`.
-
-### 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
-
-## Use node-inspector for Debugging
-
-**Note:** Electron doesn't currently work very well with node-inspector, and the
-main process will crash if you inspect the `process` object under
-node-inspector's console.
-
-### 1. Install the [node-gyp required tools][node-gyp-required-tools]
-
-### 2. Install [node-inspector][node-inspector]
-
-```bash
-$ npm install node-inspector
-```
-
-### 3. Install [node-pre-gyp][node-pre-gyp]
-
-```bash
-$ npm install node-pre-gyp
-```
-
-### 4. Recompile the `node-inspector` `v8` modules for Electron
-
-**Note:** Update the target argument to be your Electron version number
-
-```bash
-$ node_modules/.bin/node-pre-gyp --target=1.2.5 --runtime=electron --fallback-to-build --directory node_modules/v8-debug/ --dist-url=https://atom.io/download/atom-shell reinstall
-$ node_modules/.bin/node-pre-gyp --target=1.2.5 --runtime=electron --fallback-to-build --directory node_modules/v8-profiler/ --dist-url=https://atom.io/download/atom-shell reinstall
-```
-
-See also [How to install native modules][how-to-install-native-modules].
-
-### 5. Enable debug mode for Electron
-
-You can either start Electron with a debug flag like:
-
-```bash
-$ electron --debug=5858 your/app
-```
-
-or, to pause your script on the first line:
-
-```bash
-$ electron --debug-brk=5858 your/app
-```
-
-### 6. Start the [node-inspector][node-inspector] server using Electron
-
-```bash
-$ ELECTRON_RUN_AS_NODE=true path/to/electron.exe node_modules/node-inspector/bin/inspector.js
-```
-
-### 7. Load the debugger UI
-
-Open http://127.0.0.1:8080/debug?ws=127.0.0.1:8080&port=5858 in the Chrome
-browser. You may have to click pause if starting with `debug-brk` to see the
-entry line.
-
-[node-inspector]: https://github.com/node-inspector/node-inspector
-[node-pre-gyp]: https://github.com/mapbox/node-pre-gyp
-[node-gyp-required-tools]: https://github.com/nodejs/node-gyp#installation
-[how-to-install-native-modules]: using-native-node-modules.md#how-to-install-native-modules
+- [Debugging the Main Process in VSCode](debugging-main-process-vscode.md)
+- [Debugging the Main Process in node-inspector](debugging-main-process-node-inspector.md)