Skip to content

Initial launch docs #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 24, 2021
Merged

Initial launch docs #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8ff1edf
Initial launch docs
pcj Oct 24, 2021
0633594
Add doc images
pcj Oct 24, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Change Log

## 1.3.0 (Oct 23 2021)

- Add starlark debug launch support.

## 1.2.3 (Oct 19 2021)

- 2021-10-19 22:57:34 -0600 GitHub: Fix textdocumentdefinition for external labels (#284)
Expand Down
102 changes: 90 additions & 12 deletions docs/debugging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,25 +9,103 @@ nav_order: 7

<p></p>

This extension supports debugging of Starlark (language mode: `bazel`) files. To use the debugger:
This extension supports debugging of Starlark files (language mode: `bazel`).

Make sure the "Starlark Debugger" component is enabled in the Explorer.
A debug session can be started using an `attach` or `launch` [debug
configuration](https://code.visualstudio.com/docs/editor/debugging). An
`attach` configuration provides the most control but requires you to start the
components independently, whereas a `launch` configuration will attempt to start
the debug adapter and bazel server for you.

<img width="573" alt="Screen Shot 2021-10-18 at 10 32 11 PM" src="https://user-images.githubusercontent.com/50580/137844816-72f4137e-dc23-4bcc-a369-f260dd1263af.png">
## Launch

Ensure you have a launch configuration in your `.vscode/launch.json` file. Use the "Add Configuration" and search for the one named **Attach to a running Starlark Debug Adapter**.
> You can also use the snippet `{ "type": "starlark", "request": "attach", "name": "Attach to a running Starlark Debug Adapter" }`)
Although a `launch.json` configuration is not specifically required to start a
debug session it is recommended to create one. Click on the "gear" icon in the
debug activity panel, or run the **Open 'launch.json'** command.

<img width="1597" alt="Screen Shot 2021-10-18 at 10 37 50 PM" src="https://user-images.githubusercontent.com/50580/137845082-90b187f5-7a78-4420-9890-ae8c5dd938b4.png">
<img width="1290" alt="Screen Shot 2021-10-23 at 9 38 13 PM" src="https://user-images.githubusercontent.com/50580/138579557-289b5649-7f26-4e46-b239-10516cfa0c54.png">

<img width="1597" alt="Screen Shot 2021-10-18 at 10 38 10 PM" src="https://user-images.githubusercontent.com/50580/137845090-2346b1db-2616-49fc-9b3b-1d0df8237b8f.png">
Select **Starlark Debug: Launch** configuration snippet:

Click on a **debug** codelens to start a debugging session.
<img width="1290" alt="Screen Shot 2021-10-23 at 9 38 21 PM" src="https://user-images.githubusercontent.com/50580/138579561-175271ad-fbee-49f7-bf30-9411ece2dece.png">

<img width="681" alt="Screen Shot 2021-10-18 at 10 35 41 PM" src="https://user-images.githubusercontent.com/50580/137844817-d25bf7d1-fe60-4108-9a26-de42ce36da2c.png">
Edit the selected text to configure the bazel target:

The debug adapter should launch in a VSCode terminal window (you can also launch this manually in the explorer).
<img width="1290" alt="Screen Shot 2021-10-23 at 9 38 33 PM" src="https://user-images.githubusercontent.com/50580/138579564-f7d493d7-aa56-484d-9eab-b015fc13d42c.png">

Another terminal window will be launched where bazel will be run in debug server mode.
This is bazel label that will be used when launching a `bazel build --experimental_skylark_debug` command.

<img width="1597" alt="Screen Shot 2021-10-18 at 10 39 49 PM" src="https://user-images.githubusercontent.com/50580/137845093-31b083fc-4a54-4389-b5dc-af4bd69fd947.png">
<img width="1290" alt="Screen Shot 2021-10-23 at 9 38 45 PM" src="https://user-images.githubusercontent.com/50580/138579565-cb095447-9347-4399-aba8-1f793b0f237d.png">

To start the debug session, press `F5` or click on associated **Run and Debug** configuration.

<img width="1290" alt="Screen Shot 2021-10-23 at 9 40 02 PM" src="https://user-images.githubusercontent.com/50580/138579566-4171e37a-1e95-49ef-b5da-36e208a10cde.png">

Note that the `bazel build //:buildifier --experimental_skylark_debug` has been started in an integrated VSCode terminal. You should keep an eye on this terminal.

For example, one reason that a debug session is immediately terminating is that the build files have already been parsed and remain cached by bazel's incrementality model.

You will likely want to make manual changes to the `.bzl` file of interest while
debugging to force bazel to re-evaluate that file and allow the debugger to
pause the starlark thread on your breakpoint.

Also note that a different integrated terminal is running the `bzl debug
adapter` command. This tool translates VSCode's debugging protocol into the
`skylark_debugging.proto` format.

You can add additional bazel flags as shown below:

```json
{
"version": "0.2.0",
"configurations": [
{
"type": "starlark",
"request": "launch",
"name": "Starlark debug //:buildifier",
"targetLabel": "//:buildifier",
"extraBazelFlags": [
"--config=bzl"
]
}
]
}
```

## Attach

To run an `attach` debug session, create a corresponding attach configuration:

```json
{
"type": "starlark",
"request": "attach",
"name": "Attach to a running Starlark Debug Adapter",
"debugServer": 4711
},
```

The `"debugServer": 4711` part is the default so it's not explicitly required. This is the TCP port VSCode will use to communicate with the debug adapter.

To launch the adapter, run `bzl debug adapter`, or launch it from the component activity panel:

<img width="1290" alt="Screen Shot 2021-10-23 at 10 01 56 PM" src="https://user-images.githubusercontent.com/50580/138580187-5e68a8ce-c61c-4908-9d89-4fc5d8253494.png">

This will start the debug adapter in an integrated terminal.

<img width="1290" alt="Screen Shot 2021-10-23 at 10 02 06 PM" src="https://user-images.githubusercontent.com/50580/138580191-6488cd46-20fa-47d2-8fea-188020aeeb3c.png">

At this point, you'll need to manually run a `bazel build //something --experimental_skylark_debug` in the terminal of your choice.

Then, `F5` and start a debug session using the selected debug configuration.

## DEFAULT.WORKSPACE

When a debug session starts from a clean slate, the starlark interpreter starts by parsing your `WORKSPACE` file.

Internally, bazel adds extra content to the front and back of your workspace
before actually slicing it into chunks (delimited by `load()` statements).

While the `/DEFAULT.WORKSPACE` and `/DEFAULT.WORKSPACE.SUFFIX` files only really exist in memory, for the sake of the debug experience, we can "fake" it by writing a mocks of these onto disk.

To prepare these files, run `bzl debug default_workspace_content`. They are hardcoded to reside at `${workspace}/.bazel-out/DEFAULT.WORKSPACE`. If you don't have the `.bazel-out/` symlinks, it might not work.
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "bazel-stack-vscode",
"displayName": "bazel-stack-vscode",
"description": "Bazel Support for Visual Studio Code",
"version": "1.2.3",
"version": "1.3.0",
"publisher": "StackBuild",
"license": "Apache-2.0",
"icon": "stackb-full.png",
Expand Down