bazel-contrib / bazel-contrib/rules_jvm_external

Javadoc with neverlink dependencies

Open
#680 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
373
Forks
301
Avg merge
7d 17h
Merged PRs (30d)
3

Description

When the javadoc rule builds the classpath for generating documentation it includes the `JavaInfo.transitive_runtime_deps` of the dependency set. This causes a failure when there's a `neverlink = True` dependency in play, e.g. to provide IDE hint/compile-time annotations:

```
INFO: From Action foo/libfoo-javadoc.jar:
javadoc -cp -notimestamp -use -quiet -Xdoclint:-missing -encoding UTF8 --frames -html5 -d /tmp/output-dir5411169893580777571 /tmp/unpacked-sources6302970031594061577/com/example/foo/FooException.java /tmp/unpacked-sources6302970031594061577/com/example/foo/package-info.java /tmp/unpacked-sources6302970031594061577/com/example/foo/Foo.java
javadoc: warning - You have specified to generate frames, by using the --frames option.
The default is currently to not generate frames and the support for
frames will be removed in a future release.
To suppress this warning, remove the --frames option and avoid the use of frames.
/tmp/unpacked-sources6302970031594061577/com/example/foo/package-info.java:20: error: package org.springframework.lang does not exist
import org.springframework.lang.NonNullApi;
^
/tmp/unpacked-sources6302970031594061577/com/example/foo/package-info.java:17: error: cannot find symbol
@NonNullApi
^
symbol: class NonNullApi
2 errors
1 warning
```

I suspect the correct approach is to build the javadoc classpath from `JavaInfo.transitive_compile_time_jars` instead - at least, this seems to solve it in my fairly basic case. I'm happy to raise a PR, but is there a reason we might want the runtime dependency set instead? Or both?

```patch
diff --git a/private/rules/javadoc.bzl b/private/rules/javadoc.bzl
index 9b90570..bfa5759 100644
--- a/private/rules/javadoc.bzl
+++ b/private/rules/javadoc.bzl
@@ -19,7 +19,7 @@ def _javadoc_impl(ctx):

jar_file = ctx.actions.declare_file("%s.jar" % ctx.attr.name)

- classpath = depset(transitive = [dep[JavaInfo].transitive_runtime_jars for dep in ctx.attr.deps])
+ classpath = depset(transitive = [dep[JavaInfo].transitive_compile_time_jars for dep in ctx.attr.deps])

# javadoc options and javac options overlap, but we cannot
# necessarily rely on those to derive the javadoc options we need
```

Contributor guide

Open the contributing guide

Research direction

Start in private/rules/javadoc.bzl at the classpath construction in _javadoc_impl, and compare the JavaInfo dependency sets used there. Verify the javadoc action can resolve compile-time annotations from neverlink dependencies and completes without the reported missing-package errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
build-system
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.