Using bzlmod makes stardoc unable to find dependencies

[keith]

With apple_support we have initial bzlmod support checked in, but it seems like with bazel 5.0.0, stardoc cannot find the dependencies defined by the MODULE.bzl:

$ bazel build doc:rules_doc --experimental_enable_bzlmod
INFO: Build option --check_visibility has changed, discarding analysis cache.
INFO: Analyzed target //doc:rules_doc (0 packages loaded, 469 targets configured).
INFO: Found 1 target...
ERROR: /Users/ksmiley/dev/apple_support/doc/BUILD:27:12: Generating proto for Starlark doc for rules_doc failed: (Exit 1): stardoc failed: error executing command bazel-out/host/bin/external/stardoc.0.5.0/stardoc/stardoc '--input=//rules:rules.doc.bzl' '--workspace_name=build_bazel_apple_support' '--symbols=apple_genrule' '--symbols=universal_binary' ... (remaining 3 arguments skipped)

Use --sandbox_debug to see verbose messages from the sandbox
com.google.devtools.build.skydoc.SkydocMain$StarlarkEvaluationException: File rules/private/apple_genrule.bzl imported '@bazel_skylib//lib:dicts.bzl', yet external/bazel_skylib/lib/dicts.bzl was not found, even at roots [., external/build_bazel_apple_support].
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:412)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:402)
        at com.google.devtools.build.skydoc.SkydocMain.eval(SkydocMain.java:260)
        at com.google.devtools.build.skydoc.SkydocMain.main(SkydocMain.java:163)
Caused by: java.nio.file.NoSuchFileException: external/bazel_skylib/lib/dicts.bzl
        at com.google.devtools.build.skydoc.SkydocMain.getInputSource(SkydocMain.java:454)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:385)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:402)
        ... 3 more
Stardoc documentation generation failed: File rules/private/apple_genrule.bzl imported '@bazel_skylib//lib:dicts.bzl', yet external/bazel_skylib/lib/dicts.bzl was not found, even at roots [., external/build_bazel_apple_support].
Target //doc:rules_doc failed to build
Use --verbose_failures to see the command lines of failed build steps.
INFO: Elapsed time: 0.749s, Critical Path: 0.43s
INFO: 2 processes: 2 internal.
FAILED: Build did NOT complete successfully

To repro checkout that repo at 0c8647eeabdb0943649dbdee07f3aee870079a51, and run:

USE_BAZEL_VERSION=5.0.0 bazelisk build doc:rules_doc --experimental_enable_bzlmod

If you disable bzlmod it works correctly.

[keith]

Ah maybe the same as bazelbuild/bazel#14140

[tetromino]

We need to update Stardoc's bundled jars - so I think we can fix this together with #119.

[tetromino]

I was wrong about my diagnosis; merely updating the jars from current Bazel HEAD doesn't fix it.

It seems we need to explicitly make Stardoc aware of modules, otherwise it doesn't know where on disk to find the imports when processing .bzl files. @Wyverald - any advice?

[Wyverald]

This is actually just the same issue as bazelbuild/bazel#14140 (as Keith noted above). So yes, we need to make Stardoc aware of modules (more precisely, of repo mappings -- since it could break even today).

It's been on the back of my mind but I haven't come up with a great solution. I was thinking maybe we need something like the runfiles library.

[fmeum]

Based on my understanding of Stardoc, it would actually be quite difficult to wire repo mapping support into the Java part of Stardoc. While Stardoc uses some Bazel classes (mostly the net.starlark part), it doesn't know about modules and thus wouldn't be able to derive the repository mapping by itself.

However, I think there might be an alternative approach that actually almost works today: If every Bazel module that wants to be documented by Stardoc uses a tag offered by the stardoc module, than the Starlark part of Stardoc could traverse the module graph via a module extension, dumping the modules and their versions into a .bzl file via a repository rule. The actual stardoc rule could then use that information to calculate the repo mapping and pass into the Stardoc binary via command-line arguments.

This comes with two caveats:

1. The module graph doesn't contain the information whether a module comes from an override, which causes the canonical repository name to be different (thanks to your truly ;-)).
2. The canonical repository names are meant to be internal and not part of public API, but maybe Stardoc could be an exception (and versioned with Bazel appropriately).

@Wyverald What do you think, is this approach promising?

[fmeum]

Well, I forgot about the important caveat that this won't work if .bzl files are loaded from module extensions or even for transitive dependencies that load .bzl.

Maybe Bazel should just dump the full repo mapping as a file (e.g. JSON) to a well-known location under external? Then Stardoc could just parse that file and derive the repo mapping from it.

[Kernald]

Any update on this? It's making adopting bzlmod quite tricky.

[fmeum]

@Wyverald @meteorcloudy If we agree on where to dump the repo mapping, I could work on this at some point during the next couple of weeks.

[fmeum]

I submitted a proposal on how to locate runfiles with Bzlmod: bazelbuild/proposals#269.
@tetromino I would highly appreciate if you could take a look at Section 5 of the proposal, which contains a proposed solution to this issue.

[keith]

What's the status of this with that merged? Looks to me like I still see the same issue with today's last_green bazel

[fmeum]

This will be fixed by bazelbuild/bazel#16775 and #141, which @comius is currently reviewing. The process to merge them is somewhat tricky as there is a cyclic dependency between Bazel and stardoc.

[rickeylev]

"me too" -- I was trying to use stardoc in rules_testing with bzlmod enabled and ran into this, too.

[tetromino]

Fixed by #141 and released as https://github.com/bazelbuild/stardoc/releases/tag/0.5.4