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
