diff --git a/docs/README.md b/docs/README.md index a8dac1a89..3d57dae0f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,11 +15,10 @@ - [Using NodeGui's APIs](tutorial/application-architecture.md#using-NodeGui-apis) - [Using Node.js APIs](tutorial/application-architecture.md#using-nodejs-apis) - [Using Native Node.js Modules](tutorial/using-native-node-modules.md) +- [Testing and Debugging](tutorial/debugging-app.md) + - [Debugging Qode/NodeGui Process](tutorial/debugging-qode-process.md) + - [Debugging a NodeGui app with Visual Studio Code](tutorial/debugging-app-vscode.md) // BOOK MARK - TODO AFTER THIS -- [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) - - [DevTools Extension](tutorial/devtools-extension.md) - [Distribution](tutorial/application-distribution.md) - [Supported Platforms](tutorial/support.md#supported-platforms) - [Code Signing](tutorial/code-signing.md) diff --git a/docs/tutorial/debugging-app-vscode.md b/docs/tutorial/debugging-app-vscode.md new file mode 100644 index 000000000..ef58c81cf --- /dev/null +++ b/docs/tutorial/debugging-app-vscode.md @@ -0,0 +1,38 @@ +# Debugging the App in VSCode + +### 1. Open an NodeGui project in VSCode. + +```sh +$ git clone git@github.com:nodegui/nodegui-starter.git +$ code nodegui-starter +``` + +### 2. Add a file `.vscode/launch.json` with the following configuration: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Debug Qode Process", + "type": "node", + "request": "launch", + "cwd": "${workspaceRoot}", + "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/qode", + "windows": { + "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/qode.exe" + }, + "args": ["./dist/index.js"], + "outputCapture": "std" + } + ] +} +``` + +**Tip** + +You could also configure a preLaunchTask for building typescript before launching the debugger everytime. + +### 3. Debugging + +Set some breakpoints in `index.js`, and start debugging in the [Debug View](https://code.visualstudio.com/docs/editor/debugging). You should be able to hit the breakpoints. diff --git a/docs/tutorial/debugging-app.md b/docs/tutorial/debugging-app.md new file mode 100644 index 000000000..fd9836b67 --- /dev/null +++ b/docs/tutorial/debugging-app.md @@ -0,0 +1,54 @@ +# Application Debugging + +Whenever your NodeGui application is not behaving the way you wanted it to, +an array of debugging tools might help you find coding errors, performance +bottlenecks, or optimization opportunities. + +Since a NodeGui application runs on Qode. And Qode is essentially Node.Js. We can consider a NodeGui app as a regular NodeJs app. Hence, you can use any debugging tool that you use with Node.Js +One of the most popular way of debugging a Node.Js app is by making use of the [Chromium Developer Tools][node-inspect]. + +Google offers [excellent documentation for their developer tools][devtools]. +We recommend that you make yourself familiar with them - they are usually one +of the most powerful utilities in any NodeGui Developer's tool belt. + +# Debugging Qode process + +To debug JavaScript that's executed in the Qode/Node process you will need to use an external debugger and +launch Qode with the `--inspect` or `--inspect-brk` switch. Once you run it you can open up Chrome and visit `chrome://inspect` where you should see your app listed. + +## Command Line Switches + +Use one of the following command line switches to enable debugging of the process: + +### `--inspect=[port]` + +Qode will listen for V8 inspector protocol messages on the specified `port`, +an external debugger will need to connect on this port. The default `port` is +`9229`. + +```shell +qode --inspect=9229 your/app +``` + +### `--inspect-brk=[port]` + +Like `--inspect` but pauses execution on the first line of JavaScript. + +**Note** + +If you are using the official boilerplate `nodegui-starter`, then you can achieve this by running + +``` +npm run debug +``` + +## External Debuggers + +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 NodeGui app present there. +- [Debugging the NodeGui app in VSCode](tutorial/debugging-app-vscode.md) + +[node-inspect]: https://nodejs.org/en/docs/inspector/ +[devtools]: https://developer.chrome.com/devtools