diff options
| -rw-r--r-- | docs/images/debugger1.jpg | bin | 0 -> 5532 bytes | |||
| -rw-r--r-- | docs/images/debugger2.jpg | bin | 0 -> 130599 bytes | |||
| -rw-r--r-- | docs/images/debugger3.jpg | bin | 0 -> 108836 bytes | |||
| -rw-r--r-- | docs/images/debugger4.jpg | bin | 0 -> 114528 bytes | |||
| -rw-r--r-- | docs/images/debugger5.jpg | bin | 0 -> 151098 bytes | |||
| -rw-r--r-- | docs/images/debugger6.jpg | bin | 0 -> 35964 bytes | |||
| -rw-r--r-- | docs/images/debugger7.jpg | bin | 0 -> 113573 bytes | |||
| -rw-r--r-- | docs/tools.md | 8 | ||||
| -rw-r--r-- | docs/tools/debugger.md | 130 |
9 files changed, 133 insertions, 5 deletions
diff --git a/docs/images/debugger1.jpg b/docs/images/debugger1.jpg Binary files differnew file mode 100644 index 000000000..176e971ab --- /dev/null +++ b/docs/images/debugger1.jpg diff --git a/docs/images/debugger2.jpg b/docs/images/debugger2.jpg Binary files differnew file mode 100644 index 000000000..5521d2da3 --- /dev/null +++ b/docs/images/debugger2.jpg diff --git a/docs/images/debugger3.jpg b/docs/images/debugger3.jpg Binary files differnew file mode 100644 index 000000000..7682d9bff --- /dev/null +++ b/docs/images/debugger3.jpg diff --git a/docs/images/debugger4.jpg b/docs/images/debugger4.jpg Binary files differnew file mode 100644 index 000000000..e8725123f --- /dev/null +++ b/docs/images/debugger4.jpg diff --git a/docs/images/debugger5.jpg b/docs/images/debugger5.jpg Binary files differnew file mode 100644 index 000000000..3cff06bb2 --- /dev/null +++ b/docs/images/debugger5.jpg diff --git a/docs/images/debugger6.jpg b/docs/images/debugger6.jpg Binary files differnew file mode 100644 index 000000000..e89346e5f --- /dev/null +++ b/docs/images/debugger6.jpg diff --git a/docs/images/debugger7.jpg b/docs/images/debugger7.jpg Binary files differnew file mode 100644 index 000000000..2b242a2e1 --- /dev/null +++ b/docs/images/debugger7.jpg diff --git a/docs/tools.md b/docs/tools.md index 904bf027f..2754de43b 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -6,12 +6,12 @@ and TypeScript: <!-- prettier-ignore-start --> <!-- prettier incorrectly moves the coming soon links to new lines --> -- [test runner (`deno test`)](./testing.md) -- [code formatter (`deno fmt`)](./tools/formatter.md) - [bundler (`deno bundle`)](./tools/bundler.md) -- [debugger (`--debug`)](./tools/debugger.md) -- [documentation generator (`deno doc`)](./tools/documentation_generator.md) +- [debugger (`--inspect, --inspect-brk`)](./tools/debugger.md) - [dependency inspector (`deno info`)](./tools/dependency_inspector.md) +- [documentation generator (`deno doc`)](./tools/documentation_generator.md) +- [formatter (`deno fmt`)](./tools/formatter.md) +- [test runner (`deno test`)](./testing.md) - linter (`deno lint`) [coming soon](https://github.com/denoland/deno/issues/1880) <!-- prettier-ignore-end --> diff --git a/docs/tools/debugger.md b/docs/tools/debugger.md index 626032d5f..f5ebd23c8 100644 --- a/docs/tools/debugger.md +++ b/docs/tools/debugger.md @@ -1,3 +1,131 @@ ## Debugger -<!-- TODO(lucacasonto): write things --> +Deno supports [V8 Inspector Protocol](https://v8.dev/docs/inspector). + +It is possible to debug Deno programs using Chrome Devtools or other clients +that support the protocol (eg. VSCode). + +To activate debugging capabilities run Deno with `--inspect` or `--inspect-brk` +flag. + +`--inspect` flag allows to attach debugger at any point in time, while +`--inspect-brk` will wait for debugger being attached and pause execution on the +first line of code. + +### Chrome Devtools + +Let's try debugging simple program using Chrome Devtools; for this purpose we'll +use [file_server.ts](https://deno.land/std@v0.50.0/http/file_server.ts) from +`std`; a simple static file server. + +Use `--inspect-brk` flag to break execution on the first line. + +```shell +$ deno run --inspect-brk https://deno.land/std@v0.50.0/http/file_server.ts +Debugger listening on ws://127.0.0.1:9229/ws/1e82c406-85a9-44ab-86b6-7341583480b1 +Download https://deno.land/std@v0.50.0/http/file_server.ts +Compile https://deno.land/std@v0.50.0/http/file_server.ts +... +``` + +Open `chrome://inspect` and click `Inspect` next to target: + + + +It might take a few seconds after opening the devtools to load all modules. + + + +You might notice that Devtools paused execution on the first line of +`_constants.ts` instead of `file_server.ts`. This is an expected behavior and is +caused by the way ES modules are evaluated by V8 (`_constants.ts` is left-most, +bottom-most dependency of `file_server.ts` so it is evaluated first). + +At this point all source code is available in the Devtools, so let's open up +`file_server.ts` and add a breakpoint there; go to "Sources" pane and expand the +tree: + + + +_Looking closesly you'll find duplicate entries for each file; one written +regularly and one in italics. The former is compiled source file (so in case of +`.ts` files it will be emitted JavaScript source), while the latter is a source +map for the file._ + +Add a breakpoint in `listenAndServe` method: + + + +As soon as we've added the breakpoint Devtools automatically opened up source +map file, which allows us step through the actual source code that includes +types. + +Let's send a request and inspect it in Devtools: + +``` +$ curl http://0.0.0.0:4500/ +``` + + + +At this point we can introspect contents of the request and go step-by-step to +debug the code. + +### VSCode + +Deno can be debugged using VSCode. + +Official support in plugin is being worked on - +https://github.com/denoland/vscode_deno/issues/12 + +We can still attach debugger by manually providing simple `launch.json` config: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Deno", + "type": "node", + "request": "launch", + "cwd": "${workspaceFolder}", + "runtimeExecutable": "deno", + "runtimeArgs": ["run", "--inspect-brk", "-A", "<entry_point>"], + "port": 9229 + } + ] +} +``` + +**NOTE**: Replace `<entry_point>` with actual script name. + +This time let's try with local source file, create `server.ts`: + +```ts +import { serve } from "https://deno.land/std@v0.50.0/http/server.ts"; +const s = serve({ port: 8000 }); +console.log("http://localhost:8000/"); + +for await (const req of s) { + req.respond({ body: "Hello World\n" }); +} +``` + +Change `<entry_point>` to `server.ts` and run created configuration: + + + + + +### Other + +Any client that implementes Devtools protocol should be able to connect to Deno +process. + +### Limitations + +Devtools support is still immature, there are some functionalities that are +known to be missing/buggy: + +- autocomplete in Devtools' Console causes Deno process to exit +- profiling and memory dumps might not work correctly |
