bugs.js
====

A NodeJS library providing a unified interface to common debuggers (gdb, jdb, pdb, ...). It's meant for building developer tools (debug tools, IDEs, etc ...), built for Codebox

Supported debuggers

- gdb : c/c++ (and any native binaries really)
- jdb : java (and anything running on the JVM)
- pdb : python
- rdb : ruby
- Feel free to send Pull Requests for more

Right now we interface with the current debugger through their command line programs and smartly writing and reading from their stdout/stdin.

Install

:warning: Warning: bugs is not yet published to npm
``
npm install bugs
`

Examples

#### python with pdb

`js
var bugs = require('bugs');

// Use pdb to debug a python file
var dbg = bugs.pdb('./some_file.py');

// Debug "main" function
dbg.init()
.then(function() {
return dbg.break('main');
})
.then(function() {
// Run debugger
return dbg.run();
})
.then(function() {
// Get backtrace
return dbg.backtrace();
})
.then(function(trace) {
// Display trace & quit
console.log('trace =', trace)
return dbg.quit();
})
.done();
`

#### Native binaries with gdb

`js
var bugs = require('bugs');

// Use gdb to unix "ls" binary
var dbg = bugs.gdb('ls');

// Debug "main" function
dbg.init()
.then(function() {
return dbg.break('main');
})
.then(function() {
// Run "ls" on a given folder
return dbg.run('-al /tmp');
})
.then(function() {
// Get backtrace
return dbg.backtrace();
})
.then(function(trace) {
// Display trace & quit
console.log('trace =', trace)
return dbg.quit();
})
.done();
`

Commands

General

$3

Run file to debug with given args

$3

Restart program

$3

Quit current instance of the debugger (this isn't terribly useful)

Movement

$3

Run until current method returns.

$3

Execute and step into function

$3

Execute current instruction

$3

Keep running from here

$3

Run to the next line of the current function

$3

Move one level up in the stack trace

$3

Move one level down in the stack trace

Examination

$3

Evaluate a string of code and print the result

$3

Print backtrace of current stack

$3

List source code of current location

$3

Get local variables of current stack

$3

Get global variables

Breakpoints

$3

Lists currently set breakpoints

$3

Set a new breakpoint at location (location can be a line number, function address ...)

$3

Clear breakproint for location (see above for location)

Aliases

$3

Alias to run

$3

Alias to quit

Events

$3

Signals when the debugger is ready to receive commands.
.init() resolves when started` is emitted (you should probably use that).

$3

Provides updates when state of process changes. And updates not request or results of commands executed.