Developing the Debugger

The nuclide debugger uses //Chrome Dev Tools// as the client UI, and plugs into various backends for debugging different languages.

Package Overview

Frontend (nuclide-debugger)

Location: pkg/nuclide-debugger/

The atom package which handles the interface and user interactions. Its core function is to load in an atom panel an iframe containing //Chrome Dev Tools// pointed at the websocket of an appropriate backend.

Chrome Dev Tools

Location: pkg/nuclide-debugger/VendorLib/devtools/

Our copy of //Chrome Dev Tools// is a snapshot of the devtools directory from the Blink repo.

LLDB Backend

Location: pkg/debugger-lldb/

The package exposes a service which can be called from another package to start up a debugger instance. The debugger instance is a python program which interfaces with LLDB via the python API, and with //Chrome Dev Tools// via a websocket server.

Backend Development Tips

Developing your backend with a browser

It's often faster to develop the debugger backend by running //Chrome Dev Tools// from your browser to avoid going through the Nuclide UI.

1. Starting a webserver to serve the //Chrome Dev Tools// snapshot:

(cd pkg/nuclide-debugger/VendorLib/devtools/; python -m SimpleHTTPServer)

2. Start the backend (here's the lldb backend, connecting to a running app named //Components//):

python pkg/nuclide-debugger-native-rpc/scripts/main.py --port=9000 -n Components

3. Point your browser at your webserver, and pass the location of the websocket as url param:

   http://localhost:8000/front_end/inspector.html?ws=localhost:9000/

Protocol

Basics

The basic paradigms consist of client initiated request-response and server notifications. Messages in the protocol are json encoded, and corresponds one-to-one with a websocket message.

Request-Response structure:

Request: { "id": number, "method": string, "params": object }

Response: { "id": number, "result": object, "error": string }

Error responses are surfaced as client JS errors.

Notification structure

{ "method": string, "params": object }

The protocol as understood by our snapshot of //Chrome Dev Tools//: pkg/nuclide-debugger/VendorLib/devtools/protocol.json

Quirks

//Chrome Dev Tools// is very closely tied to the server, and there are quirks in how the server should interact with the client which goes beyond what is specified in the protocol. These quirks are probably specific to particular versions of the client, and updates would likely bring new quirks.

Some traps for the fledgling debugger backend developer:

• The server must respond to Page.getResourceTree with something plausible, or the debugger doesn't finish initializing and most features will not work.
• Call stacks must refer to files which the client knows about. Otherwise, they are simply filtered out. Register files with the client using Debugger.scriptParsed event.