Skip to content

Commit d9c4ee7

Browse files
pcjpcj
authored
Initial launch docs (#79)
* Initial launch docs * Add doc images * bump to 1.3.0
1 parent e457942 commit d9c4ee7

File tree

3 files changed

+95
-13
lines changed

3 files changed

+95
-13
lines changed

‎CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Change Log
22

3+
## 1.3.0 (Oct 23 2021)
4+
5+
- Add starlark debug launch support.
6+
37
## 1.2.3 (Oct 19 2021)
48

59
- 2021-10-19 22:57:34 -0600 GitHub: Fix textdocumentdefinition for external labels (#284)

‎docs/debugging.md

Lines changed: 90 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -9,25 +9,103 @@ nav_order: 7
99

1010
<p></p>
1111

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

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

16-
<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">
20+
## Launch
1721

18-
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**.
19-
> You can also use the snippet `{ "type": "starlark", "request": "attach", "name": "Attach to a running Starlark Debug Adapter" }`)
22+
Although a `launch.json` configuration is not specifically required to start a
23+
debug session it is recommended to create one. Click on the "gear" icon in the
24+
debug activity panel, or run the **Open 'launch.json'** command.
2025

21-
<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">
26+
<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">
2227

23-
<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">
28+
Select **Starlark Debug: Launch** configuration snippet:
2429

25-
Click on a **debug** codelens to start a debugging session.
30+
<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">
2631

27-
<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">
32+
Edit the selected text to configure the bazel target:
2833

29-
The debug adapter should launch in a VSCode terminal window (you can also launch this manually in the explorer).
34+
<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">
3035

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

33-
<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">
38+
<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">
39+
40+
To start the debug session, press `F5` or click on associated **Run and Debug** configuration.
41+
42+
<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">
43+
44+
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.
45+
46+
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.
47+
48+
You will likely want to make manual changes to the `.bzl` file of interest while
49+
debugging to force bazel to re-evaluate that file and allow the debugger to
50+
pause the starlark thread on your breakpoint.
51+
52+
Also note that a different integrated terminal is running the `bzl debug
53+
adapter` command. This tool translates VSCode's debugging protocol into the
54+
`skylark_debugging.proto` format.
55+
56+
You can add additional bazel flags as shown below:
57+
58+
```json
59+
{
60+
"version": "0.2.0",
61+
"configurations": [
62+
{
63+
"type": "starlark",
64+
"request": "launch",
65+
"name": "Starlark debug //:buildifier",
66+
"targetLabel": "//:buildifier",
67+
"extraBazelFlags": [
68+
"--config=bzl"
69+
]
70+
}
71+
]
72+
}
73+
```
74+
75+
## Attach
76+
77+
To run an `attach` debug session, create a corresponding attach configuration:
78+
79+
```json
80+
{
81+
"type": "starlark",
82+
"request": "attach",
83+
"name": "Attach to a running Starlark Debug Adapter",
84+
"debugServer": 4711
85+
},
86+
```
87+
88+
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.
89+
90+
To launch the adapter, run `bzl debug adapter`, or launch it from the component activity panel:
91+
92+
<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">
93+
94+
This will start the debug adapter in an integrated terminal.
95+
96+
<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">
97+
98+
At this point, you'll need to manually run a `bazel build //something --experimental_skylark_debug` in the terminal of your choice.
99+
100+
Then, `F5` and start a debug session using the selected debug configuration.
101+
102+
## DEFAULT.WORKSPACE
103+
104+
When a debug session starts from a clean slate, the starlark interpreter starts by parsing your `WORKSPACE` file.
105+
106+
Internally, bazel adds extra content to the front and back of your workspace
107+
before actually slicing it into chunks (delimited by `load()` statements).
108+
109+
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.
110+
111+
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.

‎package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"name": "bazel-stack-vscode",
33
"displayName": "bazel-stack-vscode",
44
"description": "Bazel Support for Visual Studio Code",
5-
"version": "1.2.3",
5+
"version": "1.3.0",
66
"publisher": "StackBuild",
77
"license": "Apache-2.0",
88
"icon": "stackb-full.png",

0 commit comments

Comments
 (0)