Version: Next

Starlark Debugger

The Starlark Debugger component manages starlark debug sessions.

There are three actors in the system:

  1. VSCode acts as the debug client that requests thread, stack frame, and variable information over the debug adapter protocol (DAP).
  2. Bazel is the debug server that sends thread, stack frame, and variable information over a protocol buffer based API.
  3. The bzl debug adapter command acts as in intermediary between the two, translating between the DAP and protobuf schema.

Usage via "Code Action" Link

The debugger should work out of the box by clicking on a debug code action:

image

When clicked, three things are happening:

  1. The debug adapter is launched in an integrated terminal, listening on port :4711. You don't need to watch this, just know that it's there.

  2. A second integrated terminal is launched that invokes bazel build --experimental_skylark_debug:

    image

    Keep an eye on this terminal if things aren't working as expected. Most likely, the process exited because the starlark parsing/execution was incrementally cached; in that case the debugger will never hit your breakpoint.

  3. VSCode starts a debug session, communicating over port :4711 with the debug adapter. In this scenario, a debug configuration was dynamically generated.

Debug Configurations

Instead of using a dynamically-generated debug configuration, you may want to create a "static" configuration. This provides more control over the specifics of the debug session. You have two basic choices:

  1. A launch configuration. In this scenario the bazel server and debug adapter are automatically run (as described in the code action scenario above).

  2. An attach configuration. In this scenario, you are responsible for starting up the server and adapter yourself.

Launch Configuration

To create a debug configuration, click on the debug settings "gear" icon:

image

Click the [Add Configuration] button and scroll down to Starlark Debug: Launch:

image

Fill in the bazel label that should be used when launching the bazel server process:

image

{
"configurations": [
{
"type": "starlark",
"request": "launch",
"name": "Starlark debug //example/routeguide:routeguide_nodejs_library",
"targetLabel": "//example/routeguide:routeguide_nodejs_library"
}
]
}

At this point, you can start a debug sesssion under this configuration by manually choosing in the dropdown (or press F5):

image

note

When the bazel debug server is launched, the flags used on the command line are taken from the bsv.bazel.starlarkDebugFlags setting. You can add --experimental_skylark_debug_verbose_logging here, if desired.

image

Attach Configuration

Using attach is the preferred method if things aren't working correctly or you need more control over starting the bazel invocation.

Follow the same procedure to create an attach configuration, or enter it manually in your .vscode/launch.json file:

{
"configurations": [
{
"type": "starlark",
"request": "attach",
"name": "Attach to a running Starlark Debug Adapter",
"debugServer": 4711
}
]
}
note

"debugServer": 4711 is the default and does not need to be explicitly provided.

Perform the following steps:

  1. Launch the bzl debug adapter somewhere. You can use the Launch tree item in the component UI, or run the executable directly.

    caution

    When the debug adapter starts up, it runs a bazel query to prepare several files. If you already have a bazel invocation running, this can block. If this is an issue, run the adapter with --make_default_workspace_content=false.

  2. Start your bazel command using the --experimental_skylark_debug flag. The server will block waiting for a client connection.

    :::tip Use the --experimental_skylark_debug_verbose_logging flag to get extra info from the server. :::

  3. Start a debug session with F5 using the attach configuration.

Caveats

  1. Don't expect the starlark debug experience to be as nice as javascript debugging, for example. It's not as polished of a toolset.

  2. Be prepared to make trivial changes in file of interest to force bazel to re-evaluate the file.

  3. Hovering over variables generally does not work.

  4. Conditional breakpoints don't work.

  5. You can only use bazel build for debugging.

See https://www.youtube.com/watch?v=MAXJA8Gbtxk for a conference presentation on the debugger:

Edit this page