Fix non-bzlmod distribution (#172)

Since we are building the renderer from source and using rules_jvm_external to pull in Maven deps, the WORKSPACE setup for a user of Stardoc is now significantly more complicated; the user will now need to do the multi-step rules_jvm_external initialization and maven_install. For convenience, let's wrap maven_install in a macro - and finally split out the legacy-test-only maven deps into their own .json file and repo. Update stardoc_repositories to pull in all the new deps we need to build Java code. Update maintainer guide.
bazelbuild · Aug 3, 2023 · af19cfe · af19cfe
1 parent b8856b4
commit af19cfe
Show file tree

Hide file tree

Showing 10 changed files with 924 additions and 603 deletions.
diff --git a/MODULE.bazel b/MODULE.bazel
@@ -12,11 +12,12 @@ bazel_dep(name = "protobuf", version = "21.7", repo_name = "com_google_protobuf"
 
 maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")
 maven.install(
+    name = "stardoc_maven",
     # We don't yet specify the maven coordinates in the MODULE.bazel to avoid duplicating information.
     # Always respect the maven_install.json file generated by rules_jvm_external from the WORKSPACE file.
     lock_file = "//:maven_install.json",
     repositories = [
         "https://repo1.maven.org/maven2",
     ],
 )
-use_repo(maven, "maven")
+use_repo(maven, "stardoc_maven")
diff --git a/WORKSPACE b/WORKSPACE
@@ -5,19 +5,6 @@ load(":setup.bzl", "stardoc_repositories")
 
 stardoc_repositories()
 
-RULES_JVM_EXTERNAL_TAG = "4.5"
-
-RULES_JVM_EXTERNAL_SHA = "b17d7388feb9bfa7f2fa09031b32707df529f26c91ab9e5d909eb1676badd9a6"
-
-http_archive(
-    name = "rules_jvm_external",
-    patch_args = ["-p1"],
-    patches = ["//:rules_jvm_external.patch"],
-    sha256 = RULES_JVM_EXTERNAL_SHA,
-    strip_prefix = "rules_jvm_external-%s" % RULES_JVM_EXTERNAL_TAG,
-    url = "https://github.com/bazelbuild/rules_jvm_external/archive/refs/tags/%s.zip" % RULES_JVM_EXTERNAL_TAG,
-)
-
 load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")
 
 rules_jvm_external_deps()
@@ -26,18 +13,32 @@ load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")
 
 rules_jvm_external_setup()
 
+load(":deps.bzl", "stardoc_external_deps")
+
+stardoc_external_deps()
+
+load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install")
+
+stardoc_pinned_maven_install()
+
+### INTERNAL ONLY - lines after this are not included in the release packaging.
+#
+# Include dependencies which are only needed for development of Stardoc here.
+
+load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
+
+# Needed for generating the Stardoc release binary.
+git_repository(
+    name = "io_bazel",
+    commit = "b71b2df2b22e052f8540a23051b589c6ef870d0a",  # 2023-08-01
+    remote = "https://github.com/bazelbuild/bazel.git",
+)
+
 load("@rules_jvm_external//:defs.bzl", "maven_install")
 
+# Bazel's Maven dependencies - must live in @maven
 maven_install(
     artifacts = [
-        "com.beust:jcommander:1.82",
-        "com.google.escapevelocity:escapevelocity:1.1",
-        "com.google.guava:guava:31.1-jre",
-        "com.google.truth:truth:1.1.3",
-        "junit:junit:4.13.2",
-        # Artifacts below this line are only needed for building @io_bazel for
-        # stardoc_binary.jar integration tests. They should be removed once we
-        # fully migrate to starlark_doc_extract after Bazel 7.
         "com.github.ben-manes.caffeine:caffeine:3.0.5",
         "com.github.stephenc.jcip:jcip-annotations:1.0-1",
         "com.google.auto.service:auto-service-annotations:1.0.1",
@@ -53,6 +54,7 @@ maven_install(
         "com.google.flogger:flogger:0.5.1",
         "com.google.flogger:google-extensions:0.5.1",
         "com.google.guava:failureaccess:1.0.1",
+        "com.google.guava:guava:31.1-jre",
         "com.google.j2objc:j2objc-annotations:1.3",
         "com.ryanharter.auto.value:auto-value-gson-extension:1.3.1",
         "com.ryanharter.auto.value:auto-value-gson-runtime:1.3.1",
@@ -65,7 +67,7 @@ maven_install(
         "org.checkerframework:checker-qual:3.19.0",
     ],
     fail_if_repin_required = True,
-    maven_install_json = "//:maven_install.json",
+    maven_install_json = "//:legacy_maven_install.json",
     repositories = [
         "https://repo1.maven.org/maven2",
     ],
@@ -76,31 +78,6 @@ load("@maven//:defs.bzl", "pinned_maven_install")
 
 pinned_maven_install()
 
-http_archive(
-    name = "com_google_protobuf",
-    sha256 = "75be42bd736f4df6d702a0e4e4d30de9ee40eac024c4b845d17ae4cc831fe4ae",
-    strip_prefix = "protobuf-21.7",
-    urls = [
-        "https://mirror.bazel.build/github.com/protocolbuffers/protobuf/archive/v21.7.tar.gz",
-        "https://github.com/protocolbuffers/protobuf/archive/v21.7.tar.gz",
-    ],
-)
-
-load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps")
-
-### INTERNAL ONLY - lines after this are not included in the release packaging.
-#
-# Include dependencies which are only needed for development of Stardoc here.
-
-load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
-
-# Needed for generating the Stardoc release binary.
-git_repository(
-    name = "io_bazel",
-    commit = "b71b2df2b22e052f8540a23051b589c6ef870d0a",  # 2023-08-01
-    remote = "https://github.com/bazelbuild/bazel.git",
-)
-
 # The following binds are needed for building protobuf java libraries.
 bind(
     name = "guava",
@@ -182,7 +159,3 @@ http_archive(
         "https://github.com/BLAKE3-team/BLAKE3/archive/refs/tags/1.3.3.zip",
     ],
 )
-
-### END INTERNAL ONLY
-# protobuf_deps() must not be called before @rules_python are loaded (if they are loaded).
-protobuf_deps()
diff --git a/deps.bzl b/deps.bzl
@@ -0,0 +1,54 @@
+# Copyright 2023 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""WORKSPACE dependency definitions for Stardoc."""
+
+load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps")
+load("@rules_jvm_external//:defs.bzl", "maven_install")
+
+# Maven artifacts required by Stardoc
+STARDOC_MAVEN_ARTIFACTS = [
+    "com.beust:jcommander:1.82",
+    "com.google.escapevelocity:escapevelocity:1.1",
+    "com.google.guava:guava:31.1-jre",
+    "com.google.truth:truth:1.1.3",
+    "junit:junit:4.13.2",
+]
+
+def stardoc_external_deps():
+    """
+    Sets up Stardoc's workspace dependencies.
+
+    Requires stardoc_repositories() to be called first.
+
+    Normally should be followed up by
+
+    ```bzl
+        load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install")
+
+        stardoc_pinned_maven_install()
+    ```
+    """
+    protobuf_deps()
+
+    maven_install(
+        name = "stardoc_maven",
+        artifacts = STARDOC_MAVEN_ARTIFACTS,
+        fail_if_repin_required = True,
+        maven_install_json = "@io_bazel_stardoc//:maven_install.json",
+        repositories = [
+            "https://repo1.maven.org/maven2",
+        ],
+        strict_visibility = True,
+    )
diff --git a/docs/maintainers_guide.md b/docs/maintainers_guide.md
@@ -16,7 +16,11 @@ To update the jar:
 
 ## Making a New Release
 
-1.  Update CHANGELOG.md at the top. You may want to use the following template:
+1.  Verify tests. Verify that dependencies are consistent between `setup.bzl` +
+    `WORKSPACE` and `MODULE.bazel` (but note that `MODULE.bazel` does not
+    include dependencies on `io_bazel` and its transitive deps).
+2.  Update `CHANGELOG.md` at the top. You may want to use the following \
+    template:
 
 --------------------------------------------------------------------------------
 
@@ -38,22 +42,26 @@ Name 1, Name 2, Name 3 (alphabetically)
 
 --------------------------------------------------------------------------------
 
-2.  Bump `version` in version.bzl to the new version.
-3.  Ensure that the commits for steps 1 and 2 have been merged. All further
-    steps must be performed on a single, known-good git commit.
-4.  `bazel build //distro`
-5.  Copy the `stardoc-$VERSION.tar.gz` tarball to the mirror (you'll need Bazel
+3.  Bump `version` in `version.bzl` *and* `MODULE.bazel` to the new version.
+4.  Ensure that the commits for steps 1-3 have been merged. All further steps
+    must be performed on a single, known-good git commit.
+5.  `bazel build //distro`
+6.  Copy the `stardoc-$VERSION.tar.gz` tarball to the mirror (you'll need Bazel
     developer gcloud credentials; assuming you are a Bazel developer, you can
     obtain them via `gcloud init`):
 
-```
-gsutil cp bazel-bin/distro/stardoc-$VERSION.tar.gz gs://bazel-mirror/github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz
-gsutil setmeta -h "Cache-Control: public, max-age=31536000" "gs://bazel-mirror/github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz"
-```
+    ```bash
+    gsutil cp bazel-bin/distro/stardoc-$VERSION.tar.gz gs://bazel-mirror/github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz
+    gsutil setmeta -h "Cache-Control: public, max-age=31536000" "gs://bazel-mirror/github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz"
+    ```
+
+7.  Obtain checksum for release notes:
+
+    ```bash
+    sha256sum bazel-bin/distro/stardoc-$VERSION.tar.gz
+    ```
 
-6.  Run `sha256sum bazel-bin/distro/stardoc-$VERSION.tar.gz`; you'll need the
-    checksum for the release notes.
-7.  Draft a new release with a new tag named $VERSION in github. Attach
+8.  Draft a new release with a new tag named $VERSION in github. Attach
     `stardoc-$VERSION.tar.gz` to the release. For the release notes, use the
     CHANGELOG.md entry plus the following template:
 
@@ -63,7 +71,7 @@ gsutil setmeta -h "Cache-Control: public, max-age=31536000" "gs://bazel-mirror/g
 
 To use Stardoc, add the following to your `WORKSPACE` file:
 
-```
+```starlark
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 
 http_archive(
@@ -78,14 +86,69 @@ http_archive(
 load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
 
 stardoc_repositories()
+
+load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")
+
+rules_jvm_external_deps()
+
+load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")
+
+rules_jvm_external_setup()
+
+load("@io_bazel_stardoc//:deps.bzl", "stardoc_external_deps")
+
+stardoc_external_deps()
+
+load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install")
+
+stardoc_pinned_maven_install()
 ```
 
-The load statement and function call after the `io_bazel_stardoc` repository
-definition ensure that this repository's dependencies are loaded.
+The sequence of function calls and load statements after the `io_bazel_stardoc`
+repository definition ensures that this repository's dependencies are loaded
+(each function call defines additional repositories for Stardoc's dependencies,
+which are then used by subsequent load statements).
 
 **Using the rules**
 
 See [the source](https://github.com/bazelbuild/stardoc/tree/$VERSION).
 
 --------------------------------------------------------------------------------
 
+9.  Obtain [Subresource Integrity](https://w3c.github.io/webappsec-subresource-integrity/#integrity-metadata-description)
+    format checksum for bzlmod:
+
+```bash
+echo -n sha256-; cat bazel-bin/distro/stardoc-$VERSION.tar.gz | openssl dgst -sha256 -binary | base64
+```
+
+10. Create a PR at [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry)
+    to update the registry's versions of bazel_skylib and
+    bazel_skylib_gazelle_plugin.
+
+    Use https://github.com/bazelbuild/bazel-central-registry/pull/677 as the
+    model; you will need to update `modules/stardoc/metadata.json` to list the
+    new version in `versions`, and create new $VERSION subdirectories for the
+    updated module, using the latest existing version subdirectories as the
+    guide. Use Subresource Integrity checksums obtained above in the new
+    `source.json` file.
+
+    Ensure that the `MODULE.bazel` file you add in the new $VERSION
+    subdirectory exactly matches the `MODULE.bazel` file packaged in the
+    stardoc-$VERSION.tar.gz tarball - or buildkite checks will fail.
+
+11. Once the Bazel Central Registry PR is merged, insert in the release
+    description after the `WORKSPACE` setup section:
+
+--------------------------------------------------------------------------------
+
+**MODULE.bazel setup**
+
+```starlark
+bazel_dep(name = "stardoc", version = "$VERSION")
+```
+
+For compatibility with `WORKSPACE` setup, add `repo_name = "io_bazel_stardoc"`
+to the `bazel_dep` call.
+
+--------------------------------------------------------------------------------