You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/howto/debuggers.md
+144-4Lines changed: 144 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,10 +3,14 @@
3
3
4
4
# How to integrate a debugger
5
5
6
-
This guide explains how to use the {obj}`--debugger` flag to integrate a debugger
6
+
This guide explains how to integrate a debugger
7
7
with your Python applications built with `rules_python`.
8
8
9
-
## Basic Usage
9
+
There are two ways available: the {obj}`--debugger` flag, and the {any}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable.
10
+
11
+
## {obj}`--debugger` flag
12
+
13
+
### Basic Usage
10
14
11
15
The {obj}`--debugger` flag allows you to inject an extra dependency into `py_test`
12
16
and `py_binary` targets so that they have a custom debugger available at
@@ -32,7 +36,7 @@ The specified target must be in the requirements.txt file used with
32
36
`pip.parse()` to make it available to Bazel.
33
37
:::
34
38
35
-
## Python `PYTHONBREAKPOINT` Environment Variable
39
+
###Python `PYTHONBREAKPOINT` Environment Variable
36
40
37
41
For more fine-grained control over debugging, especially for programmatic breakpoints,
38
42
you can leverage the Python built-in `breakpoint()` function and the
@@ -52,7 +56,7 @@ PYTHONBREAKPOINT=pudb.set_trace bazel run \
52
56
53
57
For more details on `PYTHONBREAKPOINT`, refer to the [Python documentation](https://docs.python.org/3/library/functions.html#breakpoint).
54
58
55
-
## Setting a default debugger
59
+
###Setting a default debugger
56
60
57
61
By adding settings to your user or project `.bazelrc` files, you can have
58
62
these settings automatically added to your bazel invocations. e.g.
@@ -64,3 +68,139 @@ common --test_env=PYTHONBREAKPOINT=pudb.set_trace
64
68
65
69
Note that `--test_env` isn't strictly necessary. The `py_test` and `py_binary`
66
70
rules will respect the `PYTHONBREAKPOINT` environment variable in your shell.
71
+
72
+
## debugpy (e.g. vscode)
73
+
74
+
You can integrate `debugpy` (i.e. the debugger used in vscode or PyCharm) by using a launcher script. This method leverages {any}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` to inject the debugger into the Bazel-managed Python process.
75
+
76
+
For the remainder of this document, we assume you are using vscode.
1.**Create a launcher script**: Save the following Python script as `.vscode/debugpy/launch.py` (or another location, adjusting `launch.json` accordingly). This script bridges VS Code's debugger with Bazel.
82
+
83
+
<details>
84
+
<summary><code>launch.py</code></summary>
85
+
86
+
```python
87
+
"""
88
+
Launcher script for VS Code (debugpy).
89
+
90
+
This script is not managed by Bazel; it is invoked by VS Code's launch.json to
91
+
wrap the Bazel command, injecting the debugger into the runtime environment.
92
+
"""
93
+
94
+
import argparse
95
+
import os
96
+
import shlex
97
+
import subprocess
98
+
import sys
99
+
from typing import cast
100
+
101
+
defmain() -> None:
102
+
parser = argparse.ArgumentParser(description="Launch bazel debugpy with test or run.")
103
+
parser.add_argument("mode", choices=["test", "run"], help="Choose whether to run a bazel test or run.")
104
+
parser.add_argument("args", help="The bazel target to test or run (e.g., //foo:bar) and any additional args")
105
+
args = parser.parse_args()
106
+
107
+
# Import debugpy, provided by VS Code
108
+
try:
109
+
# debugpy._vendored is needed for force_pydevd to perform path manipulation.
"description": "Bazel target and arguments (e.g., //foo:bar --my-arg)"
199
+
}
200
+
]
201
+
}
202
+
```
203
+
</details>
204
+
205
+
Note: If you find `justMyCode` behavior is incompatible with Bazel's symlinks (causing breakpoints to be missed), you can set `"justMyCode": false` in `launch.json` and use the `IDE_PROJECT_ROOTS` environment variable (set to `"${workspaceFolder}"`) to explicitly map your workspace.
0 commit comments