Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory
> On Apr 20, 2017, at 9:55 AM, Alan Bateman wrote: > > On 20/04/2017 17:47, Mandy Chung wrote: > >> In this case, which module should jdwp-protocol.html spec belong to? Not >> jdk.jdwp.agent then. >> The suggestion of the modular specs layout in the docs bundle may not apply. >> > jdwp-protocol.html is the JDWP protocol so it's implemented by both the > debugger and debugee. Typically the debugger sends a command and the debuggee > responds with a reply. There are also event messages that the target > VM/debuggee sends to the debugger. If there is place for Java SE > documentation then it might be best to put it there rather than trying to put > it in jdk.jdi or jdk.jdwp.agent. Agree. Magnus’s proposed patch to put jdwp-protocol.html in the spec/jdwp directory is fine. Mandy
Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory
On 20/04/2017 17:47, Mandy Chung wrote: In this case, which module should jdwp-protocol.html spec belong to? Not jdk.jdwp.agent then. The suggestion of the modular specs layout in the docs bundle may not apply. jdwp-protocol.html is the JDWP protocol so it's implemented by both the debugger and debugee. Typically the debugger sends a command and the debuggee responds with a reply. There are also event messages that the target VM/debuggee sends to the debugger. If there is place for Java SE documentation then it might be best to put it there rather than trying to put it in jdk.jdi or jdk.jdwp.agent. -Alan
Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory
> On Apr 20, 2017, at 9:32 AM, Alan Bateman wrote: > > > > On 20/04/2017 17:26, Mandy Chung wrote: >> JDI and JDWP are not Java SE and no need to handle that. >> > Just a small correction to this. The JDWP spec is Java SE. JDI is course > JDK-specific, as is the JDWP transport interface. Thanks for the correction. In this case, which module should jdwp-protocol.html spec belong to? Not jdk.jdwp.agent then. The suggestion of the modular specs layout in the docs bundle may not apply. Mandy
Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory
> On Apr 20, 2017, at 12:37 AM, Magnus Ihse Bursie > wrote: > > On 2017-04-20 01:11, Mandy Chung wrote: >>> On Apr 19, 2017, at 3:54 PM, Mandy Chung wrote: >>> >>> On Apr 19, 2017, at 5:36 AM, Magnus Ihse Bursie wrote: WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01 >>> 368 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html >> One more thing: jdwp-protocol belongs to jdk.jdwp.agent module. >> It would be nice if Gensrc-jdk.jdi.gmk can be cleaned up. > I agree that it would be nice if Gensrc-jdk.jdi.gmk can be cleaned up. > Unfortunately it's a bit tangled up right now, and a proper solution might be > too radical for this change. But let's see if we can sort this out, perhaps > with your module expertise a solution is possible. > > We need to gensrc three files: > 1) $(SUPPORT_OUTPUTDIR)/headers/jdk.jdwp.agent/JDWPCommands.h > 2) $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/com/sun/tools/jdi/JDWP.java > 3) $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html > > 1 and 2 are being created by the same call to the build tool, and 3 is > created by a separate call. I'm not sure if this is possible to change. It > looks like it might. > > 1 already belongs to jdk.jdwp.agent, and 3 could easily be moved there. The > problem is 2, which is needed when compiling the jdk.jdi module. > > I have two suggestions, but I don't know if either of them is possible: > 1) Move the JDWP.java file to jdk.jdwp.agent, and make sure it's properly > exported from jdk.jdwp.agent to jdk.jdi. (From my point of view, this seems > like the logical thing to do.) In this case, the entire gensrc:ing could move > to jdk.jdwp.agent, and possibly even into a single call to the build tool to > generate all three files. > As Alan said, JDWP.java is part of jdk.jdi. No need to be moved. > 2) Split the gensrc into one for jdk.jdwp.agent that generated 1 and 3, and > one for jdk.jdi that generates 2. It might require us to generate a dummy 2 > and 1 that are just thrown away, if the tool cannot be told not to generate > both 1 and 2 at the same time. I checked that build.tool.jdwpgen.Main can be invoked with -doc option only to generate 2 and it can be invoked separately with -include option to generate 1. Moving 1 and 3 to Gensrc-jdk.jdwp.agent.gmk seems like would work without change to the jdwpgen tool. Mandy
Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory
On 20/04/2017 17:26, Mandy Chung wrote: JDI and JDWP are not Java SE and no need to handle that. Just a small correction to this. The JDWP spec is Java SE. JDI is course JDK-specific, as is the JDWP transport interface. -Alan
Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory
> On Apr 20, 2017, at 12:21 AM, Magnus Ihse Bursie > wrote: > > > > On 2017-04-20 00:54, Mandy Chung wrote: >>> On Apr 19, 2017, at 5:36 AM, Magnus Ihse Bursie wrote: >>> >>> WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01 >> 368 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html >> 369 $(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \ >> 370 FILES := $(JDWP_PROTOCOL), \ >> 371 DEST := $(JAVADOC_OUTPUTDIR)/specs/jdwp, \ >> 372 )) >> >> Is there any reason why jdwp-protocol.html is not copied to the “specs” >> directory? > Yes, there is. This document is only part of the jdwp specification. This is > dynamically generated. The rest of the jdwp specification is static. I have a > prototype that, in light of JEP 299, copies the rest of the specification to > "specs/jdwp", but at the moment it's unclear if that's going to get into JDK > 9. Nevertheless, I think it is prudent to prepare for this structure. > Should the specs be organized with modular layout? e.g. docs/specs/$MODULE. In this case, it would be docs/specs/jdk.jdwp.agent. Jon - have you considered the specs be organized with modular layout? >> docs-docs-specs copies specs to jdk docs. I would expect there will be >> docs-javase-specs to copy specs from Java SE modules to javase-docs/specs >> but missing. > You mean docs-jdk-specs? Oops.. typo. > > While there is a superficial similarity between "docs-jdk" and "docs-javase", > there's a difference in purpose. The latter is only created for a > special-purpose formal API verification, and is not supposed to be shipped. > This means that it's not built by e.g. "docs-image". I assumed that only the > API would be needed for that. Some spec are Java SE such as JNI, JVM TI, JAR file spec that should be included when building "docs-javase" target. So copying of $MODULE/share/specs to $JAVADOC_OUTPUTDIR/specs should also be done for docs-javase but only the selected Java SE modules. JDI and JDWP are not Java SE and no need to handle that. I’m okay if you prefer separating “copying of Java SE specs" for “docs-javase” from this issue. Mandy
Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory
On 20/04/2017 08:37, Magnus Ihse Bursie wrote: : I have two suggestions, but I don't know if either of them is possible: 1) Move the JDWP.java file to jdk.jdwp.agent, and make sure it's properly exported from jdk.jdwp.agent to jdk.jdi. (From my point of view, this seems like the logical thing to do.) In this case, the entire gensrc:ing could move to jdk.jdwp.agent, and possibly even into a single call to the build tool to generate all three files. JDWP.java is the debugger side of the wire protocol and so jdk.jdi is the right module for this class. I haven't been following this thread closely but are you planning to move make/data/jdwp/jdwp.spec or the jdwpgen tool? If not then would it help if this tool were updated with an option to to just generate the source files for debugger or debuggee side rather than both? That seems to be your option #2 which I assume would mean running the tool twice. -Alan
Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory
On 2017-04-20 01:11, Mandy Chung wrote: On Apr 19, 2017, at 3:54 PM, Mandy Chung wrote: On Apr 19, 2017, at 5:36 AM, Magnus Ihse Bursie wrote: WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01 368 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html One more thing: jdwp-protocol belongs to jdk.jdwp.agent module. It would be nice if Gensrc-jdk.jdi.gmk can be cleaned up. I agree that it would be nice if Gensrc-jdk.jdi.gmk can be cleaned up. Unfortunately it's a bit tangled up right now, and a proper solution might be too radical for this change. But let's see if we can sort this out, perhaps with your module expertise a solution is possible. We need to gensrc three files: 1) $(SUPPORT_OUTPUTDIR)/headers/jdk.jdwp.agent/JDWPCommands.h 2) $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/com/sun/tools/jdi/JDWP.java 3) $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html 1 and 2 are being created by the same call to the build tool, and 3 is created by a separate call. I'm not sure if this is possible to change. It looks like it might. 1 already belongs to jdk.jdwp.agent, and 3 could easily be moved there. The problem is 2, which is needed when compiling the jdk.jdi module. I have two suggestions, but I don't know if either of them is possible: 1) Move the JDWP.java file to jdk.jdwp.agent, and make sure it's properly exported from jdk.jdwp.agent to jdk.jdi. (From my point of view, this seems like the logical thing to do.) In this case, the entire gensrc:ing could move to jdk.jdwp.agent, and possibly even into a single call to the build tool to generate all three files. 2) Split the gensrc into one for jdk.jdwp.agent that generated 1 and 3, and one for jdk.jdi that generates 2. It might require us to generate a dummy 2 and 1 that are just thrown away, if the tool cannot be told not to generate both 1 and 2 at the same time. /Magnus Mandy 369 $(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \ 370 FILES := $(JDWP_PROTOCOL), \ 371 DEST := $(JAVADOC_OUTPUTDIR)/specs/jdwp, \ 372 )) Is there any reason why jdwp-protocol.html is not copied to the “specs” directory? docs-docs-specs copies specs to jdk docs. I would expect there will be docs-javase-specs to copy specs from Java SE modules to javase-docs/specs but missing. Mandy
Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory
On 2017-04-20 00:54, Mandy Chung wrote: On Apr 19, 2017, at 5:36 AM, Magnus Ihse Bursie wrote: WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01 368 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html 369 $(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \ 370 FILES := $(JDWP_PROTOCOL), \ 371 DEST := $(JAVADOC_OUTPUTDIR)/specs/jdwp, \ 372 )) Is there any reason why jdwp-protocol.html is not copied to the “specs” directory? Yes, there is. This document is only part of the jdwp specification. This is dynamically generated. The rest of the jdwp specification is static. I have a prototype that, in light of JEP 299, copies the rest of the specification to "specs/jdwp", but at the moment it's unclear if that's going to get into JDK 9. Nevertheless, I think it is prudent to prepare for this structure. docs-docs-specs copies specs to jdk docs. I would expect there will be docs-javase-specs to copy specs from Java SE modules to javase-docs/specs but missing. You mean docs-jdk-specs? While there is a superficial similarity between "docs-jdk" and "docs-javase", there's a difference in purpose. The latter is only created for a special-purpose formal API verification, and is not supposed to be shipped. This means that it's not built by e.g. "docs-image". I assumed that only the API would be needed for that. /Magnus Mandy
Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory
> On Apr 19, 2017, at 3:54 PM, Mandy Chung wrote: > > >> On Apr 19, 2017, at 5:36 AM, Magnus Ihse Bursie wrote: >> >> WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01 > > 368 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html One more thing: jdwp-protocol belongs to jdk.jdwp.agent module. It would be nice if Gensrc-jdk.jdi.gmk can be cleaned up. Mandy > 369 $(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \ > 370 FILES := $(JDWP_PROTOCOL), \ > 371 DEST := $(JAVADOC_OUTPUTDIR)/specs/jdwp, \ > 372 )) > > Is there any reason why jdwp-protocol.html is not copied to the “specs” > directory? > > docs-docs-specs copies specs to jdk docs. I would expect there will be > docs-javase-specs to copy specs from Java SE modules to javase-docs/specs but > missing. > > Mandy
Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory
> On Apr 19, 2017, at 5:36 AM, Magnus Ihse Bursie wrote: > > WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01 368 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html 369 $(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \ 370 FILES := $(JDWP_PROTOCOL), \ 371 DEST := $(JAVADOC_OUTPUTDIR)/specs/jdwp, \ 372 )) Is there any reason why jdwp-protocol.html is not copied to the “specs” directory? docs-docs-specs copies specs to jdk docs. I would expect there will be docs-javase-specs to copy specs from Java SE modules to javase-docs/specs but missing. Mandy
Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory
Looks good. Nit: Javadoc.gmk:358-360 only indented 2 spaces for continuation. Same goes for 390-393, but you didn't actually touch those lines. /Erik On 2017-04-19 14:36, Magnus Ihse Bursie wrote: This patch will solve three issues that I (unfortunately) filed as separate issues, but that shares a common solution. The three issues are: JDK-8178038 Copy jdwp-protocol.html to proper location JDK-8178039 Copy jvmti.html to proper location JDK-8178316 Add JVM-MANAGEMENT-MIB.mib to jdk/src/java.management/share/specs/ This patch will also solve this in a general way, to start preparing for JDK-8177434 (Copy specifications from module specs directory to docs image). Bug descriptions: https://bugs.openjdk.java.net/browse/JDK-8178038 Copy jdwp-protocol.html to proper location After JDK-8172312, the copy of jvmti.html into docs/platform/jvmti will stick out like a sore thumb. It should be moved to the new location designed by JEP 299, in docs/specs. https://bugs.openjdk.java.net/browse/JDK-8178039 Copy jvmti.html to proper location After JDK-8172312, the copy of jvmti.html into docs/platform/jvmti will stick out like a sore thumb. It should be moved to the new location designed by JEP 299, in docs/specs. https://bugs.openjdk.java.net/browse/JDK-8178316 Add JVM-MANAGEMENT-MIB.mib to jdk/src/java.management/share/specs/ The file JVM-MANAGEMENT-MIB.mib have unfortunately been stored in the closed sources. This was an oversight, and it should be moved to open sources. The file will follow the new structure of JEP 299 and be put in java.management/share/specs/, and copied to docs/specs during build. WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01 /Magnus
