really nice job.
i have done the windows transport port, if you need.
you will face a small problem under windows, the debugger will send you
breakpoints in the for
C:\path\to\\the\debug/file.js
C (drive letter) in upper case
mix between / & \
Thanks for the excellent QuickJS project.
I spent the last couple days implementing for a QuickJS runtime debugger.
The debugger front end is VS Code. It supports all the features you'd
expect from a debugger: javascript breakpoints (and exception breakpoints),
evaluation, stepping, etc.
Fork of QuickJS with the necessary changes:
https://github.com/koush/quickjs
VSCode Extension:
https://github.com/koush/vscode-quickjs-debug
VSCode Marketplace Link:
https://marketplace.visualstudio.com/items?itemName=koush.quickjs-debug
Usage instructions are in the marketplace link. It will launch qjs with a
test.js script.
Technical details:
VS Code was chosen because it has a lightweight protocol that allows
piecemeal feature support. The Chrome debugger protocol was considered, but
it requires websockets and has a whole lot of other baggage. One could
potentially write a CLI client that uses the VS Code protocol.
The debugger code has been split into separate files.
quickjs.c:
Contains the necessary hooks and changes in the runtime. The changes are
nearly unintrusive. There's a few fields that were necessary on JSContext
and JSFunctionBytecode.
Most of the code lives at the bottom of the file. There are a number of
internal APIs necessary for the functional debugger: getting a list of
closure and local variables, dumping the stack frames, and evaluating an
expression at any stack frame. A roll up of the changes can be seen here:
https://github.com/koush/quickjs/compare/33c91ce2bc1c9422d32f5f26ccef56ff6b4d9bda..master#diff-8561242cf01b9394bd9d00e57a0f7db3
quickjs-debugger.c
This contains the debug session management and wire protocol to talk to VS
Code.
https://github.com/koush/quickjs/blob/master/quickjs-debugger.c
quickjs-debugger-transport-unix.c:
This is the default transport implementation that uses sockets. Other
transports could be swapped in by implementing the 5 transport_* functions.
https://github.com/koush/quickjs/blob/master/quickjs-debugger-transport-unix.c
Currently no windows transport is implemented, but I'll do that within the
next couple days.
Debugging embedded QuickJS notes:
Debugger connection initiation is done with
js_debugger_connect(JSContext *, const char *address)
Where <address> is the "address:port" value that will connect to the VS
Code extension waiting for incoming QuickJS debug sessions.
Connection initiation can also be done automatically by setting the
QUICKJS_DEBUG_ADDRESS environment variable to "address:port".
For example:
QUICKJS_DEBUG_ADDRESS=localhost:5555 ./qjs test.js
or
QUICKJS_DEBUG_ADDRESS=localhost:5555 ./my_program_with_qjs_embedded
I'd be happy to work with Fabrice and Charlie to get these changes in
quickjs.c approved, if possible. At the very least, the hooks necessary for
a debugger. Specifically, these functions need to live in quickjs.c due to
them needing to access internal data structures:
https://github.com/koush/quickjs/blob/master/quickjs-debugger.h#L63
Thanks. Feel free to open github issues for questions or help on getting
the debugger working in your project.
Koush
