-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
3 changed files
with
40 additions
and
16 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,22 +1,28 @@ | ||
| <!DOCTYPE html> | ||
| <html xmlns="http://www.w3.org/1999/xhtml"><head><title>index (ppx_minidebug.index)</title><link rel="stylesheet" href="../_odoc_support/odoc.css"/><meta charset="utf-8"/><meta name="generator" content="odoc 2.2.0"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../_odoc_support/highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – ppx_minidebug</nav><header class="odoc-preamble"><h2 id="ppx_minidebug-usage"><a href="#ppx_minidebug-usage" class="anchor"></a><code>ppx_minidebug</code> usage</h2><p><code>ppx_minidebug</code> traces selected code if it has type annotations. <code>ppx_minidebug</code> offers three ways of instrumenting the code: <code>%debug_pp</code> and <code>%debug_show</code> based on <code>deriving.show</code>, and <code>%debug_sexp</code> based on the <code>sexplib</code>. The syntax extension expects a module <code>Debug_runtime</code> in the scope. <code>minidebug_runtime</code> offers three ways of logging the traces, as functors generating <code>Debug_runtime</code> modules given a file path.</p><p>Take a look at <a href="https://github.com/dariusf/ppx_debug"><code>ppx_debug</code></a> which is significantly more powerful!</p><p>See <a href="http://lukstafi.github.io/ppx_minidebug/minidebug_runtime/Minidebug_runtime/index.html"><code>Minidebug_runtime</code></a> for the provided loggers.</p></header><nav class="odoc-toc"><ul><li><a href="#usage">Usage</a></li><li><a href="#vs-code-suggestions">VS Code suggestions</a><ul><li><a href="#visualize-the-flame-graph-using-log-inspector">Visualize the flame graph using <em>Log Inspector</em></a></li><li><a href="#go-to-file-location-using-find-and-transform">Go to file location using <em>Find and Transform</em></a></li></ul></li></ul></nav><div class="odoc-content"><h3 id="usage"><a href="#usage" class="anchor"></a>Usage</h3><p>To trace a function, you have to type-annotate the function result. To trace an argument of a traced function, or a <code>let</code>-binding, you need to type-annotate it. You can control how much gets logged by adding or removing type annotations.</p><p>Tracing only happens in explicitly marked scopes, using the extension points: <code>%debug_pp</code>, <code>%debug_this_pp</code>, <code>%debug_show</code>, <code>%debug_this_show</code> (based on printing functionality provided by <code>deriving.show</code>), <code>%debug_sexp</code>, <code>%debug_this_sexp</code> (using functionality provided by <code>sexplib</code> and <code>ppx_sexp</code>). See examples in <a href="https://github.com/lukstafi/ppx_minidebug/tree/main/test">the test directory</a>.</p><p>The <code>%debug_this</code> variants are intended only for <code>let</code>-bindings: <code>let%debug_this v: t = compute value in body</code> will trace <code>v</code> and the type-annotated bindings and functions inside <code>compute value</code>, but it will not trace <code>body</code>.</p><p>Example setting up a logger printing to the screen:</p><pre class="language-ocaml"><code>module Debug_runtime = | ||
| <html xmlns="http://www.w3.org/1999/xhtml"><head><title>index (ppx_minidebug.index)</title><link rel="stylesheet" href="../_odoc_support/odoc.css"/><meta charset="utf-8"/><meta name="generator" content="odoc 2.2.0"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../_odoc_support/highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – ppx_minidebug</nav><header class="odoc-preamble"><h2 id="ppx_minidebug-usage"><a href="#ppx_minidebug-usage" class="anchor"></a><code>ppx_minidebug</code> usage</h2><p><code>ppx_minidebug</code> traces selected code if it has type annotations. <code>ppx_minidebug</code> offers three ways of instrumenting the code: <code>%debug_pp</code> and <code>%debug_show</code> based on <code>deriving.show</code>, and <code>%debug_sexp</code> based on the <code>sexplib</code>. The syntax extension expects a module <code>Debug_runtime</code> in the scope. <code>minidebug_runtime</code> offers three ways of logging the traces, as functors generating <code>Debug_runtime</code> modules given a file path.</p><p>Take a look at <a href="https://github.com/dariusf/ppx_debug"><code>ppx_debug</code></a> which is significantly more powerful!</p><p>See <a href="http://lukstafi.github.io/ppx_minidebug/minidebug_runtime/Minidebug_runtime/index.html"><code>Minidebug_runtime</code></a> for the provided loggers.</p></header><nav class="odoc-toc"><ul><li><a href="#usage">Usage</a></li><li><a href="#vs-code-suggestions">VS Code suggestions</a><ul><li><a href="#add-/-remove-type-annotations-and-visit-files-using-vocaml">Add / remove type annotations and visit files using <em>VOCaml</em></a></li><li><a href="#visualize-the-flame-graph-using-log-inspector">Visualize the flame graph using <em>Log Inspector</em></a></li><li><a href="#go-to-file-location-using-find-and-transform">Go to file location using <em>Find and Transform</em></a></li></ul></li></ul></nav><div class="odoc-content"><h3 id="usage"><a href="#usage" class="anchor"></a>Usage</h3><p>To trace a function, you have to type-annotate the function result. To trace an argument of a traced function, or a <code>let</code>-binding, you need to type-annotate it. You can control how much gets logged by adding or removing type annotations.</p><p>Tracing only happens in explicitly marked scopes, using the extension points: <code>%debug_pp</code>, <code>%debug_this_pp</code>, <code>%debug_show</code>, <code>%debug_this_show</code> (based on printing functionality provided by <code>deriving.show</code>), <code>%debug_sexp</code>, <code>%debug_this_sexp</code> (using functionality provided by <code>sexplib</code> and <code>ppx_sexp</code>). See examples in <a href="https://github.com/lukstafi/ppx_minidebug/tree/main/test">the test directory</a>.</p><p>The <code>%debug_this</code> variants are intended only for <code>let</code>-bindings: <code>let%debug_this v: t = compute value in body</code> will trace <code>v</code> and the type-annotated bindings and functions inside <code>compute value</code>, but it will not trace <code>body</code>.</p><p>Example setting up a logger printing to the screen:</p><pre class="language-ocaml"><code>module Debug_runtime = | ||
| Minidebug_runtime.Flushing(struct let debug_ch = stdout end) | ||
| let%debug_show test_logging: string = "Hello World"</code></pre><p>Example setting up a logger printing to a file:</p><pre class="language-ocaml"><code>module Debug_runtime = | ||
| Minidebug_runtime.Flushing( | ||
| Minidebug_runtime.Debug_ch(struct let filename = "debugger_flushing.log" end)) | ||
| let%debug_show test_logging: string = "Hello World"</code></pre><h3 id="vs-code-suggestions"><a href="#vs-code-suggestions" class="anchor"></a>VS Code suggestions</h3><h4 id="visualize-the-flame-graph-using-log-inspector"><a href="#visualize-the-flame-graph-using-log-inspector" class="anchor"></a>Visualize the flame graph using <em>Log Inspector</em></h4><p><a href="https://marketplace.visualstudio.com/items?itemName=lukstafi.loginspector-submillisecond">Log Inspector (sub-millisecond)</a>'s main feature is visualizing timestamped logs as flame graphs. To invoke it in VS Code, go to the <code>Minidebug_runtime.Flushing</code>-style logs file, press <em>crtl+shift+P</em>, and execute the command <em>Log Inspector: Draw</em>.</p><p>Note that <a href="https://marketplace.visualstudio.com/items?itemName=lukstafi.loginspector-submillisecond">Log Inspector (sub-millisecond)</a> is a forked variant of the Log Inspector extension.</p><h4 id="go-to-file-location-using-find-and-transform"><a href="#go-to-file-location-using-find-and-transform" class="anchor"></a>Go to file location using <em>Find and Transform</em></h4><p><a href="https://marketplace.visualstudio.com/items?itemName=ArturoDent.find-and-transform">Find and Transform</a> is a powerful VS Code extension, so there might be easier ways to accomplish this, but it gets the job done. I put the following in my `keybindings.json` file (command: <em>Open Keyboard Shortcuts (JSON)</em>):</p><pre class="language-json"><code>{ | ||
| let%debug_show test_logging: string = "Hello World"</code></pre><h3 id="vs-code-suggestions"><a href="#vs-code-suggestions" class="anchor"></a>VS Code suggestions</h3><h4 id="add-/-remove-type-annotations-and-visit-files-using-vocaml"><a href="#add-/-remove-type-annotations-and-visit-files-using-vocaml" class="anchor"></a>Add / remove type annotations and visit files using <em>VOCaml</em></h4><p><a href="https://marketplace.visualstudio.com/items?itemName=lukstafi.vocaml">VOCaml helpers for coding in OCaml</a> provide commands to add and remove annotations on selected bindings. They can be used to introduce logging, tune it, and cleanup afterward. It also has a command to populate the _Quick Open_ dialog with a file name and location from a line under cursor. It can be used to jump to the source code from a log file.</p><p>Note that you can add and remove type annotations using VSCode OCaml Platform's code actions, and the <em>Find and Transform</em> suggestion below is a more flexible go-to-file solution -- so VOCaml is somewhat redundant. But, it is still valuable: (1) it annotates multiple <code>let</code>-bindings at once in a selection, and (2) it annotates the argument types and the return type of a function (as required by <code>ppx_debug</code>) when invoked on a function definition.</p><h4 id="visualize-the-flame-graph-using-log-inspector"><a href="#visualize-the-flame-graph-using-log-inspector" class="anchor"></a>Visualize the flame graph using <em>Log Inspector</em></h4><p><a href="https://marketplace.visualstudio.com/items?itemName=lukstafi.loginspector-submillisecond">Log Inspector (sub-millisecond)</a>'s main feature is visualizing timestamped logs as flame graphs. To invoke it in VS Code, go to the <code>Minidebug_runtime.Flushing</code>-style logs file, press <em>crtl+shift+P</em>, and execute the command <em>Log Inspector: Draw</em>.</p><p>Note that <a href="https://marketplace.visualstudio.com/items?itemName=lukstafi.loginspector-submillisecond">Log Inspector (sub-millisecond)</a> is a forked variant of the Log Inspector extension.</p><h4 id="go-to-file-location-using-find-and-transform"><a href="#go-to-file-location-using-find-and-transform" class="anchor"></a>Go to file location using <em>Find and Transform</em></h4><p>This will expand your general-purpose VS Code toolbox!</p><p><a href="https://marketplace.visualstudio.com/items?itemName=ArturoDent.find-and-transform">Find and Transform</a> is a powerful VS Code extension. I put the following in my `keybindings.json` file (command: <em>Open Keyboard Shortcuts (JSON)</em>):</p><pre class="language-json"><code>{ | ||
| "key": "alt+q", | ||
| "command": "findInCurrentFile", | ||
| "args": { | ||
| "description": "Open file at cursor", | ||
| "find": "\"([^\"]+)\":([0-9]+)", | ||
| "replace": [ | ||
| "run": [ | ||
| "$${", | ||
| "vscode.commands.executeCommand('workbench.action.quickOpen', `$1:$2`);", | ||
| "return '\\\"$1\\\":$2';", | ||
| "const pos = new vscode.Position($2, 0);", | ||
| "const range = new vscode.Range(pos, pos);", | ||
| "const options = {selection: range};", | ||
| "const wsFolderUri = vscode.workspace.workspaceFolders[0].uri;", | ||
| "const uri = await vscode.Uri.joinPath(wsFolderUri, '$1');", | ||
| "await vscode.commands.executeCommand('vscode.open', uri, options);", | ||
|
|
||
| // "await vscode.commands.executeCommand('workbench.action.quickOpen', `$1:$2`);", | ||
| "}$$", | ||
| ], | ||
| "isRegex": true, | ||
| "restrictFind": "line", | ||
| } | ||
| }</code></pre><p>Then, pressing `alt+q` will open a pre-populated dialog, and `enter` will get me to the file location.</p></div></body></html> | ||
| }</code></pre><p>Then, pressing `alt+q` will open a pre-populated dialog, and `enter` will get me to the file location. The file-and-location detection above matches the default one from the <code>Flushing</code> module, you can adjust the <code>find</code> pattern to match other formats.</p></div></body></html> |