Reducing dependencies for docs (original) (raw)

Magnus Ihse Bursie magnus.ihse.bursie at oracle.com
Wed Dec 12 13:39:50 UTC 2018

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

- 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 DOCSMODULES 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

More information about the build-dev mailing list