Modifying examples for gazelle and bzlmod

This commit removes bzlmod support from the build_file_generation
example and adds bzlmod support to the bzlmod example.

.bazelci/presubmit.yml

@@ -47,7 +47,7 @@ buildifier:
   build_targets: ["..."]
   test_targets: ["..."]
 .coverage_targets_example_bzlmod: &coverage_targets_example_bzlmod
-  coverage_targets: ["//:test"]
+  coverage_targets: ["//:bzlmod_test"]
 .coverage_targets_example_multi_python: &coverage_targets_example_multi_python
   coverage_targets:
     - //tests:my_lib_3_10_test
@@ -147,32 +147,6 @@ tasks:
     working_directory: examples/build_file_generation
     platform: windows
 
-  integration_test_build_file_generation_bzlmod_ubuntu:
-    <<: *minimum_supported_bzlmod_version
-    <<: *common_bzlmod_flags
-    <<: *reusable_build_test_all
-    name: build_file_generation_bzlmod integration tests on Ubuntu
-    working_directory: examples/build_file_generation
-    platform: ubuntu2004
-  integration_test_build_file_generation_bzlmod_debian:
-    <<: *common_bzlmod_flags
-    <<: *reusable_build_test_all
-    name: build_file_generation_bzlmod integration tests on Debian
-    working_directory: examples/build_file_generation
-    platform: debian11
-  integration_test_build_file_generation_bzlmod_macos:
-    <<: *common_bzlmod_flags
-    <<: *reusable_build_test_all
-    name: build_file_generation_bzlmod integration tests on macOS
-    working_directory: examples/build_file_generation
-    platform: macos
-  integration_test_build_file_generation_bzlmod_windows:
-    <<: *common_bzlmod_flags
-    <<: *reusable_build_test_all
-    name: build_file_generation_bzlmod integration tests on Windows
-    working_directory: examples/build_file_generation
-    platform: windows
-
   integration_test_bzlmod_ubuntu_min:
     <<: *minimum_supported_bzlmod_version
     <<: *reusable_build_test_all

examples/build_file_generation/WORKSPACE

@@ -16,23 +16,24 @@ load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 ######################################################################
 
 # Define an http_archive rule that will download the below ruleset,
-# test the sha, and extract the ruleset to you local bazel cache.
+# test the sha256, and extract the ruleset to you local bazel cache.
+
 http_archive(
     name = "io_bazel_rules_go",
-    sha256 = "099a9fb96a376ccbbb7d291ed4ecbdfd42f6bc822ab77ae6f1b5cb9e914e94fa",
+    sha256 = "6b65cb7917b4d1709f9410ffe00ecf3e160edf674b78c54a894471320862184f",
     urls = [
-        "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.35.0/rules_go-v0.35.0.zip",
-        "https://github.com/bazelbuild/rules_go/releases/download/v0.35.0/rules_go-v0.35.0.zip",
+        "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.39.0/rules_go-v0.39.0.zip",
+        "https://github.com/bazelbuild/rules_go/releases/download/v0.39.0/rules_go-v0.39.0.zip",
     ],
 )
 
 # Download the bazel_gazelle ruleset.
 http_archive(
     name = "bazel_gazelle",
-    sha256 = "448e37e0dbf61d6fa8f00aaa12d191745e14f07c31cabfa731f0c8e8a4f41b97",
+    sha256 = "727f3e4edd96ea20c29e8c2ca9e8d2af724d8c7778e7923a854b2c80952bc405",
     urls = [
-        "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.28.0/bazel-gazelle-v0.28.0.tar.gz",
-        "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.28.0/bazel-gazelle-v0.28.0.tar.gz",
+        "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.30.0/bazel-gazelle-v0.30.0.tar.gz",
+        "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.30.0/bazel-gazelle-v0.30.0.tar.gz",
     ],
 )
 
@@ -48,7 +49,7 @@ go_rules_dependencies()
 # go_rules_dependencies is a function that registers external dependencies
 # needed by the Go rules.
 # See: https://github.com/bazelbuild/rules_go/blob/master/go/dependencies.rst#go_rules_dependencies
