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/

Chrome Dev Tools

We are moving away from the Chrome Dev Tools to our own UI and model, but will retain loose compatibility with them until the transition is complete.

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

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

Backend Development Tips

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.