Skip to content

Latest commit

 

History

History
138 lines (88 loc) · 7.37 KB

README.md

File metadata and controls

138 lines (88 loc) · 7.37 KB

Java No-Config Debug

This feature enables configuration-less debugging for Java applications, similar to the JavaScript Debug Terminal in VS Code.

How It Works

Once No-Config Debug initialization finishes, newly opened VS Code terminals receive the following environment contributions:

  • VSCODE_JDWP_ADAPTER_ENDPOINTS: Path to a communication file for port exchange
  • PATH: Includes the debugjava command wrapper

Note: JAVA_TOOL_OPTIONS is NOT set globally to avoid affecting other Java tools (javac, maven, gradle). Instead, it's set only when you run the debugjava command.

Startup readiness

The extension registers core Java Run/Debug support first, then starts No-Config Debug initialization in the background. Ordinary launch/attach registration and extension activation do not wait for endpoint storage, Java executable discovery, or wrapper permission preparation.

The AI debug_java_application entry is registered immediately. It observes the Java extension's serverReady() signal in the background, independently of terminal preparation. Invocation checks both states before inspecting launch inputs, probing Java, recording launch telemetry, building, creating a terminal, or stopping an existing debug session. It never waits for startup or queues a launch.

If JDT LS is not ready, the tool immediately returns JAVA_NOT_READY. If Java is ready but terminal preparation is incomplete, it returns NO_CONFIG_NOT_READY. Wait for the reported prerequisite before a new invocation; do not retry in a loop or treat readiness as a project-code error. Becoming ready does not automatically launch a previously refused request. Known Java or No-Config initialization failures, disabled integration, cancellation, and disposal return distinct explanations.

The existing javaLSReady tool visibility condition remains unchanged. Direct tool calls still receive explicit readiness feedback. Endpoint listeners remain eager rather than waiting for JDT LS, so surviving terminals can submit endpoints while Java starts. Directory preparation and startup cleanup run once per registration, not once per tool invocation.

This is not lazy terminal setup: preparation still starts during activation. However, activation completing does not guarantee that debugjava is ready. Terminals opened before preparation finishes may lack the environment contributions and must be recreated afterward. Existing terminals are not automatically closed or repaired.

On disposal, listeners are released immediately even if initialization is still pending. Already-started filesystem operations or Java extension activation are not forcibly cancelled, but their late completion cannot publish environment updates or register new listeners.

Disabling No-Config Debug

No-Config Debug is enabled by default. To opt out for all workspaces or just the current workspace, add this to the corresponding VS Code settings:

"java.debug.settings.enableNoConfigDebug": false

Reload VS Code and recreate existing terminals after changing this setting. The value is read once during extension activation; there is no live enable/disable switch. Existing terminal processes retain their old environment until they are recreated.

When disabled, the extension skips endpoint storage, file watching, Java executable detection, and wrapper permission setup, and removes this feature's cached terminal environment contributions. It does not clear the user's PATH or delete endpoint files as part of opting out. Standard Java launch/attach debugging, F5, and Run/Debug CodeLens are unaffected.

The AI debug_java_application tool requires this integration. When disabled, it returns instructions to enable the setting instead of building, launching a terminal, or stopping an existing debug session. Other AI tools for existing debug sessions remain available.

Usage

Basic Usage

Instead of running:

java -cp . com.example.Main

Simply run:

debugjava -cp . com.example.Main

The debugger will automatically attach, and breakpoints will work without any launch.json configuration!

Maven Projects

debugjava -jar target/myapp.jar

Gradle Projects

debugjava -jar build/libs/myapp.jar

With Arguments

debugjava -cp . com.example.Main arg1 arg2 --flag=value

Spring Boot

debugjava -jar myapp.jar --spring.profiles.active=dev

Advantages

  1. No Configuration Required: No need to create or maintain launch.json
  2. Rapid Prototyping: Perfect for quick debugging sessions
  3. Script Debugging: Debug applications launched by complex shell scripts
  4. Environment Consistency: Inherits all terminal environment variables
  5. Parameter Flexibility: Easy to change arguments using terminal history (↑ key)

How It Works Internally

  1. When you run debugjava, the wrapper script temporarily sets JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=0
  2. The wrapper determines which Java executable to use (priority order):
    • First: JAVA_HOME/bin/java if JAVA_HOME environment variable is set (user's explicit choice)
    • Second: VSCODE_JAVA_EXEC environment variable (Java path from VS Code's Java Language Server)
    • Third: java command from system PATH
  3. The wrapper launches the Java process with JDWP enabled
  4. JVM starts and outputs: "Listening for transport dt_socket at address: 12345"
  5. The wrapper captures the JDWP port from this output
  6. The port is written to a communication file
  7. VS Code's file watcher detects the file and automatically starts an attach debug session

The communication file is stored in the extension's workspace-specific VS Code storage directory, not its installation directory. It contains only the local debug host and port, is deleted after a successful attach, and any stale file is removed before the next registration. Its path remains stable across window reloads.

Troubleshooting

No-Config Debug Could Not Be Initialized

If the workspace storage directory or its file watcher cannot be initialized, the extension displays a warning and leaves standard Java launch/attach debugging available. No-Config Debug requires an open workspace and writable VS Code workspace storage.

After upgrading from a version that stored the communication file in the extension directory, recreate existing terminals to pick up the new endpoint path.

Port Already in Use

If you see "Address already in use", another Java debug session is running. Terminate it first.

No Breakpoints Hit

  1. Ensure you're running with debugjava command (not plain java)
  2. Check that the debugjava command is available: which debugjava (Unix) or Get-Command debugjava (PowerShell)
  3. Verify the terminal was opened after No-Config Debug initialization finished; recreate an early terminal if its environment is missing the contributions
  4. Check the Debug Console for error messages

Node.js Not Found

The wrapper script requires Node.js to be installed and available in PATH.

Limitations

  • Requires Node.js to be installed and available in PATH
  • Only works in terminals opened within VS Code
  • Requires using the debugjava command instead of java
  • The Java process will suspend (hang) until the debugger attaches

See Also