missing bzl_library target for find_cc_toolchain.bzl if .bzl file being documented transitively loads rules_go

[abhinav]

Problem

If the .bzl file that we're generating documentation for imports rules_cc or anything that imports rules_cc, then stardoc is unable to generate documentation for any of these rules with the error:

ERROR: /Users/abhinav/src/stardoc-repro/BUILD.bazel:11:8: in deps attribute of starlark_doc_extract rule //:my_rule_docs.extract: missing bzl_library targets for Starlark module(s) @@rules_cc+//cc:find_cc_toolchain.bzl. Since this rule was created by the macro 'stardoc', the error might have been caused by the macro implementation
ERROR: /Users/abhinav/src/stardoc-repro/BUILD.bazel:11:8: Analysis of target '//:my_rule_docs.extract' failed

Specifically:

missing bzl_library targets for Starlark module(s) @@rules_cc+//cc:find_cc_toolchain.bzl

Reproduction

-- MODULE.bazel --
bazel_dep(name = "rules_go", version = "0.55.1")
bazel_dep(name = "stardoc", version = "0.8.0")
bazel_dep(name = "bazel_skylib", version = "1.8.1")

-- BUILD.bazel --
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
load("@stardoc//stardoc:stardoc.bzl", "stardoc")

bzl_library(
    name = "my_rule",
    srcs = ["my_rule.bzl"],
    visibility = ["//visibility:public"],
    deps = ["@rules_go//go:def"],
)

stardoc(
    name = "my_rule_docs",
    out = "my_rule.md",
    input = "my_rule.bzl",
    deps = [":my_rule"],
)

-- my_rule.bzl --
load("@rules_go//go:def.bzl", "go_test")

def go_helper_test(name, **kwargs):
    """A helper function to create a Go test target with specific attributes."""
    go_test(
        name = name,
        srcs = ["test_helper.go"],
        embed = [":helper_lib"],
        **kwargs
    )

bazel build :my_rule_docs fails with the above setup, but works if we drop the go_test import in my_rule.

Related issue

While this is probably an issue with rules_cc (bazelbuild/rules_cc#279), these targets definitely exist in the latest release: https://github.com/bazelbuild/rules_cc/blob/3dce172deec2a4563c28eae02a8bb18555abafb2/cc/BUILD#L85-L89

However, the above fails even if you add one of the following to the MODULE.bazel.

bazel_dep(name = "rules_cc", version = "0.1.2")
# or
single_version_override(module_name = "rules_cc", version = "0.1.2")

Bazel version

This fails with Bazel 8.3.1.

It works with Bazel 7.6.1, even without the rules_cc upgrade.

Workaround

For the go_test case above, there's currently a workaround:
upgrade rules_cc and explicitly add those bzl targets as dependencies:

    deps = [
        ":my_rule",
+       "@rules_cc//cc:find_cc_toolchain_bzl",
+       "@rules_cc//cc/common",
    ],

[tetromino]

This is not a bug - please see https://github.com/bazelbuild/stardoc/blob/master/docs/generating_stardoc.md#files-with-dependencies

In other words, if the .bzl file whose documentation you are generating imports some symbol from @some_repo//foo.bzl, you need to add the bzl_library target containing @some_repo//foo.bzl to stardoc's deps.

If there is a better way we should explain this in stardoc's documentation, I'm open to suggestions :)

[abhinav]

@tetromino right, adding dependencies to deps makes sense. And that's there:
my_rule in the example above imports @rules_go//go:def.bzl, and so it has deps = ["@rules_go//go:def"].

There are a couple problems here:

1. Where's this dependency coming from?

rules_cc, the dependency that the stardoc error complains about is not imported by my rule, or by rules_go:

❯ cd rules_go && rg rules_cc
WORKSPACE
26:    name = "rules_cc",
28:    strip_prefix = "rules_cc-0.0.16",
29:    urls = ["https://github.com/bazelbuild/rules_cc/releases/download/0.0.16/rules_cc-0.0.16.tar.gz"],

tests/core/transition/hermeticity_test.go
144:    name = "rules_cc",
146:    strip_prefix = "rules_cc-0.0.16",
147:    urls = ["https://github.com/bazelbuild/rules_cc/releases/download/0.0.16/rules_cc-0.0.16.tar.gz"],

I mean it's definitely being imported by a transitive dependency somewhere, but the error message doesn't have nearly enough information to guess where that missing bzl_target happened.

I don't know if this is an issue for stardoc specifically—maybe Bazel needs to print more information? (I'll defer to y'all on that.)
If there's a Bazel flag that will help find that out, I would be willing to add a troubleshooting section to stardoc documentation that mentions that for this error scenario.

2. bzl_library exists and is not picked up

The bzl_library has been defined in rules_cc 0.1.2, but it is not picked up by the bzl_library rule of whichever transitive dependency imports rules_cc.

This is arguably a bug in the module that is importing rules_cc, but again, I can't guess at which module that is from the error message. (If there's a way on figuring out which module that is, I'm happy to try to follow up with them as well.)

Either way, even if this is not a bug in stardoc specifically, it is a breakage in a pretty basic usage scenario: define a bzl_library that happens to depend on rules_go, generate stardoc, and it will fail.
As I didn't find an existing issue for this on this issue tracker, I figured this would be a good place to discuss the problem and workarounds, and maybe diagnose what dependency in the ecosystem is causing trouble.

[tetromino]

Thanks for the explanation.

If your rule does load("@rules_go//go:def.bzl", "go_test"), it should be sufficient to add the bzl_library target which contains "@rules_go//go:def.bzl" to the deps - in other words,@rules_go//go:def.

If that doesn't work, the most probable explanation is that @rules_go//go:def is missing some transitive dependencies, and we should file a bug against rules_go. Let me verify.

[tetromino]

Reported to rules_go at bazel-contrib/rules_go#4394

And until that's fixed, as a workaround, you can add rules_cc to MODULE.bazel, and "@rules_cc//cc:find_cc_toolchain_bzl", "@rules_cc//cc/common" to the deps of your bzl_library.

[abhinav]

Thanks for following up, @tetromino! Yep, per the issue above, the bzl_library target with the dep on rules_go wasn't sufficient, and I did work around this by manually adding the two rules_cc targets for now.

[tetromino]

Will be fixed by the next rules_go release.