JDK-8227229 : Deprecate the launcher -Xdebug/-debug flags that have not done anything since Java 6
  • Type: Enhancement
  • Component: tools
  • Sub-Component: launcher
  • Affected Version: 14
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2019-07-03
  • Updated: 2023-07-27
  • Resolved: 2023-07-21
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 22
22 b08Fixed
Related Reports
CSR :  
Duplicate :  
Relates :  
Relates :  
Relates :  
Description
The Xdebug (and its alias -debug) launcher flag does nothing and is documented as existing "for backwards compatibility". The history is rather complex but fortunately it is summarized in JDK-6272174:

-------------------------------------------------------------------------------------
History, to the best of my memory --

(1) Long ago and far away

 -Xdebug used to mean use JVMDI
 -Djava.compiler=whatever was how you could specify a JIT compiler to run in the Classic VM
 -Djava.compiler=NONE was the Classic VM way of forcing interpreted execution and had to be used with -Xdebug because JVMDI ran in the interpreter

(2) HotSpot came along

 -Djava.compiler=whatever was meaningless and ignored, but,
 -Djava.compiler=NONE presumably so that the "-Xdebug -Djava.compiler=NONE" command line worked, was made the same as -Xint

(3) Then full-speed debugging came along

 Everybody's command line was still launching the debugee with "-Xdebug -Djava.compiler=NONE", so a horrible hack was added out of cautiousness:

 -Djava.compiler=NONE was left equal the same as -Xint, but was ignored if combined with -Xdebug *gag*

 Worse, I think this was me

(4) Then JVM TI came along (JDK5)

 -Xdebug now meant set up the internal JVMDI emulating JVM TI environment enabling all the JVMDI events, like breakpoint.
 There wasn't a JVMDI flag anymore, so the full-speed hack (3) was changed to check for breakpoints being enabled

(5) Then JVMDI was removed (JDK6)

 -Xdebug is now just ignored

 So, -Xdebug won't enable breakpoints.

---

So Xdebug has done nothing since JDK 6, but unfortunately continues to be referred to in relation to JDWP! This occurs in our own JDWP usage information:

 > java -Xrunjdwp:help
               Java Debugger JDWP Agent Library
               --------------------------------
...
Warnings
--------
  - The older -Xrunjdwp interface can still be used, but will be removed in
    a future release, for example:
        java -Xdebug -Xrunjdwp:[help]|[<option>=<value>, ...]

---

This then makes its way into other web documents e.g.

---
To run a regular serverless Java class Test with debugging enabled in the Oracle HotSpot JVM, you need to use the following command:

java -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=y Test

As you can see, you basically need only two JVM options: -Xdebug and -Xrunjdwp. Note that these are X-arguments, which means that they are not standardized and may not work as expected in other JVM implementations.

The -Xdebug argument enables the debugging itself, and the -Xrunjdwp argument configures the JDWP protocol with several important parameters. [1]
---
[1] https://stackify.com/java-remote-debugging/  (December 2017)

So I propose that we officially deprecate -Xdebug/-debug in 14 so that we can remove it in 15.

There are obviously multiple pieces to this and we need to update the JDWP usage information independent of this.
Comments
Changeset: 842d6329 Author: Jaikiran Pai <jpai@openjdk.org> Date: 2023-07-21 12:58:20 +0000 URL: https://git.openjdk.org/jdk/commit/842d6329cf5a3da8df7eddb195b5fcb7baadbdc3
21-07-2023

A pull request was submitted for review. URL: https://git.openjdk.org/jdk/pull/14918 Date: 2023-07-18 06:59:52 +0000
18-07-2023

The history is not quite accurate. The use of Xdebug to forestall -Xint mode remains in use: // This must be done after all arguments have been processed. // java_compiler() true means set to "NONE" or empty. if (java_compiler() && !xdebug_mode()) { // For backwards compatibility, we switch to interpreted mode if // -Djava.compiler="NONE" or "" is specified AND "-Xdebug" was // not specified. set_mode_flags(_int); } so it is not completely ignored despite being documented as doing nothing.
04-07-2019