Reducing dependencies for docs

[Erik Joelsson]

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.)
> - 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.

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