WIP

Author: hhugo

doc/dev/manual/debug.wiki

@@ -1,34 +1,117 @@
-= How to debug an OCaml program compiled to JavaScript.
+= Debugging
+
+This page explains how to debug OCaml programs compiled to JavaScript.
+
+== Compiler flags
 
-== Use the right compiler flags
 === OCaml flags
-Make sure to use {{{-g}}} flags when compiling and linking OCaml bytecode.
-Js_of_ocaml will attempt to preserve variable names.
+
+Use {{{-g}}} when compiling and linking OCaml bytecode. Js_of_ocaml will
+attempt to preserve variable names.
 
 === Js_of_ocaml flags
-  * {{{--pretty}}}     - format the generated JavaScript in a readable way and try to keep OCaml variable names.
-  * {{{--no-inline}}}  - prevent function inlining.
-  * {{{--debug-info}}} - annotate the JavaScript file with locations from the OCaml sources.
-  * {{{--source-map}}} - enable source-map support
 
-== JavaScript stacktrace
+|= Flag |= Description |
+| {{{--pretty}}} | Format JavaScript readably, preserve OCaml variable names |
+| {{{--no-inline}}} | Prevent function inlining |
+| {{{--debug-info}}} | Add source location comments |
+| {{{--source-map}}} | Generate source map |
+
+=== Dune configuration
+
+For development builds, add to your dune file:
+
+{{{
+(executable
+ (name main)
+ (modes js)
+ (js_of_ocaml (flags --pretty --source-map)))
+}}}
+
+== Source maps
+
+Source maps map generated JavaScript back to OCaml sources. With source maps
+enabled, you can set breakpoints, step through code, and inspect variables
+directly in your OCaml files.
+
+To enable source maps:
 
-See <<a_manual chapter="errors"|Error handling>> for details on attaching
-JavaScript stack traces to OCaml exceptions using {{{OCAMLRUNPARAM=b=1}}} or
-the {{{--enable with-js-error}}} compiler flag.
+{{{
+js_of_ocaml --source-map program.byte
+}}}
+
+This generates {{{program.js}}} and {{{program.js.map}}}.
 
 == Breakpoints
 
-Set breakpoints using browser developer tools (see https://developer.chrome.com/docs/devtools/javascript).
-Alternatively, set breakpoints programmatically by calling {{{Js.debugger ()}}}. Note that
-browsers only stop at breakpoints when developer tools are open.
+=== In browser developer tools
+
+Open browser developer tools (F12), navigate to the Sources panel, and set
+breakpoints in your OCaml files (when using source maps) or JavaScript files.
+
+See https://developer.chrome.com/docs/devtools/javascript for details.
+
+=== Programmatic breakpoints
+
+Insert breakpoints in your OCaml code:
+
+<<code language="ocaml"|
+let my_function x =
+  Js_of_ocaml.Js.debugger ();  (* Breaks here when devtools are open *)
+  x + 1
+>>
+
+Note: Browsers only pause at {{{debugger}}} statements when developer tools are open.
+
+== Debugging in Node.js
+
+=== Using --inspect
+
+Run your program with Node.js inspector:
+
+{{{
+node --inspect _build/default/main.bc.js
+}}}
+
+This prints a URL like:
+
+{{{
+Debugger listening on ws://127.0.0.1:9229/...
+}}}
+
+=== Chrome DevTools for Node.js
+
+1. Run {{{node --inspect}}} or {{{node --inspect-brk}}} (breaks on first line)
+2. Open Chrome and navigate to {{{chrome://inspect}}}
+3. Click "Open dedicated DevTools for Node"
+4. Your program appears in the Sources panel
+
+== Stack traces
+
+=== Attaching JavaScript backtraces
+
+To get JavaScript stack traces attached to OCaml exceptions:
+
+{{{
+OCAMLRUNPARAM=b=1 node program.js
+}}}
+
+Or compile with:
+
+{{{
+js_of_ocaml --enable with-js-error program.byte
+}}}
+
+See <<a_manual chapter="errors"|Error handling>> for details.
+
+== Chrome DevTools tips
+
+Useful settings in Chrome DevTools (Settings > Experiments):
+
+* **Display variable values inline while debugging** - Shows values next to variables
+* **Resolve variable names** - Maps minified names back to original names
 
-== Source map
-Source map is used to map the generated JavaScript code to original sources.
-After compiling with sourcemap enabled, using developers tools, one can set breakpoints,
-step through the code, and inspect variables directly in OCaml sources.
+== See also
 
-== About Chrome DevTools
-Useful settings for Chrome DevTools:
-* Display variable values inline while debugging
-* Resolve variable names (hidden DevTools Experiments, see https://developer.chrome.com/docs/devtools/settings/experiments)
+* <<a_manual chapter="errors"|Error handling>> - Exception handling between OCaml and JavaScript
+* <<a_manual chapter="options"|Command line options>> - Full list of compiler flags