From 7ff0c4d8c88027a2157df5e2e6c47ef647a2e614 Mon Sep 17 00:00:00 2001 From: tokiedokie Date: Fri, 11 Sep 2020 23:28:25 +0900 Subject: =?UTF-8?q?docs:=20move=20=E2=80=9CDebugger=E2=80=9D=20to=20?= =?UTF-8?q?=E2=80=9CDebugging=20your=20code=E2=80=9D=20in=20=E2=80=9CGetti?= =?UTF-8?q?ng=20started=E2=80=9D=20(#7421)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/getting_started.md | 1 + docs/getting_started/debugging_your_code.md | 145 ++++++++++++++++++++++++++++ docs/toc.json | 4 +- docs/tools.md | 1 - docs/tools/debugger.md | 145 ---------------------------- 5 files changed, 148 insertions(+), 148 deletions(-) create mode 100644 docs/getting_started/debugging_your_code.md delete mode 100644 docs/tools/debugger.md (limited to 'docs') diff --git a/docs/getting_started.md b/docs/getting_started.md index 2643a22ca..1da9147bb 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -10,3 +10,4 @@ In this chapter we'll discuss: - [Understanding permissions](./getting_started/permissions.md) - [Using Deno with TypeScript](./getting_started/typescript.md) - [Using WebAssembly](./getting_started/webassembly.md) +- [Debugging your code](./getting_started/debugging_your_code.md) diff --git a/docs/getting_started/debugging_your_code.md b/docs/getting_started/debugging_your_code.md new file mode 100644 index 000000000..920f55624 --- /dev/null +++ b/docs/getting_started/debugging_your_code.md @@ -0,0 +1,145 @@ +## Debugging your code + +Deno supports the [V8 Inspector Protocol](https://v8.dev/docs/inspector). + +It's possible to debug Deno programs using Chrome Devtools or other clients that +support the protocol (eg. VSCode). + +To activate debugging capabilities run Deno with the `--inspect` or +`--inspect-brk` flags. + +The `--inspect` flag allows attaching the debugger at any point in time, while +`--inspect-brk` will wait for the debugger to attach and will pause execution on +the first line of code. + +### Chrome Devtools + +Let's try debugging a program using Chrome Devtools. For this, we'll use +[file_server.ts](https://deno.land/std@$STD_VERSION/http/file_server.ts) from +`std`, a static file server. + +Use the `--inspect-brk` flag to break execution on the first line: + +```shell +$ deno run --inspect-brk --allow-read --allow-net https://deno.land/std@$STD_VERSION/http/file_server.ts +Debugger listening on ws://127.0.0.1:9229/ws/1e82c406-85a9-44ab-86b6-7341583480b1 +Download https://deno.land/std@$STD_VERSION/http/file_server.ts +Compile https://deno.land/std@$STD_VERSION/http/file_server.ts +... +``` + +Open `chrome://inspect` and click `Inspect` next to target: + +![chrome://inspect](../images/debugger1.jpg) + +It might take a few seconds after opening the Devtools to load all modules. + +![Devtools opened](../images/debugger2.jpg) + +You might notice that Devtools paused execution on the first line of +`_constants.ts` instead of `file_server.ts`. This is 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: + +![Open file_server.ts](../images/debugger3.jpg) + +_Looking closely you'll find duplicate entries for each file; one written +regularly and one in italics. The former is compiled source file (so in the case +of `.ts` files it will be emitted JavaScript source), while the latter is a +source map for the file._ + +Next, add a breakpoint in the `listenAndServe` method: + +![Break in file_server.ts](../images/debugger4.jpg) + +As soon as we've added the breakpoint Devtools automatically opened up the +source map file, which allows us step through the actual source code that +includes types. + +Now that we have our breakpoints set, we can resume the execution of our script +so that we might inspect an incoming request. Hit the Resume script execution +button to do so. You might even need to hit it twice! + +Once our script is running again, let's send a request and inspect it in +Devtools: + +``` +$ curl http://0.0.0.0:4500/ +``` + +![Break in request handling](../images/debugger5.jpg) + +At this point we can introspect the contents of the request and go step-by-step +to debug the code. + +### VSCode + +Deno can be debugged using VSCode. + +Official support via the plugin is being worked on - +https://github.com/denoland/vscode_deno/issues/12 + +We can still attach the debugger by manually providing a +[`launch.json`](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations) +config: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Deno", + "type": "pwa-node", + "request": "launch", + "cwd": "${workspaceFolder}", + "runtimeExecutable": "deno", + "runtimeArgs": ["run", "--inspect-brk", "-A", "${file}"], + "attachSimplePort": 9229 + } + ] +} +``` + +**NOTE**: This uses the file you have open as the entry point; replace `${file}` +with a script name if you want a fixed entry point. + +Let's try out debugging a local source file. Create `server.ts`: + +```ts +import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts"; +const server = serve({ port: 8000 }); +console.log("http://localhost:8000/"); + +for await (const req of server) { + req.respond({ body: "Hello World\n" }); +} +``` + +Then we can set a breakpoint, and run the created configuration: + +![VSCode debugger](../images/debugger7.jpg) + +### JetBrains IDEs + +You can debug Deno using your JetBrains IDE by right-clicking the file you want +to debug and selecting the `Debug 'Deno: '` option. This will create +a run/debug configuration with no permission flags set. To configure these flags +edit the run/debug configuration and modify the `Arguments` field with the +required flags. + +### Other + +Any client that implements the Devtools protocol should be able to connect to a +Deno process. + +### Limitations + +Devtools support is still immature. There is some functionality that is known to +be missing or buggy: + +- autocomplete in Devtools' console causes the Deno process to exit +- profiling and memory dumps might not work correctly diff --git a/docs/toc.json b/docs/toc.json index 626530a38..331629fcf 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -11,7 +11,8 @@ "command_line_interface": "Command line interface", "permissions": "Permissions", "typescript": "Using TypeScript", - "webassembly": "Using WebAssembly" + "webassembly": "Using WebAssembly", + "debugging_your_code": "Debugging your code" } }, "runtime": { @@ -45,7 +46,6 @@ "tools": { "name": "Tools", "children": { - "debugger": "Debugger", "script_installer": "Script installer", "formatter": "Formatter", "bundler": "Bundler", diff --git a/docs/tools.md b/docs/tools.md index 76f54e6bc..e64c9d840 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -4,7 +4,6 @@ Deno provides some built in tooling that is useful when working with JavaScript and TypeScript: - [bundler (`deno bundle`)](./tools/bundler.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) diff --git a/docs/tools/debugger.md b/docs/tools/debugger.md deleted file mode 100644 index 2a4c7f0d8..000000000 --- a/docs/tools/debugger.md +++ /dev/null @@ -1,145 +0,0 @@ -## Debugger - -Deno supports the [V8 Inspector Protocol](https://v8.dev/docs/inspector). - -It's possible to debug Deno programs using Chrome Devtools or other clients that -support the protocol (eg. VSCode). - -To activate debugging capabilities run Deno with the `--inspect` or -`--inspect-brk` flags. - -The `--inspect` flag allows attaching the debugger at any point in time, while -`--inspect-brk` will wait for the debugger to attach and will pause execution on -the first line of code. - -### Chrome Devtools - -Let's try debugging a program using Chrome Devtools. For this, we'll use -[file_server.ts](https://deno.land/std@$STD_VERSION/http/file_server.ts) from -`std`, a static file server. - -Use the `--inspect-brk` flag to break execution on the first line: - -```shell -$ deno run --inspect-brk --allow-read --allow-net https://deno.land/std@$STD_VERSION/http/file_server.ts -Debugger listening on ws://127.0.0.1:9229/ws/1e82c406-85a9-44ab-86b6-7341583480b1 -Download https://deno.land/std@$STD_VERSION/http/file_server.ts -Compile https://deno.land/std@$STD_VERSION/http/file_server.ts -... -``` - -Open `chrome://inspect` and click `Inspect` next to target: - -![chrome://inspect](../images/debugger1.jpg) - -It might take a few seconds after opening the Devtools to load all modules. - -![Devtools opened](../images/debugger2.jpg) - -You might notice that Devtools paused execution on the first line of -`_constants.ts` instead of `file_server.ts`. This is 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: - -![Open file_server.ts](../images/debugger3.jpg) - -_Looking closely you'll find duplicate entries for each file; one written -regularly and one in italics. The former is compiled source file (so in the case -of `.ts` files it will be emitted JavaScript source), while the latter is a -source map for the file._ - -Next, add a breakpoint in the `listenAndServe` method: - -![Break in file_server.ts](../images/debugger4.jpg) - -As soon as we've added the breakpoint Devtools automatically opened up the -source map file, which allows us step through the actual source code that -includes types. - -Now that we have our breakpoints set, we can resume the execution of our script -so that we might inspect an incoming request. Hit the Resume script execution -button to do so. You might even need to hit it twice! - -Once our script is running again, let's send a request and inspect it in -Devtools: - -``` -$ curl http://0.0.0.0:4500/ -``` - -![Break in request handling](../images/debugger5.jpg) - -At this point we can introspect the contents of the request and go step-by-step -to debug the code. - -### VSCode - -Deno can be debugged using VSCode. - -Official support via the plugin is being worked on - -https://github.com/denoland/vscode_deno/issues/12 - -We can still attach the debugger by manually providing a -[`launch.json`](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations) -config: - -```json -{ - "version": "0.2.0", - "configurations": [ - { - "name": "Deno", - "type": "pwa-node", - "request": "launch", - "cwd": "${workspaceFolder}", - "runtimeExecutable": "deno", - "runtimeArgs": ["run", "--inspect-brk", "-A", "${file}"], - "attachSimplePort": 9229 - } - ] -} -``` - -**NOTE**: This uses the file you have open as the entry point; replace `${file}` -with a script name if you want a fixed entry point. - -Let's try out debugging a local source file. Create `server.ts`: - -```ts -import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts"; -const server = serve({ port: 8000 }); -console.log("http://localhost:8000/"); - -for await (const req of server) { - req.respond({ body: "Hello World\n" }); -} -``` - -Then we can set a breakpoint, and run the created configuration: - -![VSCode debugger](../images/debugger7.jpg) - -### JetBrains IDEs - -You can debug Deno using your JetBrains IDE by right-clicking the file you want -to debug and selecting the `Debug 'Deno: '` option. This will create -a run/debug configuration with no permission flags set. To configure these flags -edit the run/debug configuration and modify the `Arguments` field with the -required flags. - -### Other - -Any client that implements the Devtools protocol should be able to connect to a -Deno process. - -### Limitations - -Devtools support is still immature. There is some functionality that is known to -be missing or buggy: - -- autocomplete in Devtools' console causes the Deno process to exit -- profiling and memory dumps might not work correctly -- cgit v1.2.3