Skip to content

Commit 994f3d4

Browse files
wenytang-mswenytang-ms
committed
feat: no config debug
1 parent 1be1fef commit 994f3d4

File tree

9 files changed

+583
-0
lines changed

9 files changed

+583
-0
lines changed

‎bundled/scripts/noConfigScripts/README.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Java No-Config Debug
2+
3+
This feature enables configuration-less debugging for Java applications, similar to the JavaScript Debug Terminal in VS Code.
4+
5+
## How It Works
6+
7+
When you open a terminal in VS Code with this extension installed, the following environment variables are automatically set:
8+
9+
- `JAVA_TOOL_OPTIONS`: Configured with JDWP to enable debugging on a random port
10+
- `VSCODE_JDWP_ADAPTER_ENDPOINTS`: Path to a communication file for port exchange
11+
- `PATH`: Includes the `javadebug` command wrapper
12+
13+
## Usage
14+
15+
### Basic Usage
16+
17+
Instead of running:
18+
```bash
19+
java -cp . com.example.Main
20+
```
21+
22+
Simply run:
23+
```bash
24+
javadebug -cp . com.example.Main
25+
```
26+
27+
The debugger will automatically attach, and breakpoints will work without any launch.json configuration!
28+
29+
### Maven Projects
30+
31+
```bash
32+
javadebug -jar target/myapp.jar
33+
```
34+
35+
### Gradle Projects
36+
37+
```bash
38+
javadebug -jar build/libs/myapp.jar
39+
```
40+
41+
### With Arguments
42+
43+
```bash
44+
javadebug -cp . com.example.Main arg1 arg2 --flag=value
45+
```
46+
47+
### Spring Boot
48+
49+
```bash
50+
javadebug -jar myapp.jar --spring.profiles.active=dev
51+
```
52+
53+
## Advantages
54+
55+
1. **No Configuration Required**: No need to create or maintain launch.json
56+
2. **Rapid Prototyping**: Perfect for quick debugging sessions
57+
3. **Script Debugging**: Debug applications launched by complex shell scripts
58+
4. **Environment Consistency**: Inherits all terminal environment variables
59+
5. **Parameter Flexibility**: Easy to change arguments using terminal history (↑ key)
60+
61+
## How It Works Internally
62+
63+
1. The extension sets `JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=0,quiet=y`
64+
2. When you run `javadebug`, it wraps the Java process
65+
3. The wrapper captures the JDWP port from JVM output: "Listening for transport dt_socket at address: 12345"
66+
4. The port is written to a communication file
67+
5. VS Code's file watcher detects the file and automatically starts an attach debug session
68+
69+
## Troubleshooting
70+
71+
### Port Already in Use
72+
73+
If you see "Address already in use", another Java debug session is running. Terminate it first.
74+
75+
### No Breakpoints Hit
76+
77+
1. Ensure you're running with `javadebug` command
78+
2. Check that JAVA_TOOL_OPTIONS is set in your terminal
79+
3. Verify the terminal was opened AFTER the extension activated
80+
81+
### Node.js Not Found
82+
83+
The wrapper script requires Node.js to be installed and available in PATH.
84+
85+
## Limitations
86+
87+
- Requires Node.js to be installed
88+
- Only works in terminals opened within VS Code
89+
- Cannot debug applications that override JAVA_TOOL_OPTIONS
90+
91+
## See Also
92+
93+
- [Debugger for Java Documentation](https://github.com/microsoft/vscode-java-debug)
94+
- [JDWP Documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/jpda/jdwp-spec.html)

‎bundled/scripts/noConfigScripts/TESTING.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Testing Java No-Config Debug
2+
3+
## Quick Test
4+
5+
1. **Create a simple Java file** (`HelloWorld.java`):
6+
7+
```java
8+
public class HelloWorld {
9+
public static void main(String[] args) {
10+
System.out.println("Starting application...");
11+
12+
String message = "Hello, World!";
13+
System.out.println(message); // Set a breakpoint here
14+
15+
for (int i = 0; i < 3; i++) {
16+
System.out.println("Count: " + i);
17+
}
18+
19+
System.out.println("Application finished.");
20+
}
21+
}
22+
```
23+
24+
2. **Compile it**:
25+
```bash
26+
javac HelloWorld.java
27+
```
28+
29+
3. **Set a breakpoint** on the line with `System.out.println(message);`
30+
31+
4. **Run with javadebug**:
32+
```bash
33+
javadebug HelloWorld
34+
```
35+
36+
5. **Result**:
37+
- The debugger should automatically attach
38+
- Execution should pause at your breakpoint
39+
- You can inspect variables, step through code, etc.
40+
41+
## Advanced Test - With Arguments
42+
43+
Create `EchoArgs.java`:
44+
45+
```java
46+
public class EchoArgs {
47+
public static void main(String[] args) {
48+
System.out.println("Arguments received: " + args.length);
49+
50+
for (int i = 0; i < args.length; i++) {
51+
System.out.println("Arg " + i + ": " + args[i]); // Breakpoint here
52+
}
53+
}
54+
}
55+
```
56+
57+
Compile and run:
58+
```bash
59+
javac EchoArgs.java
60+
javadebug EchoArgs arg1 arg2 "arg with spaces"
61+
```
62+
63+
## Test with JAR
64+
65+
Create a JAR with manifest:
66+
67+
```bash
68+
# Compile
69+
javac HelloWorld.java
70+
71+
# Create manifest
72+
echo "Main-Class: HelloWorld" > manifest.txt
73+
74+
# Create JAR
75+
jar cfm hello.jar manifest.txt HelloWorld.class
76+
77+
# Debug the JAR
78+
javadebug -jar hello.jar
79+
```
80+
81+
## Test Terminal History
82+
83+
One of the key benefits is easy parameter modification:
84+
85+
```bash
86+
# First run
87+
javadebug EchoArgs test1 test2
88+
89+
# Press ↑ to recall, modify and run again
90+
javadebug EchoArgs different parameters
91+
92+
# Press ↑ again, modify again
93+
javadebug EchoArgs yet another test
94+
```
95+
96+
This is much faster than editing launch.json each time!
97+
98+
## Verify Environment Variables
99+
100+
In your VS Code terminal, check that environment variables are set:
101+
102+
**Unix/Linux/macOS**:
103+
```bash
104+
echo $JAVA_TOOL_OPTIONS
105+
echo $VSCODE_JDWP_ADAPTER_ENDPOINTS
106+
which javadebug
107+
```
108+
109+
**Windows (PowerShell)**:
110+
```powershell
111+
$env:JAVA_TOOL_OPTIONS
112+
$env:VSCODE_JDWP_ADAPTER_ENDPOINTS
113+
Get-Command javadebug
114+
```
115+
116+
**Windows (CMD)**:
117+
```cmd
118+
echo %JAVA_TOOL_OPTIONS%
119+
echo %VSCODE_JDWP_ADAPTER_ENDPOINTS%
120+
where javadebug
121+
```
122+
123+
## Expected Output
124+
125+
When you run `javadebug`, you should see something like:
126+
127+
```
128+
Picked up JAVA_TOOL_OPTIONS: -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=0,quiet=y
129+
[Java Debug] Captured JDWP port: 54321
130+
[Java Debug] Wrote endpoint file: C:\...\endpoint-abc123.txt
131+
Starting application...
132+
```
133+
134+
Then VS Code should show:
135+
- Debug toolbar appears
136+
- Breakpoint icon turns solid red (was hollow)
137+
- Execution pauses at your breakpoint
138+
139+
## Common Issues
140+
141+
### Issue: "javadebug: command not found"
142+
143+
**Solution**:
144+
- Close and reopen your terminal
145+
- The extension must be activated first
146+
- Check that the extension is installed and enabled
147+
148+
### Issue: Debugger doesn't attach
149+
150+
**Solution**:
151+
- Check the Debug Console for errors
152+
- Verify JAVA_TOOL_OPTIONS is set
153+
- Try setting a breakpoint before running
154+
155+
### Issue: "Address already in use"
156+
157+
**Solution**:
158+
- Stop any existing debug sessions
159+
- Wait a few seconds and try again
160+
- The port from a previous session might still be bound
161+
162+
## Comparison with Traditional Debugging
163+
164+
### Traditional Way (with launch.json):
165+
166+
1. Create `.vscode/launch.json`
167+
2. Configure:
168+
```json
169+
{
170+
"type": "java",
171+
"name": "Debug HelloWorld",
172+
"request": "launch",
173+
"mainClass": "HelloWorld",
174+
"args": ["arg1", "arg2"]
175+
}
176+
```
177+
3. Press F5
178+
4. To change args: Edit launch.json, save, press F5
179+
180+
### No-Config Way:
181+
182+
1. Set breakpoint
183+
2. Run: `javadebug HelloWorld arg1 arg2`
184+
3. To change args: Press ↑, edit command, press Enter
185+
186+
**Much faster! 🚀**

‎bundled/scripts/noConfigScripts/javadebug‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
#!/bin/bash
2+
# Java No-Config Debug Wrapper Script for Unix/Linux/macOS
3+
# This script intercepts java commands and automatically enables JDWP debugging
4+
5+
# Export the endpoint file path for JDWP port communication
6+
export JDWP_ADAPTER_ENDPOINTS=$VSCODE_JDWP_ADAPTER_ENDPOINTS
7+
8+
# Get the directory of this script
9+
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
10+
11+
# Use Node.js wrapper to capture JDWP port
12+
exec node "$SCRIPT_DIR/jdwp-wrapper.js" "$@"

‎bundled/scripts/noConfigScripts/javadebug.bat‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
@echo off
2+
REM Java No-Config Debug Wrapper Script for Windows
3+
REM This script intercepts java commands and automatically enables JDWP debugging
4+
5+
REM Export the endpoint file path for JDWP port communication
6+
set JDWP_ADAPTER_ENDPOINTS=%VSCODE_JDWP_ADAPTER_ENDPOINTS%
7+
8+
REM Use Node.js wrapper to capture JDWP port
9+
node "%~dp0jdwp-wrapper.js" %*

‎bundled/scripts/noConfigScripts/javadebug.fish‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
#!/usr/bin/env fish
2+
# Java No-Config Debug Wrapper Script for Fish Shell
3+
# This script intercepts java commands and automatically enables JDWP debugging
4+
5+
# Export the endpoint file path for JDWP port communication
6+
set -x JDWP_ADAPTER_ENDPOINTS $VSCODE_JDWP_ADAPTER_ENDPOINTS
7+
8+
# Get the directory of this script
9+
set script_dir (dirname (status -f))
10+
11+
# Use Node.js wrapper to capture JDWP port
12+
exec node "$script_dir/jdwp-wrapper.js" $argv

‎bundled/scripts/noConfigScripts/javadebug.ps1‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Java No-Config Debug Wrapper Script for PowerShell
2+
# This script intercepts java commands and automatically enables JDWP debugging
3+
4+
# Export the endpoint file path for JDWP port communication
5+
$env:JDWP_ADAPTER_ENDPOINTS = $env:VSCODE_JDWP_ADAPTER_ENDPOINTS
6+
7+
# Get the directory of this script
8+
$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
9+
10+
# Use Node.js wrapper to capture JDWP port
11+
& node (Join-Path $scriptDir "jdwp-wrapper.js") $args

0 commit comments

Comments
 (0)