Reducing dependencies for docs

[Magnus Ihse Bursie]

On 2018-12-12 02:47, Dan Smith wrote:
>> On Dec 11, 2018, at 5:28 PM, Erik Joelsson <erik.joelsson at oracle.com> wrote:
>>
>>> - 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.
> Ah, okay. That explains why 'make gensrc' does so much compilation.
But still, as I said in my previous mail, it should only do so once, not 
on each incremental build.

>
> But that's not the issue I'm raising here. What I'm observing is that the javadoc targets—like, say, 'make docs-javase-api', seem to depend on 'exploded-image'. I get various errors from 'make docs-javase-api-only', which I interpreted to mean that the javadoc targets are requiring compiled classes, but I could be wrong.
The modulegraph generation requires compiled classes. But it is only 
enabled if you are running with full docs. Otoh, it is possible that we 
enable full docs automatically if all prerequisites are present. 
Nevertheless, asking for just docs-jdk-specs should not require all 
classes. In fact, just building specs should be pretty standalone. 
However, it requires hotspot and jdk.jdi gensrc, since they are creating 
the jvmti and jdwp specs as part of the gensrc procedure. Ideally, this 
should be done by the specs target instead. But as things stand now, the 
specs are sort of a by-product of gensrc generation, and splitting it 
out into Docs.gmk will result in duplication of effort.

However, the question is how much to push this. With my fix removing the 
dependencies for the index, my local compile time for "docs-jdk-specs" 
was 20 seconds, from a clean build, and 4 seconds on an incremental 
build with no changes. For an, admittedly, somewhat uncommon single 
target, I think this is acceptable.
>
> Ideally, all the targets invoked for 'make docs' should need, _at most_, 'gensrc'. Then it might be worth looking at refining the dependency on gensrc.
>
>> 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.
> Would it be reasonable to filter out all 'jdk.internal.*' modules? That wouldn't require ongoing maintenance, and would eliminate most of the gensrc cost.
>
I thought your worry was the specs target? Filtering out gensrc from all 
modules will only help with the docs-jdk-javadoc target. But sure, it 
can probably be done.

Update: I tried this, but it didn't help. We're still compiling 
java.base for the remaining gensrc targets. I'm not sure why, and right 
now I don't have the time to find out.

/Magnus