Developer's Guide

Ali Ijaz Sheikh edited this page Jan 10, 2015 · 5 revisions

Directory structure

The project follows the usual convention for node projects:

  • bin for executables
  • lib for implementation files
  • test for unit-tests
  • tools for helper scripts
  • front-end contains a snapshot of Blink's Developer Tools GUI
  • front-end-node contains Node Inspector files that are added to the GUI


The backend consist of several parts (all files are in lib).

  • Web server which handles browser requests, sends back front-end files and handles connections.

    Files: debug-server.js, session.js

  • Agents implement Developer Tools Protocol, which is used for communication between front-end and back-end. The protocol itself has a concept of agents, Node Inspector's agents are the same.

  • DebuggerClient.js, debugger.js and callback.js implement a client for V8 debugger protocol. The official protocol documentation is very incomplete. Alternative protocol documentation: bugger's

  • A lot of functionality is extracted into standalone classes, which makes it easier to test it in isolation.

    • convert.js implements conversions between types used by DevTools and V8 debugger.
    • BreakEventHandler handles the break event and prepares stack trace for the front-end with the help of CallFramesProvider.js
    • FrontendCommandHandler listens for front-end messages and dispatches them to Agents
    • ScriptManager keeps track of javascript files loaded in V8 runtime
    • ScriptFileStorage can load, save and list javascript source on disk

Reverse-engineering the front-end

The internal documentation for Blink Developer Tools front-end and protocol is quite often incomplete and you have to intercept the communication between DevTools and the backend in Chrome to understand how it works.

There are two tools to help:

  1. Enable protocol debug logs by starting the Node Inspector via the following command line. Node Inspector will dump all message to stdout/stderr.
$ DEBUG=node-inspector:protocol:* node-inspector

Alternatively, you can enable this.dumpInspectorProtocolMessages in front-end/InspectorBackend.js. All messages (requests, responses, events) will be logged to DevTools console.

  1. Run the front-end against the Chrome/Chromium back-end to see what does the "real" implementation do. See "Running" in Chrome Developer Tools documentation.

Upgrading the front-end

  1. Pick the Blink branch you would like to update to from list of all branches.

  2. Run tools/ {branch-number}.

  3. Review diffs to find out any breaking changes. Be prepared to spend possibly large amount of time to fix them all.

  4. Commit the updated front-end.

  5. Re-apply changes to front-end/inspector.html, commit the fixed version.

  6. Fix all problems found in step 3.

  7. Test basic scenarios (set breakpoint, step through code, inspect variables, live edit) to make sure they still work, fix any problems found.

  8. Submit a pull request.