The Starlark Debugger component manages starlark debug sessions.
There are three actors in the system:
- VSCode acts as the debug client that requests thread, stack frame, and variable information over the debug adapter protocol (DAP).
- Bazel is the debug server that sends thread, stack frame, and variable information over a protocol buffer based API.
bzl debug adaptercommand 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:
When clicked, three things are happening:
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.
A second integrated terminal is launched that invokes
bazel build --experimental_skylark_debug:
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.
VSCode starts a debug session, communicating over port
:4711with the debug adapter. In this scenario, a debug configuration was dynamically generated.
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:
launchconfiguration. In this scenario the bazel server and debug adapter are automatically run (as described in the code action scenario above).
attachconfiguration. In this scenario, you are responsible for starting up the server and adapter yourself.
To create a debug configuration, click on the debug settings "gear" icon:
[Add Configuration] button and scroll down to
Starlark Debug: Launch:
Fill in the bazel label that should be used when launching the bazel server process:
At this point, you can start a debug sesssion under this configuration by
manually choosing in the dropdown (or press
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.
attach is the preferred method if things aren't working correctly or you
need more control over starting the
Follow the same procedure to create an attach configuration, or enter it
manually in your
"debugServer": 4711 is the default and does not need to be explicitly provided.
Perform the following steps:
bzl debug adaptersomewhere. You can use the
Launchtree item in the component UI, or run the executable directly.
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
Start your bazel command using the
--experimental_skylark_debugflag. The server will block waiting for a client connection.
:::tip Use the
--experimental_skylark_debug_verbose_loggingflag to get extra info from the server. :::
Start a debug session with
F5using the attach configuration.
Be prepared to make trivial changes in file of interest to force bazel to re-evaluate the file.
Hovering over variables generally does not work.
Conditional breakpoints don't work.
You can only use
bazel buildfor debugging.
See https://www.youtube.com/watch?v=MAXJA8Gbtxk for a conference presentation on the debugger: