github.com/bazelbuild/bazel-gazelle@v0.36.1-0.20240520142334-61b277ba6fed/tests/bzl_deps/bzl_test.bzl (about)

     1  """Macro for Ensuring Starlark Dependencies are Specified Properly"""
     2  
     3  load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
     4  load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
     5  
     6  def bzl_test(name, src, deps):
     7      """Provides build-time assurances that `bzl_library` declarations exist \
     8      and are referenced properly.
     9  
    10      This macro relies upon Stardoc's ability to traverse `bzl_library`
    11      dependencies. If a Starlark dependency is loaded, but not specified as a
    12      dependency, the Stardoc utility will fail with a reasonably helpful error
    13      message. Interestingly, the Stardoc utility does not apply the same rigor
    14      to files that are directly specifed to it.
    15  
    16      Another point worth metioning is that the `src` file cannot be generated
    17      for this macro to work. If one tries to use a generated file, the `input`
    18      for the `stardoc` rule will resolve to the label for the generated file
    19      which will cause the Stardoc utility to not find the file. Specifying the
    20      input in different ways (i.e. filename vs target name) did not seem to
    21      affect this behavior.
    22  
    23      Args:
    24          name: The name of the build target.
    25          src: A non-generated Starlark file that loads the `bzl_library` that is
    26               being checked.
    27          deps: A `list` of deps for the Starlark file.
    28  
    29      Returns:
    30      """
    31      macro_lib_name = name + "_macro_lib"
    32      bzl_library(
    33          name = macro_lib_name,
    34          srcs = [src],
    35          deps = deps,
    36      )
    37  
    38      stardoc(
    39          name = name,
    40          out = macro_lib_name + ".md_",
    41          input = src,
    42          deps = [macro_lib_name],
    43      )