-go_register_toolchains(version = "1.19.4")
+go_register_toolchains(version = "1.19.5")
 
 # The following call configured the gazelle dependencies, Go environment and Go SDK.
 gazelle_dependencies()

examples/bzlmod/BUILD.bazel

@@ -1,8 +1,22 @@
-load("@pip//:requirements.bzl", "requirement")
+# Load various rules so that we can have bazel download
+# various rulesets and dependencies.
+# The `load` statement imports the symbol for the rule, in the defined
+# ruleset. When the symbol is loaded you can use the rule.
+
+# The following code loads the base python requirements.
+load("@pip//:requirements.bzl", "all_whl_requirements")
 load("@python3_9//:defs.bzl", py_test_with_transition = "py_test")
 load("@rules_python//python:defs.bzl", "py_binary", "py_library", "py_test")
 load("@rules_python//python:pip.bzl", "compile_pip_requirements")
 
+# The following code loads the gazelle requirements.
+load("@bazel_gazelle//:def.bzl", "gazelle")
+load("@rules_python_gazelle_plugin//:def.bzl", "GAZELLE_PYTHON_RUNTIME_DEPS")
+load("@rules_python_gazelle_plugin//manifest:defs.bzl", "gazelle_python_manifest")
+load("@rules_python_gazelle_plugin//modules_mapping:def.bzl", "modules_mapping")
+
+# This stanza calls a rule that generates targets for managing pip dependencies
+# with pip-compile.
 compile_pip_requirements(
     name = "requirements",
     extra_args = ["--allow-unsafe"],
@@ -11,35 +25,76 @@ compile_pip_requirements(
     requirements_windows = "requirements_windows.txt",
 )
 
+# This repository rule fetches the metadata for python packages we
+# depend on. That data is required for the gazelle_python_manifest
+# rule to update our manifest file.
+modules_mapping(
+    name = "modules_map",
+    exclude_patterns = [
+        "^_|(\\._)+",  # This is the default.
+        "(\\.tests)+",  # Add a custom one to get rid of the psutil tests.
+    ],
+    wheels = all_whl_requirements,
+)
+
+# Gazelle python extension needs a manifest file mapping from
+# an import to the installed package that provides it.
+# This macro produces two targets:
+# - //:gazelle_python_manifest.update can be used with `bazel run`
+#   to recalculate the manifest
+# - //:gazelle_python_manifest.test is a test target ensuring that
+#   the manifest doesn't need to be updated
+gazelle_python_manifest(
+    name = "gazelle_python_manifest",
+    modules_mapping = ":modules_map",
+    pip_repository_name = "pip",
+    requirements = "//:requirements_lock.txt",
+    # NOTE: we can use this flag in order to make our setup compatible with
+    # bzlmod.
+    use_pip_repository_aliases = True,
+)
+
+# Our gazelle target points to the python gazelle binary.
+# This is the simple case where we only need one language supported.
+# If you also had proto, go, or other gazelle-supported languages,
+# you would also need a gazelle_binary rule.
+# See https://github.com/bazelbuild/bazel-gazelle/blob/master/extend.rst#example
+gazelle(
+    name = "gazelle",
+    data = GAZELLE_PYTHON_RUNTIME_DEPS,
+    gazelle = "@rules_python_gazelle_plugin//python:gazelle_binary",
+)
+
+# gazelle does not support transition tests yet
+# so we add the following directive for gazelle to ignore
+# the following rule.
+# gazelle:ignore
+py_test_with_transition(
+    name = "test_with_transition",
+    srcs = ["__test__.py"],
+    main = "__test__.py",
+    deps = [":bzlmod"],
+)
+
+# The following targets are created by gazelle
 py_library(
-    name = "lib",
+    name = "bzlmod",
     srcs = ["lib.py"],
-    deps = [
-        requirement("pylint"),
-        requirement("tabulate"),
-        requirement("python-dateutil"),
-    ],
+    visibility = ["//:__subpackages__"],
+    deps = ["@pip//tabulate"],
 )
 
 py_binary(
-    name = "bzlmod",
+    name = "bzlmod_bin",
     srcs = ["__main__.py"],
     main = "__main__.py",
     visibility = ["//:__subpackages__"],
-    deps = [
-        ":lib",
-    ],
+    deps = [":bzlmod"],
 )
 
 py_test(
-    name = "test",
-    srcs = ["test.py"],
-    deps = [":lib"],
-)
-
-py_test_with_transition(
-    name = "test_with_transition",
-    srcs = ["test.py"],
-    main = "test.py",
-    deps = [":lib"],
+    name = "bzlmod_test",
+    srcs = ["__test__.py"],
+    main = "__test__.py",
+    deps = [":bzlmod"],
 )

examples/bzlmod/MODULE.bazel

@@ -1,36 +1,89 @@
+# This file replaces the WORKSPACE file when using bzlmod.
+
+# Declares certain properties of the Bazel module represented by the current Bazel repo.
+# These properties are either essential metadata of the module (such as the name and version),
+# or affect behavior of the current module and its dependents.
 module(
     name = "example_bzlmod",
     version = "0.0.0",
     compatibility_level = 1,
 )
 
+# The following stanza defines the dependency rules_python.
+# For typical setups you set the version.
+# See the releases page for available versions.
+# https://github.com/bazelbuild/rules_python/releases
 bazel_dep(name = "rules_python", version = "0.0.0")
+
+# The following loads rules_python from the file system.
+# For usual setups you should remove this local_path_override block.
 local_path_override(
     module_name = "rules_python",
     path = "../..",
 )
 
+# The following stanza defines the dependency rules_python_gazelle_plugin.
+# For typical setups you set the version.
+# See the releases page for available versions.
+# https://github.com/bazelbuild/rules_python/releases
+bazel_dep(name = "rules_python_gazelle_plugin", version = "0.0.0")
+
+# The following starlark loads the gazelle plugin from the file system.
+# For usual setups you should remove this local_path_override block.
+local_path_override(
+    module_name = "rules_python_gazelle_plugin",
+    path = "../../gazelle",
+)
+
+# The following stanza defines the dependency for gazelle
+# See here https://github.com/bazelbuild/bazel-gazelle/releases/ for the
+# latest version.
+bazel_dep(name = "gazelle", version = "0.30.0", repo_name = "bazel_gazelle")
+
+# The following stanze returns a proxy object representing a module extension;
+# its methods can be invoked to create module extension tags.
 python = use_extension("@rules_python//python:extensions.bzl", "python")
+
+# Intialize the python toolchain.
+# You can set different Python versions in this block.
 python.toolchain(
     name = "python3_9",
     configure_coverage_tool = True,
     python_version = "3.9",
 )
+
+# Import the python repositories generated by the given module extension into the scope of the current module.
 use_repo(python, "python3_9")
 use_repo(python, "python3_9_toolchains")
 
+# Register an already-defined toolchain so that Bazel can use it during toolchain resolution.
 register_toolchains(
     "@python3_9_toolchains//:all",
 )
 
+# Use the pip extension
 pip = use_extension("@rules_python//python:extensions.bzl", "pip")
+
+# Use the extension to call the `pip_repository` rule that invokes `pip`, with `incremental` set.
+# Accepts a locked/compiled requirements file and installs the dependencies listed within.
+# Those dependencies become available in a generated `requirements.bzl` file.
+# You can instead check this `requirements.bzl` file into your repo.
+# Because this project has different requirements for windows vs other
+# operating systems, we have requirements for each.
 pip.parse(
     name = "pip",
+    # When using gazelle you must use set the following flag
+    # in order for the generation of gazelle dependency resolution.
+    incompatible_generate_aliases = True,
     requirements_lock = "//:requirements_lock.txt",
     requirements_windows = "//:requirements_windows.txt",
 )
+
+# Imports the pip toolchain generated by the given module extension into the scope of the current module.
 use_repo(pip, "pip")
 
+# This project includes a different module that is on the local file system.
+# Add the module to this parent project.
 bazel_dep(name = "other_module", version = "", repo_name = "our_other_module")
 local_path_override(
     module_name = "other_module",