From 762a5bbefa4ed875043a34d672c1c7de6292f35d Mon Sep 17 00:00:00 2001 From: Vadim Macagon Date: Wed, 21 Sep 2016 16:39:15 +0700 Subject: [PATCH] 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) --- .../debugging-main-process-node-inspector.md | 131 +++++++++++++++++++++ docs/tutorial/debugging-main-process-vscode.md | 34 ++++++ docs/tutorial/debugging-main-process.md | 116 +++--------------- 3 files changed, 180 insertions(+), 101 deletions(-) create mode 100644 docs/tutorial/debugging-main-process-node-inspector.md create mode 100644 docs/tutorial/debugging-main-process-vscode.md diff --git a/docs/tutorial/debugging-main-process-node-inspector.md b/docs/tutorial/debugging-main-process-node-inspector.md new file mode 100644 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 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 --- 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) -- 2.7.4