Quantcast

RFR: JDK-8176785 Add build support to generate PNG file from .dot file

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

RFR: JDK-8176785 Add build support to generate PNG file from .dot file

Magnus Ihse Bursie
This bug is the continuation of JDK-8173303, in which Mandy added the
generation of .dot files for @moduleGraph Javadoc tags.

With this patch, the code is taken to it's completion, and the
temporarily solutions left in place by JDK-8173303 has been replaced by
properly integrated solutions.

Summary of changes:
* A new option --enable-full-docs determines if module graphs should be
created or not. (In the future, even more optional but "difficult"
documentation work might be added to depend on this.) This is enabled by
default is all prerequisites are present.
* It is not impossible to get to a state of the documentation with
broken img links.
* I have re-introduced SetupJavadocGeneration to stop the code
duplication between JDK and Java SE javadoc builds.
* I have fixed a bug in how the makefiles determines the dependencies of
modules. This only affected a single module in nashorn, and no nashorn
build code used these dependencies, so that's why it has gone unnoticed
until now. I have verified that no other changes in module dependencies
are introduced by this fix.
* Javadoc source code dependencies are now correct even for transitive
modules
* Support added for the creation and use in jib of a "graphviz" module.

This code is dependent on JDK-8172312. This webrev is done as a diff
against the latest published webrev of JDK-8172312. JDK-8172312 is
reviewed, but is currently awaiting the status for JEP 299 to be changed
to Targeted before it can be pushed.

This code only affects the build system and documentation. I intend to
push it to jdk9 using the "noreg-doc" RDP2 exception.

Bug: https://bugs.openjdk.java.net/browse/JDK-8176785
WebRev:
http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.01

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8176785 Add build support to generate PNG file from .dot file

Erik Joelsson
Hello,

This looks good in general. One thing I don't like about this is that if
full docs is enabled, the docs-javadoc target now requires the full
exploded image to be built first. I think that's unfortunate. Would it
be possible to introduce separate targets for the gengraphs parts so
that the main javadoc call can be run independently of most of the rest
of the build, using the existing docs-javadoc target (and the newer
docs-reference, even though I think that name is bit strange in this
context)?

/Erik


On 2017-04-07 10:40, Magnus Ihse Bursie wrote:

> This bug is the continuation of JDK-8173303, in which Mandy added the
> generation of .dot files for @moduleGraph Javadoc tags.
>
> With this patch, the code is taken to it's completion, and the
> temporarily solutions left in place by JDK-8173303 has been replaced
> by properly integrated solutions.
>
> Summary of changes:
> * A new option --enable-full-docs determines if module graphs should
> be created or not. (In the future, even more optional but "difficult"
> documentation work might be added to depend on this.) This is enabled
> by default is all prerequisites are present.
> * It is not impossible to get to a state of the documentation with
> broken img links.
> * I have re-introduced SetupJavadocGeneration to stop the code
> duplication between JDK and Java SE javadoc builds.
> * I have fixed a bug in how the makefiles determines the dependencies
> of modules. This only affected a single module in nashorn, and no
> nashorn build code used these dependencies, so that's why it has gone
> unnoticed until now. I have verified that no other changes in module
> dependencies are introduced by this fix.
> * Javadoc source code dependencies are now correct even for transitive
> modules
> * Support added for the creation and use in jib of a "graphviz" module.
>
> This code is dependent on JDK-8172312. This webrev is done as a diff
> against the latest published webrev of JDK-8172312. JDK-8172312 is
> reviewed, but is currently awaiting the status for JEP 299 to be
> changed to Targeted before it can be pushed.
>
> This code only affects the build system and documentation. I intend to
> push it to jdk9 using the "noreg-doc" RDP2 exception.
>
> Bug: https://bugs.openjdk.java.net/browse/JDK-8176785
> WebRev:
> http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.01
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8176785 Add build support to generate PNG file from .dot file

Mandy Chung

> On Apr 7, 2017, at 4:02 AM, Erik Joelsson <[hidden email]> wrote:
>
> Hello,
>
> This looks good in general. One thing I don't like about this is that if full docs is enabled, the docs-javadoc target now requires the full exploded image to be built first. I think that's unfortunate. Would it be possible to introduce separate targets for the gengraphs parts so that the main javadoc call can be run independently of most of the rest of the build, using the existing docs-javadoc target (and the newer docs-reference, even though I think that name is bit strange in this context)?
>

I agree with Erik that it’d be nice to separate the module graph generation
and enable it to run with javadoc generation in parallel.  That’s one reason
why docs-module-graphs was a separate target (I have no issue to take that
target out from Main.gmk).


> On 2017-04-07 10:40, Magnus Ihse Bursie wrote:
>>
>> Summary of changes:
>> * A new option --enable-full-docs determines if module graphs should be created or not. (In the future, even more optional but "difficult" documentation work might be added to depend on this.) This is enabled by default is all prerequisites are present.


It might be okay to call this “full docs” when it includes the
module graphs but I am not sure about the new option name.

Can I build OpenJDK with the docs with module graphs when I
have Graphviz installed? I would think we need a configure
option to specify my local path to `dot` that will enable
the module graph build.  Is it possible?

>>
>> This code only affects the build system and documentation. I intend to push it to jdk9 using the "noreg-doc" RDP2 exception.
>>

Yes this is makefile and docs-only change.  In addition, FC extension
request for JDK-8173303 covers this issue [1].

>> Bug: https://bugs.openjdk.java.net/browse/JDK-8176785
>> WebRev: http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.01
>>

common/autoconf/jdk-options.m4
 172     if test "x$DTRACE_DEP_MISSING" = "xtrue"; then

What is DTRACE_DEP_MISSING?

 158 # gengraphs tool.
 167     # generated by the gengraphs tool and store it in the target dir.

Nit: I prefer to name the tool as `GenGraphs` rather than gengraphs.

Mandy
[1] https://bugs.openjdk.java.net/browse/JDK-8173303?focusedCommentId=14064511&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14064511
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8176785 Add build support to generate PNG file from .dot file

Erik Joelsson

On 2017-04-08 00:14, Mandy Chung wrote:
> Can I build OpenJDK with the docs with module graphs when I
> have Graphviz installed? I would think we need a configure
> option to specify my local path to `dot` that will enable
> the module graph build.  Is it possible?
Yes, it is possible. Configure will look for dot on the path by default
and if found, "full docs" will be enabled implicitly.

For such a simple dependency as this, basically we just need the path to
an executable, we don't need to define actual configure arguments. You
can simply override the value on the command line like this:

bash configure DOT=/path/to/dot

/Erik
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8176785 Add build support to generate PNG file from .dot file

Mandy Chung

> On Apr 10, 2017, at 12:07 AM, Erik Joelsson <[hidden email]> wrote:
>
>
> On 2017-04-08 00:14, Mandy Chung wrote:
>> Can I build OpenJDK with the docs with module graphs when I
>> have Graphviz installed? I would think we need a configure
>> option to specify my local path to `dot` that will enable
>> the module graph build.  Is it possible?
> Yes, it is possible. Configure will look for dot on the path by default and if found, "full docs" will be enabled implicitly.
>
> For such a simple dependency as this, basically we just need the path to an executable, we don't need to define actual configure arguments. You can simply override the value on the command line like this:
>
> bash configure DOT=/path/to/dot


Thanks.  That would do it.

Mandy
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8176785 Add build support to generate PNG file from .dot file

Magnus Ihse Bursie
In reply to this post by Erik Joelsson
Here is an updated webrev:
http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.04/

This change does not stop requiring the full exploded image to be built
first when building full docs. However, full-docs will no longer be
automatically enabled, even when all prerequisites are present, so for
normal uses (where the user does not give --enable-full-docs), this
dependency will not be present.

The problem here is that if we do that, we will end up with broken
Javadoc in the image/docs directory, since the generated HTML will
contain an "<img src="$m-graph.png"..>" tag, but the png file itself
will not exist. During an offline discussion, this was deemed acceptable.

I have changed the names of the targets to be more clear. Now we have
"docs-jdk" and "docs-javase" as the "top level" javadoc targets. For
these, we (currently) have the sub-targets "docs-jdk-javadoc" and
"docs-javase-javadoc", but as part of JEP 299, more will soon follow. I
have kept "docs-javadoc" as a legacy alias for "docs-jdk-javadoc".

I have also incorporated the fixes from Mandy's comment.

/Magnus


On 2017-04-07 13:02, Erik Joelsson wrote:

> Hello,
>
> This looks good in general. One thing I don't like about this is that
> if full docs is enabled, the docs-javadoc target now requires the full
> exploded image to be built first. I think that's unfortunate. Would it
> be possible to introduce separate targets for the gengraphs parts so
> that the main javadoc call can be run independently of most of the
> rest of the build, using the existing docs-javadoc target (and the
> newer docs-reference, even though I think that name is bit strange in
> this context)?
>
> /Erik
>
>
> On 2017-04-07 10:40, Magnus Ihse Bursie wrote:
>> This bug is the continuation of JDK-8173303, in which Mandy added the
>> generation of .dot files for @moduleGraph Javadoc tags.
>>
>> With this patch, the code is taken to it's completion, and the
>> temporarily solutions left in place by JDK-8173303 has been replaced
>> by properly integrated solutions.
>>
>> Summary of changes:
>> * A new option --enable-full-docs determines if module graphs should
>> be created or not. (In the future, even more optional but "difficult"
>> documentation work might be added to depend on this.) This is enabled
>> by default is all prerequisites are present.
>> * It is not impossible to get to a state of the documentation with
>> broken img links.
>> * I have re-introduced SetupJavadocGeneration to stop the code
>> duplication between JDK and Java SE javadoc builds.
>> * I have fixed a bug in how the makefiles determines the dependencies
>> of modules. This only affected a single module in nashorn, and no
>> nashorn build code used these dependencies, so that's why it has gone
>> unnoticed until now. I have verified that no other changes in module
>> dependencies are introduced by this fix.
>> * Javadoc source code dependencies are now correct even for
>> transitive modules
>> * Support added for the creation and use in jib of a "graphviz" module.
>>
>> This code is dependent on JDK-8172312. This webrev is done as a diff
>> against the latest published webrev of JDK-8172312. JDK-8172312 is
>> reviewed, but is currently awaiting the status for JEP 299 to be
>> changed to Targeted before it can be pushed.
>>
>> This code only affects the build system and documentation. I intend
>> to push it to jdk9 using the "noreg-doc" RDP2 exception.
>>
>> Bug: https://bugs.openjdk.java.net/browse/JDK-8176785
>> WebRev:
>> http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.01
>>
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8176785 Add build support to generate PNG file from .dot file

Magnus Ihse Bursie
In reply to this post by Mandy Chung


On 2017-04-08 00:14, Mandy Chung wrote:

>> On Apr 7, 2017, at 4:02 AM, Erik Joelsson <[hidden email]> wrote:
>>
>> Hello,
>>
>> This looks good in general. One thing I don't like about this is that if full docs is enabled, the docs-javadoc target now requires the full exploded image to be built first. I think that's unfortunate. Would it be possible to introduce separate targets for the gengraphs parts so that the main javadoc call can be run independently of most of the rest of the build, using the existing docs-javadoc target (and the newer docs-reference, even though I think that name is bit strange in this context)?
>>
> I agree with Erik that it’d be nice to separate the module graph generation
> and enable it to run with javadoc generation in parallel.  That’s one reason
> why docs-module-graphs was a separate target (I have no issue to take that
> target out from Main.gmk).
>
>
>> On 2017-04-07 10:40, Magnus Ihse Bursie wrote:
>>> Summary of changes:
>>> * A new option --enable-full-docs determines if module graphs should be created or not. (In the future, even more optional but "difficult" documentation work might be added to depend on this.) This is enabled by default is all prerequisites are present.
>
> It might be okay to call this “full docs” when it includes the
> module graphs but I am not sure about the new option name.
>
> Can I build OpenJDK with the docs with module graphs when I
> have Graphviz installed? I would think we need a configure
> option to specify my local path to `dot` that will enable
> the module graph build.  Is it possible?
>
>>> This code only affects the build system and documentation. I intend to push it to jdk9 using the "noreg-doc" RDP2 exception.
>>>
> Yes this is makefile and docs-only change.  In addition, FC extension
> request for JDK-8173303 covers this issue [1].
>
>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8176785
>>> WebRev: http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.01
>>>
> common/autoconf/jdk-options.m4
>   172     if test "x$DTRACE_DEP_MISSING" = "xtrue"; then
>
> What is DTRACE_DEP_MISSING?
Oops! A copy/paste error. Thanks for catching it!
>
>   158 # gengraphs tool.
>   167     # generated by the gengraphs tool and store it in the target dir.
>
> Nit: I prefer to name the tool as `GenGraphs` rather than gengraphs.
Fixed.

/Magnus
>
> Mandy
> [1] https://bugs.openjdk.java.net/browse/JDK-8173303?focusedCommentId=14064511&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14064511

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8176785 Add build support to generate PNG file from .dot file

Magnus Ihse Bursie
In reply to this post by Magnus Ihse Bursie
On 2017-04-11 16:03, Magnus Ihse Bursie wrote:

> Here is an updated webrev:
> http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.04/ 
>
>
> This change does not stop requiring the full exploded image to be
> built first when building full docs. However, full-docs will no longer
> be automatically enabled, even when all prerequisites are present, so
> for normal uses (where the user does not give --enable-full-docs),
> this dependency will not be present.
>
> The problem here is that if we do that, we will end up with broken
> Javadoc in the image/docs directory, since the generated HTML will
> contain an "<img src="$m-graph.png"..>" tag, but the png file itself
> will not exist. During an offline discussion, this was deemed acceptable.

Obviously, miscommunication can arise even outside this mailing list.
:-) I misunderstood Erik. Here's yet another (hopefully final) version
of the patch, which does split the generation in two separate steps.
This change introduces target names which will hopefully make it harder
to accidentally build broken documentation, even though it will be
possible if you try really hard. :)

The idea behind the new name schema is that the docs image after JEP 299
will end up with two directories, "api" and "specs", and we'll have a
docs image for jdk (the "normal" docs image) and a special image
containing the Java SE documentation only, to serve as reference for the
Java SE specification ("javase-docs").

So we get docs-jdk and docs-javase for the two respective top-level
targets. Then we break them down in docs-jdk-api and docs-jdk-specs
(will be created in a separate change). And finally, docs-jdk-api
consists of docs-jdk-api-javadocs and, if running with full docs,
docs-jdk-api-modulegraph. Running any of the two latter targets
individually will result in a non-consistent api directory, but running
any of docs-jdk-api or docs-jdk will ensure it's consistent.

http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.05

/Magnus

> I have changed the names of the targets to be more clear. Now we have
> "docs-jdk" and "docs-javase" as the "top level" javadoc targets. For
> these, we (currently) have the sub-targets "docs-jdk-javadoc" and
> "docs-javase-javadoc", but as part of JEP 299, more will soon follow.
> I have kept "docs-javadoc" as a legacy alias for "docs-jdk-javadoc".
>
> I have also incorporated the fixes from Mandy's comment.
>
> /Magnus
>
>
> On 2017-04-07 13:02, Erik Joelsson wrote:
>> Hello,
>>
>> This looks good in general. One thing I don't like about this is that
>> if full docs is enabled, the docs-javadoc target now requires the
>> full exploded image to be built first. I think that's unfortunate.
>> Would it be possible to introduce separate targets for the gengraphs
>> parts so that the main javadoc call can be run independently of most
>> of the rest of the build, using the existing docs-javadoc target (and
>> the newer docs-reference, even though I think that name is bit
>> strange in this context)?
>>
>> /Erik
>>
>>
>> On 2017-04-07 10:40, Magnus Ihse Bursie wrote:
>>> This bug is the continuation of JDK-8173303, in which Mandy added
>>> the generation of .dot files for @moduleGraph Javadoc tags.
>>>
>>> With this patch, the code is taken to it's completion, and the
>>> temporarily solutions left in place by JDK-8173303 has been replaced
>>> by properly integrated solutions.
>>>
>>> Summary of changes:
>>> * A new option --enable-full-docs determines if module graphs should
>>> be created or not. (In the future, even more optional but
>>> "difficult" documentation work might be added to depend on this.)
>>> This is enabled by default is all prerequisites are present.
>>> * It is not impossible to get to a state of the documentation with
>>> broken img links.
>>> * I have re-introduced SetupJavadocGeneration to stop the code
>>> duplication between JDK and Java SE javadoc builds.
>>> * I have fixed a bug in how the makefiles determines the
>>> dependencies of modules. This only affected a single module in
>>> nashorn, and no nashorn build code used these dependencies, so
>>> that's why it has gone unnoticed until now. I have verified that no
>>> other changes in module dependencies are introduced by this fix.
>>> * Javadoc source code dependencies are now correct even for
>>> transitive modules
>>> * Support added for the creation and use in jib of a "graphviz" module.
>>>
>>> This code is dependent on JDK-8172312. This webrev is done as a diff
>>> against the latest published webrev of JDK-8172312. JDK-8172312 is
>>> reviewed, but is currently awaiting the status for JEP 299 to be
>>> changed to Targeted before it can be pushed.
>>>
>>> This code only affects the build system and documentation. I intend
>>> to push it to jdk9 using the "noreg-doc" RDP2 exception.
>>>
>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8176785
>>> WebRev:
>>> http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.01
>>>
>>
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8176785 Add build support to generate PNG file from .dot file

Erik Joelsson
Looks good, thanks!

/Erik


On 2017-04-12 15:14, Magnus Ihse Bursie wrote:

