Re: RFR: JDK-8175036 All API docs should be built for HTML 5

[Martin Buchholz]

There would be a global cleanup involved for --doclint-format html5
A CSS expert can probably suggest replacements.

[javac] ... src/main/java/util/Deque.java:30: error: attribute border
for table only accepts "" or "1", use CSS instead: BORDER
[javac]  * 


On Thu, Apr 20, 2017 at 3:42 PM, Jonathan Gibbons <
jonathan.gibb...@oracle.com> wrote:

> We probably want to set
>
> --doclint-format html5
>
> for javac as well, for the benefit of compilations that run doclint.
>
> -- Jon
>
>
>
> On 4/20/17 3:20 PM, Magnus Ihse Bursie wrote:
>
>> We should switch all uses of the javadoc tool to generate documentation
>> in HTML 5, using the -html5 option.
>>
>> Bug: https://bugs.openjdk.java.net/browse/JDK-8175036
>> Patch inline:
>> diff --git a/make/Javadoc.gmk b/make/Javadoc.gmk
>> --- a/make/Javadoc.gmk
>> +++ b/make/Javadoc.gmk
>> @@ -84,7 +84,7 @@
>>  # The initial set of options for javadoc
>>  JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords
>> -notimestamp \
>>  -serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex --system
>> none \
>> ---expand-requires transitive
>> +-html5 --expand-requires transitive
>>
>>  # Should we add DRAFT stamps to the generated javadoc?
>>  ifeq ($(VERSION_IS_GA), true)
>>
>> /Magnus
>>
>
>

Re: RFR: JDK-8175036 All API docs should be built for HTML 5

[Jonathan Gibbons]

We probably want to set

--doclint-format html5

for javac as well, for the benefit of compilations that run doclint.

-- Jon


On 4/20/17 3:20 PM, Magnus Ihse Bursie wrote:
We should switch all uses of the javadoc tool to generate 
documentation in HTML 5, using the -html5 option.


Bug: https://bugs.openjdk.java.net/browse/JDK-8175036
Patch inline:
diff --git a/make/Javadoc.gmk b/make/Javadoc.gmk
--- a/make/Javadoc.gmk
+++ b/make/Javadoc.gmk
@@ -84,7 +84,7 @@
 # The initial set of options for javadoc
 JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords 
-notimestamp \
 -serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex 
--system none \

---expand-requires transitive
+-html5 --expand-requires transitive

 # Should we add DRAFT stamps to the generated javadoc?
 ifeq ($(VERSION_IS_GA), true)

/Magnus

Re: Please review: JDK-8178725: provide way to link to external documentation

[Kumar Srinivasan]

Thanks for all the comments and feed back, I will go with what we have,
for now, likely its not the last time we will be touching this before 
jdk9 is done.


Kumar


On 2017-04-20 20:02, Jonathan Gibbons wrote:

David, Magnus,

Yes, this is somewhat Oracle-specific (more accurately it is 
JDK-specific, which is why this is a proposed to be a JDK build-time 
taglet, and not a standard tag in the standard doclet), but it is no 
worse than the explicit Oracle-specific URLs that have been used up 
to now, or the relative links using {@docRoot}/../stuff  which assume 
that "stuff " is available nearby somehow.  I would also go further 
and say this is better that the existing methodology because it 
abstracts all the linking to a single taglet, removing it from inline 
in the doc comments. 
I agree, it's in no way worse than what already existed. But it shed 
light on the somewhat unclear division between online Oracle 
documentation and OpenJDK documentation.


Just to be clear: I do not oppose the fix. It looks good to me.

If anything, there was a bit of a clash between on the one hand 
providing a means for overriding the URL, but on the other hand not 
really making it as general as it could be. Either removing the 
possibility to override it (and, as you say, let an alternative 
implementation change the code of the taglet itself), or as Roger 
suggest, using a more general mechanism like MessageFormat would have 
the code make slightly more sense. The simplest way is probably to 
skip the property override, which doesn't get used anyhow right now 
(and therefore suspect according to "if you don't test it, it is (or 
will become) broken").


/Magnus

Yes, the currently proposed taglet may assume the existence of  
single "base URL", but anyone with an alternate implementation of 
OpenJDK could change the impl of the taglet to use any other 
mechanism to establish the link. Doing a "strings in switch" on the 
identifier to select a URL comes to mind, and avoids anyone having to 
edit the main source doc comments.


-- Jon



On 04/19/2017 01:37 PM, David Holmes wrote:

On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:


We could potentially make the default URL to be "some" cgi url,
and have the build system specify the  URL all the time, in our
case it would be the Oracle documentation URL.

Would this be an acceptable approach ?


I'm not sure what you mean. I have a hard time seeing how a simple 
identifier (that will be fixed in the file using the taglet) can be 
attached to an arbitrary URL to yield a valid result. As Magnus 
said, being able to change the URL is good, but it still requires 
the same "kind" of URL where the identifier is used as a key.


Imagine you have all the documentation locally on your machine then 
try to figure out how you could link to other local documentation 
using this scheme.


David


Kumar


On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:

On 2017-04-18 19:44, Kumar Srinivasan wrote:

Hello,

As explained in the JBS issue [1], this new taglet enables API
documents
to contain the extLink tag to link external sources.

Please review the webrev [2].

Changes looks good.

Just a reflection: This is heavily biased to Oracle 
documentation. Even
if it's possible to override the URL via a system property, it 
assumes
the Oracle URL format and id name. Just wondering a bit how that 
fits

with the OpenJDK philosophy.


I have to agree, this is not at all general purpose but totally 
Oracle

documentation centric.

David
-



/Magnus



Thanks
Kumar

[1] https://bugs.openjdk.java.net/browse/JDK-8178725
[2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/

RFR: JDK-8175036 All API docs should be built for HTML 5

[Magnus Ihse Bursie]

We should switch all uses of the javadoc tool to generate documentation 
in HTML 5, using the -html5 option.


Bug: https://bugs.openjdk.java.net/browse/JDK-8175036
Patch inline:
diff --git a/make/Javadoc.gmk b/make/Javadoc.gmk
--- a/make/Javadoc.gmk
+++ b/make/Javadoc.gmk
@@ -84,7 +84,7 @@
 # The initial set of options for javadoc
 JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords 
-notimestamp \
 -serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex 
--system none \

---expand-requires transitive
+-html5 --expand-requires transitive

 # Should we add DRAFT stamps to the generated javadoc?
 ifeq ($(VERSION_IS_GA), true)

/Magnus

Re: Please review: JDK-8178725: provide way to link to external documentation

[Jonathan Gibbons]

On 4/20/17 2:53 PM, Magnus Ihse Bursie wrote:

On 2017-04-20 20:02, Jonathan Gibbons wrote:

David, Magnus,

Yes, this is somewhat Oracle-specific (more accurately it is 
JDK-specific, which is why this is a proposed to be a JDK build-time 
taglet, and not a standard tag in the standard doclet), but it is no 
worse than the explicit Oracle-specific URLs that have been used up 
to now, or the relative links using {@docRoot}/../stuff  which assume 
that "stuff " is available nearby somehow.  I would also go further 
and say this is better that the existing methodology because it 
abstracts all the linking to a single taglet, removing it from inline 
in the doc comments. 
I agree, it's in no way worse than what already existed. But it shed 
light on the somewhat unclear division between online Oracle 
documentation and OpenJDK documentation.


Just to be clear: I do not oppose the fix. It looks good to me.

If anything, there was a bit of a clash between on the one hand 
providing a means for overriding the URL, but on the other hand not 
really making it as general as it could be. Either removing the 
possibility to override it (and, as you say, let an alternative 
implementation change the code of the taglet itself), or as Roger 
suggest, using a more general mechanism like MessageFormat would have 
the code make slightly more sense. The simplest way is probably to 
skip the property override, which doesn't get used anyhow right now 
(and therefore suspect according to "if you don't test it, it is (or 
will become) broken").



I'd be OK with removing the ability to override the URL.

-- Jon


/Magnus

Yes, the currently proposed taglet may assume the existence of  
single "base URL", but anyone with an alternate implementation of 
OpenJDK could change the impl of the taglet to use any other 
mechanism to establish the link. Doing a "strings in switch" on the 
identifier to select a URL comes to mind, and avoids anyone having to 
edit the main source doc comments.


-- Jon



On 04/19/2017 01:37 PM, David Holmes wrote:

On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:


We could potentially make the default URL to be "some" cgi url,
and have the build system specify the  URL all the time, in our
case it would be the Oracle documentation URL.

Would this be an acceptable approach ?


I'm not sure what you mean. I have a hard time seeing how a simple 
identifier (that will be fixed in the file using the taglet) can be 
attached to an arbitrary URL to yield a valid result. As Magnus 
said, being able to change the URL is good, but it still requires 
the same "kind" of URL where the identifier is used as a key.


Imagine you have all the documentation locally on your machine then 
try to figure out how you could link to other local documentation 
using this scheme.


David


Kumar


On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:

On 2017-04-18 19:44, Kumar Srinivasan wrote:

Hello,

As explained in the JBS issue [1], this new taglet enables API
documents
to contain the extLink tag to link external sources.

Please review the webrev [2].

Changes looks good.

Just a reflection: This is heavily biased to Oracle 
documentation. Even
if it's possible to override the URL via a system property, it 
assumes
the Oracle URL format and id name. Just wondering a bit how that 
fits

with the OpenJDK philosophy.


I have to agree, this is not at all general purpose but totally 
Oracle

documentation centric.

David
-



/Magnus



Thanks
Kumar

[1] https://bugs.openjdk.java.net/browse/JDK-8178725
[2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/

Re: Please review: JDK-8178725: provide way to link to external documentation

[Magnus Ihse Bursie]

On 2017-04-20 20:02, Jonathan Gibbons wrote:

David, Magnus,

Yes, this is somewhat Oracle-specific (more accurately it is 
JDK-specific, which is why this is a proposed to be a JDK build-time 
taglet, and not a standard tag in the standard doclet), but it is no 
worse than the explicit Oracle-specific URLs that have been used up to 
now, or the relative links using {@docRoot}/../stuff  which assume 
that "stuff " is available nearby somehow.  I would also go further 
and say this is better that the existing methodology because it 
abstracts all the linking to a single taglet, removing it from inline 
in the doc comments. 
I agree, it's in no way worse than what already existed. But it shed 
light on the somewhat unclear division between online Oracle 
documentation and OpenJDK documentation.


Just to be clear: I do not oppose the fix. It looks good to me.

If anything, there was a bit of a clash between on the one hand 
providing a means for overriding the URL, but on the other hand not 
really making it as general as it could be. Either removing the 
possibility to override it (and, as you say, let an alternative 
implementation change the code of the taglet itself), or as Roger 
suggest, using a more general mechanism like MessageFormat would have 
the code make slightly more sense. The simplest way is probably to skip 
the property override, which doesn't get used anyhow right now (and 
therefore suspect according to "if you don't test it, it is (or will 
become) broken").


/Magnus

Yes, the currently proposed taglet may assume the existence of  single 
"base URL", but anyone with an alternate implementation of OpenJDK 
could change the impl of the taglet to use any other mechanism to 
establish the link. Doing a "strings in switch" on the identifier to 
select a URL comes to mind, and avoids anyone having to edit the main 
source doc comments.


-- Jon



On 04/19/2017 01:37 PM, David Holmes wrote:

On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:


We could potentially make the default URL to be "some" cgi url,
and have the build system specify the  URL all the time, in our
case it would be the Oracle documentation URL.

Would this be an acceptable approach ?


I'm not sure what you mean. I have a hard time seeing how a simple 
identifier (that will be fixed in the file using the taglet) can be 
attached to an arbitrary URL to yield a valid result. As Magnus said, 
being able to change the URL is good, but it still requires the same 
"kind" of URL where the identifier is used as a key.


Imagine you have all the documentation locally on your machine then 
try to figure out how you could link to other local documentation 
using this scheme.


David


Kumar


On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:

On 2017-04-18 19:44, Kumar Srinivasan wrote:

Hello,

As explained in the JBS issue [1], this new taglet enables API
documents
to contain the extLink tag to link external sources.

Please review the webrev [2].

Changes looks good.

Just a reflection: This is heavily biased to Oracle documentation. 
Even
if it's possible to override the URL via a system property, it 
assumes

the Oracle URL format and id name. Just wondering a bit how that fits
with the OpenJDK philosophy.


I have to agree, this is not at all general purpose but totally Oracle
documentation centric.

David
-



/Magnus



Thanks
Kumar

[1] https://bugs.openjdk.java.net/browse/JDK-8178725
[2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/

Re: Please review: JDK-8178725: provide way to link to external documentation

[Jonathan Gibbons]

OK by me.

-- Jon


On 04/19/2017 10:46 AM, Kumar Srinivasan wrote:

Have made the following changes:
* fixed the indentations, basically pointed the IDE and asked it to
   reformat the whole file
* fixed regex, to be defensive against leading WS, though the 
DocCommentParser

   whacks the WS.

Please see updated webrev: 
http://cr.openjdk.java.net/~ksrini/8178725/webrev.01/


Thanks
Kumar


On 4/18/2017 3:27 PM, Jonathan Gibbons wrote:
The use of double quotes in the example might lead one to incorrectly 
believe that they are required.


The example should work without the quotes:

  43 /**
  44  * An inline tag to conveniently insert an external link.
  45  * The tag can be used as follows:
  46  * {@extLink name description}, for example
  47  * 
  48  * {@code
  49  * Please see {@extLink Borealis a spectacular} sight.
  50  * }
  51  * 
  52  * will produce the following html
  53  * 
  54  * {@code
  55  * Please see href="https://www.oracle.com/pls/topic/lookup?ctx=javase9&id=Borealis";>a 
spectacular sight.

  56  * }
  57  * }
  58  */


The indentation in both the comment and the source code is a bit 
inconsistent. Is that an extra } on line 57?


The regex will fail if there are too many spaces between "{@extLink" 
and the name.   [1]


-- Jon


[1]: 
https://blog.codinghorror.com/regular-expressions-now-you-have-two-problems/



On 04/18/2017 11:26 AM, Kumar Srinivasan wrote:


Thanks Erik, yes will wait for Magnus' and Jon's comments.

Kumar

The build change looks ok to me, but Magnus should definitely look 
at this since he is so heavily involved in the Javadoc build right 
now.


/Erik


On 2017-04-18 19:44, Kumar Srinivasan wrote:

Hello,

As explained in the JBS issue [1], this new taglet enables API 
documents

to contain the extLink tag to link external sources.

Please review the webrev [2].

Thanks
Kumar

[1] https://bugs.openjdk.java.net/browse/JDK-8178725
[2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/

Re: RFR: JDK-8179022 Add serialization spec as markdown

[Mandy Chung]

> On Apr 20, 2017, at 11:47 AM, Magnus Ihse Bursie wrote:
> 
> http://cr.openjdk.java.net/~ihse/JDK-8179022-add-markdown-serialization-spec/webrev.02

A passing comment.

Copyright header is missing in make/devkit/createPandocBundle.sh

Mandy

Re: Review Request: JDK-8179035: Include tool modules in unified docs

[Lance Andersen]

The javadocs read fine.  Probably need to update the  copyright date for the 
module-info.java files

Best
Lance
> On Apr 20, 2017, at 2:37 PM, Mandy Chung  wrote:
> 
> A few modules are missing in the unified docs such as jdk.jcmd, 
> jdk.jdwp.agent, jdk.jstatd, etc.  Some tool modules are providers
> and they were in the initial set.  The modules that are neither
> a provider nor exporting any API package are missed in the initial
> patch.
> 
> http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8179035/webrev.00/
> 
> Mandy

 
  

 Lance Andersen| 
Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering 
1 Network Drive 
Burlington, MA 01803
lance.ander...@oracle.com 

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

[Mandy Chung]

> 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-8179022 Add serialization spec as markdown

[Roger Riggs]

Hi Magnus,

How did you verify that the result was the same as the previous 
specification?

It would have been good to separate the content changes from the other parts
so they could be properly reviewed.  The proposed markdown source does not
favorably easily with the spec as I worked on it a couple of months ago.
That's going to take more work to verify.

Thanks, Roger


On 4/20/2017 2:47 PM, Magnus Ihse Bursie wrote:

On 2017-04-20 15:59, Alan Bateman wrote:

On 20/04/2017 14:49, Magnus Ihse Bursie wrote:

Here's the first step towards fixing JDK-8177434 
. A framework is 
added for converting markdown specs to html using pandoc. The Java 
serialization spec is added in markdown format as a proof of 
concept. I also reintroduced the functionality to enable full docs 
if all prerequisites are present.


Note that this fix is dependent on the patch for JDK-8178038 et al 
that is currently out for review. The webrev is created with that 
patch as baseline.


This fix is part of JEP 299. I intend to push it to jdk9.

Here's an example of the generated output:
http://cr.openjdk.java.net/~ihse/JDK-8179022-javadoc-output-demo/specs/serialization/ 



Bug: https://bugs.openjdk.java.net/browse/JDK-8179022
WebRev: 
http://cr.openjdk.java.net/~ihse/JDK-8179022-add-markdown-serialization-spec/webrev.01
I just skimmed this and notice this adds class.gif with output that I 
think is serialver. This tool has been changed in JDK 9 to drop the 
GUI and so this image and the reference to the "Show" button are now 
obsolete. I'm sure you don't want want to get into issues like this 
but we will need to submit a few bugs to ensure that some of the 
dusty documents are updated.


You are right that I do not want to make any substantial changes to 
the documentation. I have made an effort to make sure the markdown is 
of a high quality (like any other source code), so that it should be 
easy to read and update. In this process I noticed a few minor issues 
(like syntactic errors in the examples, or incorrect/inconsistent 
formatting) which I have fixed.


I have also noticed some things that sound like they need to be 
updated, like the serialver stuff. I'm no expert on serialization, but 
perhaps I can have an offline chat with someone who are, and come with 
a couple of suggestions on things to improve with the documentation.


---

I just noticed that I had missed to do "hg add" so webrev did not pick 
up my new script that creates the pandoc bundle. Here's an updated 
webrev that added this:


http://cr.openjdk.java.net/~ihse/JDK-8179022-add-markdown-serialization-spec/webrev.02 



/Magnus



-Alan

Re: RFR: JDK-8179022 Add serialization spec as markdown

[Magnus Ihse Bursie]

On 2017-04-20 15:59, Alan Bateman wrote:

On 20/04/2017 14:49, Magnus Ihse Bursie wrote:

Here's the first step towards fixing JDK-8177434 
. A framework is 
added for converting markdown specs to html using pandoc. The Java 
serialization spec is added in markdown format as a proof of concept. 
I also reintroduced the functionality to enable full docs if all 
prerequisites are present.


Note that this fix is dependent on the patch for JDK-8178038 et al 
that is currently out for review. The webrev is created with that 
patch as baseline.


This fix is part of JEP 299. I intend to push it to jdk9.

Here's an example of the generated output:
http://cr.openjdk.java.net/~ihse/JDK-8179022-javadoc-output-demo/specs/serialization/ 



Bug: https://bugs.openjdk.java.net/browse/JDK-8179022
WebRev: 
http://cr.openjdk.java.net/~ihse/JDK-8179022-add-markdown-serialization-spec/webrev.01
I just skimmed this and notice this adds class.gif with output that I 
think is serialver. This tool has been changed in JDK 9 to drop the 
GUI and so this image and the reference to the "Show" button are now 
obsolete. I'm sure you don't want want to get into issues like this 
but we will need to submit a few bugs to ensure that some of the dusty 
documents are updated.


You are right that I do not want to make any substantial changes to the 
documentation. I have made an effort to make sure the markdown is of a 
high quality (like any other source code), so that it should be easy to 
read and update. In this process I noticed a few minor issues (like 
syntactic errors in the examples, or incorrect/inconsistent formatting) 
which I have fixed.


I have also noticed some things that sound like they need to be updated, 
like the serialver stuff. I'm no expert on serialization, but perhaps I 
can have an offline chat with someone who are, and come with a couple of 
suggestions on things to improve with the documentation.


---

I just noticed that I had missed to do "hg add" so webrev did not pick 
up my new script that creates the pandoc bundle. Here's an updated 
webrev that added this:


http://cr.openjdk.java.net/~ihse/JDK-8179022-add-markdown-serialization-spec/webrev.02

/Magnus



-Alan

Review Request: JDK-8179035: Include tool modules in unified docs

[Mandy Chung]

A few modules are missing in the unified docs such as jdk.jcmd, 
jdk.jdwp.agent, jdk.jstatd, etc.  Some tool modules are providers
and they were in the initial set.  The modules that are neither
a provider nor exporting any API package are missed in the initial
patch.

http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8179035/webrev.00/

Mandy

Re: Please review: JDK-8178725: provide way to link to external documentation

[Roger Riggs]

Hi,

An idea that might make it more flexible would be if the settable 
property used as the link used

one of the familiar formatting substitution mechanisms so the id can be
inserted in the link wherever it is needed.   For example, the 
PrintStream formatting like %s.
Alternatively, the {0} form of MessageFormat might clash less with the 
URL encoding syntax.


$.02, Roger


On 4/19/2017 4:47 PM, Kumar Srinivasan wrote:


On 4/19/2017 1:37 PM, David Holmes wrote:

On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:


We could potentially make the default URL to be "some" cgi url,
and have the build system specify the  URL all the time, in our
case it would be the Oracle documentation URL.

Would this be an acceptable approach ?


I'm not sure what you mean. I have a hard time seeing how a simple 
identifier (that will be fixed in the file using the taglet) can be 
attached to an arbitrary URL to yield a valid result. As Magnus said, 
being able to change the URL is good, but it still requires the same 
"kind" of URL where the identifier is used as a key.


Imagine you have all the documentation locally on your machine then 
try to figure out how you could link to other local documentation 
using this scheme.



Ok I see, I am going to defer this to Jon Gibbons.

Kumar



David


Kumar


On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:

On 2017-04-18 19:44, Kumar Srinivasan wrote:

Hello,

As explained in the JBS issue [1], this new taglet enables API
documents
to contain the extLink tag to link external sources.

Please review the webrev [2].

Changes looks good.

Just a reflection: This is heavily biased to Oracle documentation. 
Even
if it's possible to override the URL via a system property, it 
assumes

the Oracle URL format and id name. Just wondering a bit how that fits
with the OpenJDK philosophy.


I have to agree, this is not at all general purpose but totally Oracle
documentation centric.

David
-



/Magnus



Thanks
Kumar

[1] https://bugs.openjdk.java.net/browse/JDK-8178725
[2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/

Re: Please review: JDK-8178725: provide way to link to external documentation

[Jonathan Gibbons]

David, Magnus,

Yes, this is somewhat Oracle-specific (more accurately it is 
JDK-specific, which is why this is a proposed to be a JDK build-time 
taglet, and not a standard tag in the standard doclet), but it is no 
worse than the explicit Oracle-specific URLs that have been used up to 
now, or the relative links using {@docRoot}/../stuff  which assume that 
"stuff " is available nearby somehow.  I would also go further and say 
this is better that the existing methodology because it abstracts all 
the linking to a single taglet, removing it from inline in the doc 
comments.  Yes, the currently proposed taglet may assume the existence 
of  single "base URL", but anyone with an alternate implementation of 
OpenJDK could change the impl of the taglet to use any other mechanism 
to establish the link. Doing a "strings in switch" on the identifier to 
select a URL comes to mind, and avoids anyone having to edit the main 
source doc comments.


-- Jon



On 04/19/2017 01:37 PM, David Holmes wrote:

On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:


We could potentially make the default URL to be "some" cgi url,
and have the build system specify the  URL all the time, in our
case it would be the Oracle documentation URL.

Would this be an acceptable approach ?


I'm not sure what you mean. I have a hard time seeing how a simple 
identifier (that will be fixed in the file using the taglet) can be 
attached to an arbitrary URL to yield a valid result. As Magnus said, 
being able to change the URL is good, but it still requires the same 
"kind" of URL where the identifier is used as a key.


Imagine you have all the documentation locally on your machine then 
try to figure out how you could link to other local documentation 
using this scheme.


David


Kumar


On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:

On 2017-04-18 19:44, Kumar Srinivasan wrote:

Hello,

As explained in the JBS issue [1], this new taglet enables API
documents
to contain the extLink tag to link external sources.

Please review the webrev [2].

Changes looks good.

Just a reflection: This is heavily biased to Oracle documentation. 
Even

if it's possible to override the URL via a system property, it assumes
the Oracle URL format and id name. Just wondering a bit how that fits
with the OpenJDK philosophy.


I have to agree, this is not at all general purpose but totally Oracle
documentation centric.

David
-



/Magnus



Thanks
Kumar

[1] https://bugs.openjdk.java.net/browse/JDK-8178725
[2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

[Alan Bateman]

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

[Mandy Chung]

> 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

[Mandy Chung]

> 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

[Alan Bateman]

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

[Mandy Chung]

> 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-8178037 Move information from jdi-overview.html into jdk.jdi module-info.java

[Mandy Chung]

> On Apr 20, 2017, at 12:57 AM, Magnus Ihse Bursie 
>  wrote:
> 
> 
> http://cr.openjdk.java.net/~ihse/JDK-8178037-fix-obsolete-overview-files/webrev.02/

Looks good.

Mandy

Re: RFR: JDK-8179022 Add serialization spec as markdown

[Erik Joelsson]

The build changes look good to me. I can't comment on the actual .md files.

/Erik


On 2017-04-20 15:49, Magnus Ihse Bursie wrote:
Here's the first step towards fixing JDK-8177434 
. A framework is 
added for converting markdown specs to html using pandoc. The Java 
serialization spec is added in markdown format as a proof of concept. 
I also reintroduced the functionality to enable full docs if all 
prerequisites are present.


Note that this fix is dependent on the patch for JDK-8178038 et al 
that is currently out for review. The webrev is created with that 
patch as baseline.


This fix is part of JEP 299. I intend to push it to jdk9.

Here's an example of the generated output:
http://cr.openjdk.java.net/~ihse/JDK-8179022-javadoc-output-demo/specs/serialization/ 



Bug: https://bugs.openjdk.java.net/browse/JDK-8179022
WebRev: 
http://cr.openjdk.java.net/~ihse/JDK-8179022-add-markdown-serialization-spec/webrev.01


/Magnus

Re: RFR: JDK-8179022 Add serialization spec as markdown

[Alan Bateman]

On 20/04/2017 14:49, Magnus Ihse Bursie wrote:

Here's the first step towards fixing JDK-8177434 
. A framework is 
added for converting markdown specs to html using pandoc. The Java 
serialization spec is added in markdown format as a proof of concept. 
I also reintroduced the functionality to enable full docs if all 
prerequisites are present.


Note that this fix is dependent on the patch for JDK-8178038 et al 
that is currently out for review. The webrev is created with that 
patch as baseline.


This fix is part of JEP 299. I intend to push it to jdk9.

Here's an example of the generated output:
http://cr.openjdk.java.net/~ihse/JDK-8179022-javadoc-output-demo/specs/serialization/ 



Bug: https://bugs.openjdk.java.net/browse/JDK-8179022
WebRev: 
http://cr.openjdk.java.net/~ihse/JDK-8179022-add-markdown-serialization-spec/webrev.01
I just skimmed this and notice this adds class.gif with output that I 
think is serialver. This tool has been changed in JDK 9 to drop the GUI 
and so this image and the reference to the "Show" button are now 
obsolete. I'm sure you don't want want to get into issues like this but 
we will need to submit a few bugs to ensure that some of the dusty 
documents are updated.


-Alan

RFR: JDK-8179022 Add serialization spec as markdown

[Magnus Ihse Bursie]

Here's the first step towards fixing JDK-8177434 
. A framework is added 
for converting markdown specs to html using pandoc. The Java 
serialization spec is added in markdown format as a proof of concept. I 
also reintroduced the functionality to enable full docs if all 
prerequisites are present.


Note that this fix is dependent on the patch for JDK-8178038 et al that 
is currently out for review. The webrev is created with that patch as 
baseline.


This fix is part of JEP 299. I intend to push it to jdk9.

Here's an example of the generated output:
http://cr.openjdk.java.net/~ihse/JDK-8179022-javadoc-output-demo/specs/serialization/

Bug: https://bugs.openjdk.java.net/browse/JDK-8179022
WebRev: 
http://cr.openjdk.java.net/~ihse/JDK-8179022-add-markdown-serialization-spec/webrev.01


/Magnus

Re: Correct Compiler for ARM / Arch64 for the jdk8u forest? (-m64 not supported)

[Martijn Verburg]

Hi Erik/Andrew/Dalibor,

Ah that clears it up - we were getting confused with what port was in
mainstream or not.  OK, we'll pick the ssh://hg.openjdk.java.net/
aarch64-port/jdk8u for our Java 8 build (Zero is interesting, but of less
use to the wider community) and then we'll see what happens for 9 and 10 a
little down the line.

Thanks all again for the speedy assistance!

Cheers,
Martijn

On 20 April 2017 at 13:17, dalibor topic  wrote:

> If this is related to yesterday's similar query [0], then I assume you're
> using http://hg.openjdk.java.net/jdk8u/jdk8u/ for the build.
>
> There is no dedicated ARM port in JDK 8u. You would need to build the Zero
> interpreter instead, if you are building from the forest above, or, as
> Andrew suggested, use a different forest from the AArch64 Port Project.
>
> cheers,
> dalibor topic
>
> [0] http://mail.openjdk.java.net/pipermail/build-dev/2017-April/
> 018974.html
>
>
> On 20.04.2017 13:16, Martijn Verburg wrote:
>
>> Hi all,
>>
>> We've been putting together a community build farm and have wrangled from
>> ARM machines. We are building from jdk8u and have the following
>> configuration:
>>
>> -
>>
>> A new configuration has been successfully created in
>> /home/jenkins/workspace/george_arm_test/openjdk/build/linux-
>> aarch64-normal-server-release
>> using configure arguments
>> '--with-boot-jdk=/usr/lib/jvm/java-1.7.0-openjdk-arm64 --enable-ccache
>> --with-jvm-variants=server
>> --with-cacerts-file=/home/jenkins/workspace/george_arm_test/
>> cacerts_area/security/cacerts
>> --with-alsa=/home/jenkins/workspace/george_arm_test/alsa-lib-1.0.27.2
>> --with-freetype=/home/jenkins/workspace/george_arm_test/open
>> jdk/installedfreetype
>> --with-x=/usr/include/X11 --with-debug-level=release'.
>>
>> Configuration summary:
>> * Debug level:release
>> * JDK variant:normal
>> * JVM variants:   server
>> * OpenJDK target: OS: linux, CPU architecture: aarch64, address length: 64
>>
>> Tools summary:
>> * Boot JDK:   java version "1.7.0_95" OpenJDK Runtime Environment
>> (IcedTea 2.6.4) (7u95-2.6.4-3) OpenJDK 64-Bit Server VM (build 24.95-b01,
>> mixed mode)  (at /usr/lib/jvm/java-1.7.0-openjdk-arm64)
>> * C Compiler: gcc-5 (Ubuntu/Linaro 5.4.0-6ubuntu1~16.04.4) 5.4.0
>> version 5.4.0 (at /usr/bin/gcc-5)
>> * C++ Compiler:   g++-5 (Ubuntu/Linaro 5.4.0-6ubuntu1~16.04.4) 5.4.0
>> version 5.4.0 (at /usr/bin/g++-5)
>>
>> Build performance summary:
>> * Cores to use:   16
>> * Memory limit:   128878 MB
>> * ccache status:  installed and in use
>>
>> Configured the JDK
>>
>> --
>>
>> We notice that the configure output states:
>>
>> checking if the C compiler supports "-m64"... no
>> checking if the C++ compiler supports "-m64"... no
>> checking if both compilers support "-m64"... no
>> checking if the C compiler supports "-m64"... no
>> checking if the C++ compiler supports "-m64"... no
>> checking if both compilers support "-m64"... no
>>
>> -
>>
>> The hotspot build then fails (predictably enough) at:
>>
>> CCACHE_COMPRESS=1  CCACHE_SLOPPINESS=time_macros /usr/local/bin/ccache
>> /usr/bin/g++-5 -DLINUX -D_GNU_SOURCE -DAMD64 -DPRODUCT -I.
>> -I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/
>> src/share/vm/prims
>> -I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/share/vm
>> -I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/
>> src/share/vm/precompiled
>> -I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/cpu/x86/vm
>> -I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/
>> src/os_cpu/linux_x86/vm
>> -I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/os/linux/vm
>> -I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/os/posix/vm
>> -I../generated -DHOTSPOT_RELEASE_VERSION="\"25.71-b00\""
>> -DHOTSPOT_BUILD_TARGET="\"product\"" -DHOTSPOT_BUILD_USER="\"jenkins\""
>> -DHOTSPOT_LIB_ARCH=\"aarch64\" -DHOTSPOT_VM_DISTRO="\"OpenJDK\""
>>  -DTARGET_OS_FAMILY_linux -DTARGET_ARCH_x86 -DTARGET_ARCH_MODEL_x86_64
>> -DTARGET_OS_ARCH_linux_x86 -DTARGET_OS_ARCH_MODEL_linux_x86_64
>> -DTARGET_COMPILER_gcc -DCOMPILER2 -DCOMPILER1 -fPIC -fno-rtti
>> -fno-exceptions -D_REENTRANT -fcheck-new -fvisibility=hidden -m64  -pipe
>> -fno-strict-aliasing  -g -fno-omit-frame-pointer -O3  -DVM_LITTLE_ENDIAN
>> -D_LP64=1 -Werror -Wpointer-arith -Wsign-compare -Wundef -Wunused-function
>> -Wunused-value -std=gnu++98 -c -MMD -MP -MF
>> ../generated/dependencies/precompiled.hpp.gch.d -fpch-deps -x c++-header
>> /home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/
>> share/vm/precompiled/precompiled.hpp
>> -o precompiled.hpp.gch
>> *g++-5: error: unrecognized command line option '-m64'*
>>
>> -
>>
>> We're inexperienced at build on this architecture, I assuming that we
>> either need a compiler that supports -m64 or that -m64 should not be
>> passed
>> through in this case?
>>
>> Cheers,
>> Martijn
>>
>>
> --
>  Dalibor Topic | Principal Product Manager
> Phone: +494089091214  | 

Re: Correct Compiler for ARM / Arch64 for the jdk8u forest? (-m64 not supported)

[dalibor topic]

If this is related to yesterday's similar query [0], then I assume 
you're using http://hg.openjdk.java.net/jdk8u/jdk8u/ for the build.


There is no dedicated ARM port in JDK 8u. You would need to build the 
Zero interpreter instead, if you are building from the forest above, or, 
as Andrew suggested, use a different forest from the AArch64 Port Project.


cheers,
dalibor topic

[0] http://mail.openjdk.java.net/pipermail/build-dev/2017-April/018974.html

On 20.04.2017 13:16, Martijn Verburg wrote:

Hi all,

We've been putting together a community build farm and have wrangled from
ARM machines. We are building from jdk8u and have the following
configuration:

-

A new configuration has been successfully created in
/home/jenkins/workspace/george_arm_test/openjdk/build/linux-aarch64-normal-server-release
using configure arguments
'--with-boot-jdk=/usr/lib/jvm/java-1.7.0-openjdk-arm64 --enable-ccache
--with-jvm-variants=server
--with-cacerts-file=/home/jenkins/workspace/george_arm_test/cacerts_area/security/cacerts
--with-alsa=/home/jenkins/workspace/george_arm_test/alsa-lib-1.0.27.2
--with-freetype=/home/jenkins/workspace/george_arm_test/openjdk/installedfreetype
--with-x=/usr/include/X11 --with-debug-level=release'.

Configuration summary:
* Debug level:release
* JDK variant:normal
* JVM variants:   server
* OpenJDK target: OS: linux, CPU architecture: aarch64, address length: 64

Tools summary:
* Boot JDK:   java version "1.7.0_95" OpenJDK Runtime Environment
(IcedTea 2.6.4) (7u95-2.6.4-3) OpenJDK 64-Bit Server VM (build 24.95-b01,
mixed mode)  (at /usr/lib/jvm/java-1.7.0-openjdk-arm64)
* C Compiler: gcc-5 (Ubuntu/Linaro 5.4.0-6ubuntu1~16.04.4) 5.4.0
version 5.4.0 (at /usr/bin/gcc-5)
* C++ Compiler:   g++-5 (Ubuntu/Linaro 5.4.0-6ubuntu1~16.04.4) 5.4.0
version 5.4.0 (at /usr/bin/g++-5)

Build performance summary:
* Cores to use:   16
* Memory limit:   128878 MB
* ccache status:  installed and in use

Configured the JDK

--

We notice that the configure output states:

checking if the C compiler supports "-m64"... no
checking if the C++ compiler supports "-m64"... no
checking if both compilers support "-m64"... no
checking if the C compiler supports "-m64"... no
checking if the C++ compiler supports "-m64"... no
checking if both compilers support "-m64"... no

-

The hotspot build then fails (predictably enough) at:

CCACHE_COMPRESS=1  CCACHE_SLOPPINESS=time_macros /usr/local/bin/ccache
/usr/bin/g++-5 -DLINUX -D_GNU_SOURCE -DAMD64 -DPRODUCT -I.
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/share/vm/prims
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/share/vm
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/share/vm/precompiled
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/cpu/x86/vm
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/os_cpu/linux_x86/vm
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/os/linux/vm
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/os/posix/vm
-I../generated -DHOTSPOT_RELEASE_VERSION="\"25.71-b00\""
-DHOTSPOT_BUILD_TARGET="\"product\"" -DHOTSPOT_BUILD_USER="\"jenkins\""
-DHOTSPOT_LIB_ARCH=\"aarch64\" -DHOTSPOT_VM_DISTRO="\"OpenJDK\""
 -DTARGET_OS_FAMILY_linux -DTARGET_ARCH_x86 -DTARGET_ARCH_MODEL_x86_64
-DTARGET_OS_ARCH_linux_x86 -DTARGET_OS_ARCH_MODEL_linux_x86_64
-DTARGET_COMPILER_gcc -DCOMPILER2 -DCOMPILER1 -fPIC -fno-rtti
-fno-exceptions -D_REENTRANT -fcheck-new -fvisibility=hidden -m64  -pipe
-fno-strict-aliasing  -g -fno-omit-frame-pointer -O3  -DVM_LITTLE_ENDIAN
-D_LP64=1 -Werror -Wpointer-arith -Wsign-compare -Wundef -Wunused-function
-Wunused-value -std=gnu++98 -c -MMD -MP -MF
../generated/dependencies/precompiled.hpp.gch.d -fpch-deps -x c++-header
/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/share/vm/precompiled/precompiled.hpp
-o precompiled.hpp.gch
*g++-5: error: unrecognized command line option '-m64'*

-

We're inexperienced at build on this architecture, I assuming that we
either need a compiler that supports -m64 or that -m64 should not be passed
through in this case?

Cheers,
Martijn



--
 Dalibor Topic | Principal Product Manager
Phone: +494089091214  | Mobile: +491737185961


ORACLE Deutschland B.V. & Co. KG | Kühnehöfe 5 | 22761 Hamburg

ORACLE Deutschland B.V. & Co. KG
Hauptverwaltung: Riesstr. 25, D-80992 München
Registergericht: Amtsgericht München, HRA 95603

Komplementärin: ORACLE Deutschland Verwaltung B.V.
Hertogswetering 163/167, 3543 AS Utrecht, Niederlande
Handelsregister der Handelskammer Midden-Niederlande, Nr. 30143697
Geschäftsführer: Alexander van der Ven, Jan Schultheiss, Val Maher

 Oracle is committed to developing
practices and products that help protect the environment

Re: Correct Compiler for ARM / Arch64 for the jdk8u forest? (-m64 not supported)

[Andrew Haley]

On 20/04/17 12:16, Martijn Verburg wrote:
> We're inexperienced at build on this architecture, I assuming that we
> either need a compiler that supports -m64 or that -m64 should not be passed
> through in this case?

You shouldn't have any great problem building JDK8: we do it all
of the time.

Exactly what is the URL that you checked out?  It should be

ssh://hg.openjdk.java.net/aarch64-port/jdk8u

Andrew.

Re: Correct Compiler for ARM / Arch64 for the jdk8u forest? (-m64 not supported)

[Erik Joelsson]

I'm not familiar with building for arm/aarch64 on the native platform 
(i.e. not cross compiling) in jdk8u. It definitely looks like the 
configuration is confused. The command line for hotspot seems to think 
that it's supposed to produce an x86_64 binary using your aarch64 
compiler. I suspect you will need to set more environment variables 
manually to trick the hotspot makefiles into doing the right thing.


We fixed a lot of things in this area in JDK 9, where I'm pretty sure 
this would just work.


/Erik


On 2017-04-20 13:16, Martijn Verburg wrote:

Hi all,

We've been putting together a community build farm and have wrangled from
ARM machines. We are building from jdk8u and have the following
configuration:

-

A new configuration has been successfully created in
/home/jenkins/workspace/george_arm_test/openjdk/build/linux-aarch64-normal-server-release
using configure arguments
'--with-boot-jdk=/usr/lib/jvm/java-1.7.0-openjdk-arm64 --enable-ccache
--with-jvm-variants=server
--with-cacerts-file=/home/jenkins/workspace/george_arm_test/cacerts_area/security/cacerts
--with-alsa=/home/jenkins/workspace/george_arm_test/alsa-lib-1.0.27.2
--with-freetype=/home/jenkins/workspace/george_arm_test/openjdk/installedfreetype
--with-x=/usr/include/X11 --with-debug-level=release'.

Configuration summary:
* Debug level:release
* JDK variant:normal
* JVM variants:   server
* OpenJDK target: OS: linux, CPU architecture: aarch64, address length: 64

Tools summary:
* Boot JDK:   java version "1.7.0_95" OpenJDK Runtime Environment
(IcedTea 2.6.4) (7u95-2.6.4-3) OpenJDK 64-Bit Server VM (build 24.95-b01,
mixed mode)  (at /usr/lib/jvm/java-1.7.0-openjdk-arm64)
* C Compiler: gcc-5 (Ubuntu/Linaro 5.4.0-6ubuntu1~16.04.4) 5.4.0
version 5.4.0 (at /usr/bin/gcc-5)
* C++ Compiler:   g++-5 (Ubuntu/Linaro 5.4.0-6ubuntu1~16.04.4) 5.4.0
version 5.4.0 (at /usr/bin/g++-5)

Build performance summary:
* Cores to use:   16
* Memory limit:   128878 MB
* ccache status:  installed and in use

Configured the JDK

--

We notice that the configure output states:

checking if the C compiler supports "-m64"... no
checking if the C++ compiler supports "-m64"... no
checking if both compilers support "-m64"... no
checking if the C compiler supports "-m64"... no
checking if the C++ compiler supports "-m64"... no
checking if both compilers support "-m64"... no

-

The hotspot build then fails (predictably enough) at:

CCACHE_COMPRESS=1  CCACHE_SLOPPINESS=time_macros /usr/local/bin/ccache
/usr/bin/g++-5 -DLINUX -D_GNU_SOURCE -DAMD64 -DPRODUCT -I.
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/share/vm/prims
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/share/vm
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/share/vm/precompiled
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/cpu/x86/vm
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/os_cpu/linux_x86/vm
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/os/linux/vm
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/os/posix/vm
-I../generated -DHOTSPOT_RELEASE_VERSION="\"25.71-b00\""
-DHOTSPOT_BUILD_TARGET="\"product\"" -DHOTSPOT_BUILD_USER="\"jenkins\""
-DHOTSPOT_LIB_ARCH=\"aarch64\" -DHOTSPOT_VM_DISTRO="\"OpenJDK\""
  -DTARGET_OS_FAMILY_linux -DTARGET_ARCH_x86 -DTARGET_ARCH_MODEL_x86_64
-DTARGET_OS_ARCH_linux_x86 -DTARGET_OS_ARCH_MODEL_linux_x86_64
-DTARGET_COMPILER_gcc -DCOMPILER2 -DCOMPILER1 -fPIC -fno-rtti
-fno-exceptions -D_REENTRANT -fcheck-new -fvisibility=hidden -m64  -pipe
-fno-strict-aliasing  -g -fno-omit-frame-pointer -O3  -DVM_LITTLE_ENDIAN
-D_LP64=1 -Werror -Wpointer-arith -Wsign-compare -Wundef -Wunused-function
-Wunused-value -std=gnu++98 -c -MMD -MP -MF
../generated/dependencies/precompiled.hpp.gch.d -fpch-deps -x c++-header
/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/share/vm/precompiled/precompiled.hpp
-o precompiled.hpp.gch
*g++-5: error: unrecognized command line option '-m64'*

-

We're inexperienced at build on this architecture, I assuming that we
either need a compiler that supports -m64 or that -m64 should not be passed
through in this case?

Cheers,
Martijn

Correct Compiler for ARM / Arch64 for the jdk8u forest? (-m64 not supported)

[Martijn Verburg]

Hi all,

We've been putting together a community build farm and have wrangled from
ARM machines. We are building from jdk8u and have the following
configuration:

-

A new configuration has been successfully created in
/home/jenkins/workspace/george_arm_test/openjdk/build/linux-aarch64-normal-server-release
using configure arguments
'--with-boot-jdk=/usr/lib/jvm/java-1.7.0-openjdk-arm64 --enable-ccache
--with-jvm-variants=server
--with-cacerts-file=/home/jenkins/workspace/george_arm_test/cacerts_area/security/cacerts
--with-alsa=/home/jenkins/workspace/george_arm_test/alsa-lib-1.0.27.2
--with-freetype=/home/jenkins/workspace/george_arm_test/openjdk/installedfreetype
--with-x=/usr/include/X11 --with-debug-level=release'.

Configuration summary:
* Debug level:release
* JDK variant:normal
* JVM variants:   server
* OpenJDK target: OS: linux, CPU architecture: aarch64, address length: 64

Tools summary:
* Boot JDK:   java version "1.7.0_95" OpenJDK Runtime Environment
(IcedTea 2.6.4) (7u95-2.6.4-3) OpenJDK 64-Bit Server VM (build 24.95-b01,
mixed mode)  (at /usr/lib/jvm/java-1.7.0-openjdk-arm64)
* C Compiler: gcc-5 (Ubuntu/Linaro 5.4.0-6ubuntu1~16.04.4) 5.4.0
version 5.4.0 (at /usr/bin/gcc-5)
* C++ Compiler:   g++-5 (Ubuntu/Linaro 5.4.0-6ubuntu1~16.04.4) 5.4.0
version 5.4.0 (at /usr/bin/g++-5)

Build performance summary:
* Cores to use:   16
* Memory limit:   128878 MB
* ccache status:  installed and in use

Configured the JDK

--

We notice that the configure output states:

checking if the C compiler supports "-m64"... no
checking if the C++ compiler supports "-m64"... no
checking if both compilers support "-m64"... no
checking if the C compiler supports "-m64"... no
checking if the C++ compiler supports "-m64"... no
checking if both compilers support "-m64"... no

-

The hotspot build then fails (predictably enough) at:

CCACHE_COMPRESS=1  CCACHE_SLOPPINESS=time_macros /usr/local/bin/ccache
/usr/bin/g++-5 -DLINUX -D_GNU_SOURCE -DAMD64 -DPRODUCT -I.
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/share/vm/prims
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/share/vm
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/share/vm/precompiled
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/cpu/x86/vm
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/os_cpu/linux_x86/vm
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/os/linux/vm
-I/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/os/posix/vm
-I../generated -DHOTSPOT_RELEASE_VERSION="\"25.71-b00\""
-DHOTSPOT_BUILD_TARGET="\"product\"" -DHOTSPOT_BUILD_USER="\"jenkins\""
-DHOTSPOT_LIB_ARCH=\"aarch64\" -DHOTSPOT_VM_DISTRO="\"OpenJDK\""
 -DTARGET_OS_FAMILY_linux -DTARGET_ARCH_x86 -DTARGET_ARCH_MODEL_x86_64
-DTARGET_OS_ARCH_linux_x86 -DTARGET_OS_ARCH_MODEL_linux_x86_64
-DTARGET_COMPILER_gcc -DCOMPILER2 -DCOMPILER1 -fPIC -fno-rtti
-fno-exceptions -D_REENTRANT -fcheck-new -fvisibility=hidden -m64  -pipe
-fno-strict-aliasing  -g -fno-omit-frame-pointer -O3  -DVM_LITTLE_ENDIAN
-D_LP64=1 -Werror -Wpointer-arith -Wsign-compare -Wundef -Wunused-function
-Wunused-value -std=gnu++98 -c -MMD -MP -MF
../generated/dependencies/precompiled.hpp.gch.d -fpch-deps -x c++-header
/home/jenkins/workspace/george_arm_test/openjdk/hotspot/src/share/vm/precompiled/precompiled.hpp
-o precompiled.hpp.gch
*g++-5: error: unrecognized command line option '-m64'*

-

We're inexperienced at build on this architecture, I assuming that we
either need a compiler that supports -m64 or that -m64 should not be passed
through in this case?

Cheers,
Martijn

Re: RFR: JDK-8178037 Move information from jdi-overview.html into jdk.jdi module-info.java

[David Holmes]

On 20/04/2017 5:57 PM, Magnus Ihse Bursie wrote:

On 2017-04-20 04:21, David Holmes wrote:

On 19/04/2017 10:54 PM, Magnus Ihse Bursie wrote:

With JDK-8172312, the file src/jdk.jdi/share/classes/jdi-overview.html
is no longer included in the generated documentation. The information
provided by that file should move to
src/jdk.jdi/share/classes/module-info.java instead.


Looks good, but highlighted an error with the existing text:

  /**
   * Defines the Java Debugger Interface.
+  * 
+  * The Java™ Debug Interface (JDI) is a high level Java API
providing

The first line should read "Debug" not "Debugger".


Good catch.

I really didn't plan to make any editorial changes in this review, only
to move the contents to a place were it was once again included.
However, the text was apparently in need of some freshing up, so I tried
to fix what was pointed out.



Contrary to what Alan suggested (sorry Alan!) I think plain "JDI"
should be replaced by "The JDI".


I love it when I get conflicting reviews! ;-)

I'm sorry Dave, I'm afraid I can't do that. :-) "The JDI" just sounds
weird, and that's not how acronyms are typically referred to. So I've
sided with Alan here. If you don't agree, I'll back out that change and
you can fight it out by yourselves. :)


It depends on the exact nature of the acronym. If you wrote this out you 
would say "The Java Debug Interface .." hence you should say "The JDI ...".


:)

Cheers,
David
-


And Mandy: I agree with the weird ellipses. I changed that to "etc.",
which I think captures the intent that the list was not exhaustive.

Here is an updated review. It fixes the "Debugger" in the title, "The
JDI" -> "JDI" in two places, "..." -> "etc." and  -> {@code}.

http://cr.openjdk.java.net/~ihse/JDK-8178037-fix-obsolete-overview-files/webrev.02/


/Magnus



Thanks,
David


I also took the liberty of removing a bunch of other overview.html files
that are not included in the Javadoc anymore. They provided no real
informational value, and what text they contained is already expressed
similarly or better in the corresponding module-info.java files instead.

Bug: https://bugs.openjdk.java.net/browse/JDK-8178037
WebRev:
http://cr.openjdk.java.net/~ihse/JDK-8178037-fix-obsolete-overview-files/webrev.01



/Magnus

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

[Alan Bateman]

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-8178037 Move information from jdi-overview.html into jdk.jdi module-info.java

[Magnus Ihse Bursie]

On 2017-04-20 04:21, David Holmes wrote:

On 19/04/2017 10:54 PM, Magnus Ihse Bursie wrote:

With JDK-8172312, the file src/jdk.jdi/share/classes/jdi-overview.html
is no longer included in the generated documentation. The information
provided by that file should move to
src/jdk.jdi/share/classes/module-info.java instead.


Looks good, but highlighted an error with the existing text:

  /**
   * Defines the Java Debugger Interface.
+  * 
+  * The Java™ Debug Interface (JDI) is a high level Java API 
providing


The first line should read "Debug" not "Debugger".


Good catch.

I really didn't plan to make any editorial changes in this review, only 
to move the contents to a place were it was once again included. 
However, the text was apparently in need of some freshing up, so I tried 
to fix what was pointed out.




Contrary to what Alan suggested (sorry Alan!) I think plain "JDI" 
should be replaced by "The JDI".


I love it when I get conflicting reviews! ;-)

I'm sorry Dave, I'm afraid I can't do that. :-) "The JDI" just sounds 
weird, and that's not how acronyms are typically referred to. So I've 
sided with Alan here. If you don't agree, I'll back out that change and 
you can fight it out by yourselves. :)


And Mandy: I agree with the weird ellipses. I changed that to "etc.", 
which I think captures the intent that the list was not exhaustive.


Here is an updated review. It fixes the "Debugger" in the title, "The 
JDI" -> "JDI" in two places, "..." -> "etc." and  -> {@code}.


http://cr.openjdk.java.net/~ihse/JDK-8178037-fix-obsolete-overview-files/webrev.02/

/Magnus



Thanks,
David


I also took the liberty of removing a bunch of other overview.html files
that are not included in the Javadoc anymore. They provided no real
informational value, and what text they contained is already expressed
similarly or better in the corresponding module-info.java files instead.

Bug: https://bugs.openjdk.java.net/browse/JDK-8178037
WebRev:
http://cr.openjdk.java.net/~ihse/JDK-8178037-fix-obsolete-overview-files/webrev.01 




/Magnus

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

[Magnus Ihse Bursie]

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

[Magnus Ihse Bursie]

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