Reducing dependencies for docs

[Magnus Ihse Bursie]

On 2018-12-12 01:28, Erik Joelsson wrote:
> Hello Dan,
>
> On 2018-12-11 15:43, Dan Smith wrote:
>> Would it be possible to adjust the build system's handling of docs so 
>> that it is not necessary to do a complete compilation before the docs 
>> can be generated?
>>
>> I'm working with specs, and the following command does mostly what I 
>> want:
>> make jdk.jdi-gensrc hotspot-gensrc && make docs-jdk-specs-only
>>
>> But it would be nice to not have to resort to '-only' targets, when 
>> there's no real dependency on 99% of what happens when I use 'make 
>> docs-jdk-specs'.
> I do believe the dependency graph could be optimized some. I 
> appreciate that you dislike relying on the -only targets.
>> Specific proposals:
>>
>> - Change docs-jdk-specs so that it only depends on the gensrc phase. 
>> (I mean the actual source-generation phase, not the 'gensrc' target. 
>> For some reason when I do 'make gensrc', I end up waiting for lots of 
>> compilation, including java.base and jdk.internal.vm.compiler.)
> Looking at docs-jdk-specs, it requires docs-jdk-index, which in turn 
> requires exploded-image. I cannot see any reason why it would need 
> exploded-image, so that looks like the dependency to remove. Without 
> that, the prerequisite list becomes pretty small. (I would like to get 
> Magnus' to take a look too since he wrote this, but I believe this is 
> a mistake.)
Note that if you are doing full docs, you will also get exploded-image 
from the modulegraph. I don't think there's anything to do about that.

Yes, the requirement for docs-jdk-index is indeed incorrect. Probably 
some remnant from when I splitted up the single monolitical "docs" 
target, that depended on exploded-image.

Dan, please try if this patch helps you:
---
diff --git a/make/Main.gmk b/make/Main.gmk
--- a/make/Main.gmk
+++ b/make/Main.gmk
@@ -862,8 +862,6 @@
    docs-jdk-specs: $(JVM_DOCS_TARGETS) jdk.jdi-gensrc \
        docs-jdk-index

-  docs-jdk-index: exploded-image buildtools-modules
-
    docs-zip: docs-jdk

    # Tests
---

>> - Perhaps gensrc is not the right mechanism for what jdk.jdi and 
>> hotspot are trying to do? I don't know the details, other than that 
>> each produces a needed html file. The html generation could be made 
>> part of the 'docs-jdk-specs' target directly.
> Those two targets are very quick so should not be a problem.
>>
>> - Can we similarly eliminate dependencies from 'make docs'? Right 
>> now, the javadoc invocation requires compiled classes to be 
>> available, but I don't know if that's necessary. Maybe it will work 
>> just as well if it only has sources?
>>
> The jdk.internal.vm.compiler module is cause for a lot of grief in the 
> build with its generated source. The source generation there requires 
> large parts of the new java code to be compiled first.
But that should only happen once. Subsequent make calls should go 
quickly past this. If not, there's something wrong with the dependency 
check.

/Magnus
>
> The reason we depend on gensrc before API doc generation is to 
> guarantee that all source is available when the docs are to be 
> generated. If we can prove that no public classes are generated by 
> gensrc, then we could remove this dependency. If the modules with 
> public generated source are few and well defined, we could list them 
> specifically as prerequisites, but such an optimization is easy to 
> forget and may cause missing dependencies down the line. We could 
> perhaps also consider filtering the prerequisites list for docs 
> targets using the DOCS_MODULES list. There is no point requiring 
> gensrc for modules that aren't part of the docs, and 
> jdk.internal.vm.compiler certainly isn't.
>
> Please file a bug.
>
> /Erik
>