> On 2017-04-11 16:03, Magnus Ihse Bursie wrote:
>> Here is an updated webrev:
>> http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.04/ 
>>
>>
>> This change does not stop requiring the full exploded image to be
>> built first when building full docs. However, full-docs will no
>> longer be automatically enabled, even when all prerequisites are
>> present, so for normal uses (where the user does not give
>> --enable-full-docs), this dependency will not be present.
>>
>> The problem here is that if we do that, we will end up with broken
>> Javadoc in the image/docs directory, since the generated HTML will
>> contain an "<img src="$m-graph.png"..>" tag, but the png file itself
>> will not exist. During an offline discussion, this was deemed
>> acceptable.
>
> Obviously, miscommunication can arise even outside this mailing list.
> :-) I misunderstood Erik. Here's yet another (hopefully final) version
> of the patch, which does split the generation in two separate steps.
> This change introduces target names which will hopefully make it
> harder to accidentally build broken documentation, even though it will
> be possible if you try really hard. :)
>
> The idea behind the new name schema is that the docs image after JEP
> 299 will end up with two directories, "api" and "specs", and we'll
> have a docs image for jdk (the "normal" docs image) and a special
> image containing the Java SE documentation only, to serve as reference
> for the Java SE specification ("javase-docs").
>
> So we get docs-jdk and docs-javase for the two respective top-level
> targets. Then we break them down in docs-jdk-api and docs-jdk-specs
> (will be created in a separate change). And finally, docs-jdk-api
> consists of docs-jdk-api-javadocs and, if running with full docs,
> docs-jdk-api-modulegraph. Running any of the two latter targets
> individually will result in a non-consistent api directory, but
> running any of docs-jdk-api or docs-jdk will ensure it's consistent.
>
> http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.05
>
> /Magnus
>
>> I have changed the names of the targets to be more clear. Now we have
>> "docs-jdk" and "docs-javase" as the "top level" javadoc targets. For
>> these, we (currently) have the sub-targets "docs-jdk-javadoc" and
>> "docs-javase-javadoc", but as part of JEP 299, more will soon follow.
>> I have kept "docs-javadoc" as a legacy alias for "docs-jdk-javadoc".
>>
>> I have also incorporated the fixes from Mandy's comment.
>>
>> /Magnus
>>
>>
>> On 2017-04-07 13:02, Erik Joelsson wrote:
>>> Hello,
>>>
>>> This looks good in general. One thing I don't like about this is
>>> that if full docs is enabled, the docs-javadoc target now requires
>>> the full exploded image to be built first. I think that's
>>> unfortunate. Would it be possible to introduce separate targets for
>>> the gengraphs parts so that the main javadoc call can be run
>>> independently of most of the rest of the build, using the existing
>>> docs-javadoc target (and the newer docs-reference, even though I
>>> think that name is bit strange in this context)?
>>>
>>> /Erik
>>>
>>>
>>> On 2017-04-07 10:40, Magnus Ihse Bursie wrote:
>>>> This bug is the continuation of JDK-8173303, in which Mandy added
>>>> the generation of .dot files for @moduleGraph Javadoc tags.
>>>>
>>>> With this patch, the code is taken to it's completion, and the
>>>> temporarily solutions left in place by JDK-8173303 has been
>>>> replaced by properly integrated solutions.
>>>>
>>>> Summary of changes:
>>>> * A new option --enable-full-docs determines if module graphs
>>>> should be created or not. (In the future, even more optional but
>>>> "difficult" documentation work might be added to depend on this.)
>>>> This is enabled by default is all prerequisites are present.
>>>> * It is not impossible to get to a state of the documentation with
>>>> broken img links.
>>>> * I have re-introduced SetupJavadocGeneration to stop the code
>>>> duplication between JDK and Java SE javadoc builds.
>>>> * I have fixed a bug in how the makefiles determines the
>>>> dependencies of modules. This only affected a single module in
>>>> nashorn, and no nashorn build code used these dependencies, so
>>>> that's why it has gone unnoticed until now. I have verified that no
>>>> other changes in module dependencies are introduced by this fix.
>>>> * Javadoc source code dependencies are now correct even for
>>>> transitive modules
>>>> * Support added for the creation and use in jib of a "graphviz"
>>>> module.
>>>>
>>>> This code is dependent on JDK-8172312. This webrev is done as a
>>>> diff against the latest published webrev of JDK-8172312.
>>>> JDK-8172312 is reviewed, but is currently awaiting the status for
>>>> JEP 299 to be changed to Targeted before it can be pushed.
>>>>
>>>> This code only affects the build system and documentation. I intend
>>>> to push it to jdk9 using the "noreg-doc" RDP2 exception.
>>>>
>>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8176785
>>>> WebRev:
>>>> http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.01
>>>>
>>>
>>
>

Loading...