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)
This commit is contained in:
Vadim Macagon
parent
85702604c3
commit
762a5bbefa
3 changed files with 180 additions and 101 deletions
131
docs/tutorial/debugging-main-process-node-inspector.md
Normal file
131
docs/tutorial/debugging-main-process-node-inspector.md
Normal file
|
|
@ -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
|
||||||
34
docs/tutorial/debugging-main-process-vscode.md
Normal file
34
docs/tutorial/debugging-main-process-vscode.md
Normal file
|
|
@ -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
|
||||||
|
|
@ -1,115 +1,29 @@
|
||||||
# Debugging the Main Process
|
# Debugging the Main Process
|
||||||
|
|
||||||
The browser window DevTools can only debug the renderer process scripts (i.e.
|
The DevTools in an Electron browser window can only debug JavaScript that's
|
||||||
the web pages). In order to provide a way to debug the scripts from the main
|
executed in that window (i.e. the web pages). To debug JavaScript that's
|
||||||
process, Electron has provided the `--debug` and `--debug-brk` switches.
|
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
|
## 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]`
|
### `--debug=[port]`
|
||||||
|
|
||||||
When this switch is used Electron will listen for V8 debugger protocol
|
Electron will listen for V8 debugger protocol messages on the specified `port`,
|
||||||
messages on the `port`. The default `port` is `5858`.
|
an external debugger will need to connect on this port. The default `port` is
|
||||||
|
`5858`.
|
||||||
|
|
||||||
### `--debug-brk=[port]`
|
### `--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
|
- [Debugging the Main Process in VSCode](debugging-main-process-vscode.md)
|
||||||
$ git clone git@github.com:electron/electron-quick-start.git
|
- [Debugging the Main Process in node-inspector](debugging-main-process-node-inspector.md)
|
||||||
$ 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
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue