-## Debugger
+# Debugger
-V8 comes with an extensive debugger which is accessible out-of-process via a
-simple [TCP protocol](http://code.google.com/p/v8/wiki/DebuggerProtocol).
-Node has a built-in client for this debugger. To use this, start Node with the
-`debug` argument; a prompt will appear:
+ Stability: 2 - Stable
+
+<!-- type=misc -->
+
+Node.js includes a full-featured out-of-process debugging utility accessible
+via a simple [TCP-based protocol][] and built-in debugging client. To use it,
+start Node.js with the `debug` argument followed by the path to the script to
+debug; a prompt will be displayed indicating successful launch of the debugger:
% node debug myscript.js
< debugger listening on port 5858
3 debugger;
debug>
-Node's debugger client doesn't support the full range of commands, but
-simple step and inspection is possible. By putting the statement `debugger;`
-into the source code of your script, you will enable a breakpoint.
+Node.js's debugger client does not yet support the full range of commands, but
+simple step and inspection are possible.
-For example, suppose `myscript.js` looked like this:
+Inserting the statement `debugger;` into the source code of a script will
+enable a breakpoint at that position in the code.
+
+For example, suppose `myscript.js` is written as:
// myscript.js
x = 5;
setTimeout(function () {
debugger;
- console.log("world");
+ console.log('world');
}, 1000);
- console.log("hello");
+ console.log('hello');
-Then once the debugger is run, it will break on line 4.
+Once the debugger is run, a breakpoint will occur at line 4:
% node debug myscript.js
< debugger listening on port 5858
1 x = 5;
2 setTimeout(function () {
3 debugger;
- 4 console.log("world");
+ 4 console.log('world');
5 }, 1000);
debug> next
break in /home/indutny/Code/git/indutny/myscript.js:4
2 setTimeout(function () {
3 debugger;
- 4 console.log("world");
+ 4 console.log('world');
5 }, 1000);
- 6 console.log("hello");
+ 6 console.log('hello');
debug> repl
Press Ctrl + C to leave debug repl
> x
< world
break in /home/indutny/Code/git/indutny/myscript.js:5
3 debugger;
- 4 console.log("world");
+ 4 console.log('world');
5 }, 1000);
- 6 console.log("hello");
+ 6 console.log('hello');
7
debug> quit
%
-The `repl` command allows you to evaluate code remotely. The `next` command
-steps over to the next line. There are a few other commands available and more
-to come. Type `help` to see others.
+The `repl` command allows code to be evaluated remotely. The `next` command
+steps over to the next line. Type `help` to see what other commands are
+available.
-### Watchers
+## Watchers
-You can watch expression and variable values while debugging your code.
-On every breakpoint each expression from the watchers list will be evaluated
-in the current context and displayed just before the breakpoint's source code
-listing.
+It is possible to watch expression and variable values while debugging. On
+every breakpoint, each expression from the watchers list will be evaluated
+in the current context and displayed immediately before the breakpoint's
+source code listing.
-To start watching an expression, type `watch("my_expression")`. `watchers`
-prints the active watchers. To remove a watcher, type
-`unwatch("my_expression")`.
+To begin watching an expression, type `watch('my_expression')`. The command
+`watchers` will print the active watchers. To remove a watcher, type
+`unwatch('my_expression')`.
-### Commands reference
+## Commands reference
-#### Stepping
+### Stepping
* `cont`, `c` - Continue execution
* `next`, `n` - Step next
* `step`, `s` - Step in
* `out`, `o` - Step out
-* `pause` - Pause running code (like pause button in Developer TOols)
+* `pause` - Pause running code (like pause button in Developer Tools)
-#### Breakpoints
+### Breakpoints
* `setBreakpoint()`, `sb()` - Set breakpoint on current line
* `setBreakpoint(line)`, `sb(line)` - Set breakpoint on specific line
functions body
* `setBreakpoint('script.js', 1)`, `sb(...)` - Set breakpoint on first line of
script.js
-* `clearBreakpoint`, `cb(...)` - Clear breakpoint
+* `clearBreakpoint('script.js', 1)`, `cb(...)` - Clear breakpoint in script.js
+on line 1
+
+It is also possible to set a breakpoint in a file (module) that
+isn't loaded yet:
-#### Info
+ % ./node debug test/fixtures/break-in-module/main.js
+ < debugger listening on port 5858
+ connecting to port 5858... ok
+ break in test/fixtures/break-in-module/main.js:1
+ 1 var mod = require('./mod.js');
+ 2 mod.hello();
+ 3 mod.hello();
+ debug> setBreakpoint('mod.js', 23)
+ Warning: script 'mod.js' was not loaded yet.
+ 1 var mod = require('./mod.js');
+ 2 mod.hello();
+ 3 mod.hello();
+ debug> c
+ break in test/fixtures/break-in-module/mod.js:23
+ 21
+ 22 exports.hello = function() {
+ 23 return 'hello from module';
+ 24 };
+ 25
+ debug>
+
+### Info
* `backtrace`, `bt` - Print backtrace of current execution frame
* `list(5)` - List scripts source code with 5 line context (5 lines before and
breakpoint)
* `repl` - Open debugger's repl for evaluation in debugging script's context
-#### Execution control
+### Execution control
* `run` - Run script (automatically runs on debugger's start)
* `restart` - Restart script
* `kill` - Kill script
-#### Various
+### Various
* `scripts` - List all loaded scripts
-* `version` - Display v8's version
+* `version` - Display V8's version
+
+## Advanced Usage
-### Advanced Usage
+An alternative way of enabling and accessing the debugger is to start
+Node.js with the `--debug` command-line flag or by signaling an existing
+Node.js process with `SIGUSR1`.
-The V8 debugger can be enabled and accessed either by starting Node with
-the `--debug` command-line flag or by signaling an existing Node process
-with `SIGUSR1`.
+Once a process has been set in debug mode this way, it can be connected to
+using the Node.js debugger by either connecting to the `pid` of the running
+process or via URI reference to the listening debugger:
+* `node debug -p <pid>` - Connects to the process via the `pid`
+* `node debug <URI>` - Connects to the process via the URI such as
+localhost:5858
+[TCP-based protocol]: https://github.com/v8/v8/wiki/Debugging-Protocol
projects / platform / upstream / nodejs.git / blobdiff