From 3a24cf7c0dc187e006ba3a12cb1de390c87827c8 Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Wed, 11 Feb 2026 12:50:10 -0800 Subject: [PATCH 1/5] refactor: drop Java dependency - stop checking in generated stardoc outputs, they're an impediment to contributors making drive-by doc fixes in starlark (see #30) - fix a CI problem (bazel 9 introduced?) ERROR: /home/runner/work/rules_playwright/rules_playwright/tools/BUILD.bazel:3:12: //tools:stardoc_renderer: no such attribute 'main_class' in 'java_binary' rule - publish stardocs as protos on releases, which get rendered on the Bazel central registry site --- .bazelrc | 3 -- .bcr/source.template.json | 1 + .gitattributes | 3 -- .github/workflows/release_prep.sh | 9 +++++ MODULE.bazel | 8 ----- docs/BUILD.bazel | 25 ------------- docs/extensions.md | 42 ---------------------- docs/integrity_map.md | 60 ------------------------------- docs/repositories.md | 56 ----------------------------- playwright/BUILD.bazel | 22 ++++++++++++ tools/BUILD.bazel | 7 ---- 11 files changed, 32 insertions(+), 204 deletions(-) delete mode 100644 .gitattributes delete mode 100644 docs/BUILD.bazel delete mode 100644 docs/extensions.md delete mode 100644 docs/integrity_map.md delete mode 100644 docs/repositories.md diff --git a/.bazelrc b/.bazelrc index 87c12d7..5580b48 100644 --- a/.bazelrc +++ b/.bazelrc @@ -22,9 +22,6 @@ build:release --@rules_rust//rust/settings:lto=fat common --per_file_copt=external/.*protobuf.*@--PROTOBUF_WAS_NOT_SUPPOSED_TO_BE_BUILT common --host_per_file_copt=external/.*protobuf.*@--PROTOBUF_WAS_NOT_SUPPOSED_TO_BE_BUILT -# Stardoc needs a jdk; give a hermetic one -common --java_runtime_version=remotejdk_11 - # Load any settings specific to the current user. # .bazelrc.user should appear in .gitignore so that settings are not shared with team members # This needs to be last statement in this diff --git a/.bcr/source.template.json b/.bcr/source.template.json index 7fb5985..fcfcf03 100644 --- a/.bcr/source.template.json +++ b/.bcr/source.template.json @@ -1,5 +1,6 @@ { "integrity": "**leave this alone**", "strip_prefix": "{REPO}-{VERSION}", + "docs_url": "https://github.com/{OWNER}/{REPO}/releases/download/{TAG}/{REPO}-{TAG}.docs.tar.gz", "url": "https://github.com/{OWNER}/{REPO}/releases/download/{TAG}/{REPO}-{TAG}.tar.gz" } diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 8a4fa13..0000000 --- a/.gitattributes +++ /dev/null @@ -1,3 +0,0 @@ -# In code review, collapse generated files -docs/*.md linguist-generated=true - diff --git a/.github/workflows/release_prep.sh b/.github/workflows/release_prep.sh index 04bb4a4..8b46596 100755 --- a/.github/workflows/release_prep.sh +++ b/.github/workflows/release_prep.sh @@ -15,6 +15,15 @@ ARCHIVE="rules_playwright-$TAG.tar.gz" git archive --format=tar --prefix=${PREFIX}/ ${TAG} | gzip > $ARCHIVE SHA=$(shasum -a 256 $ARCHIVE | awk '{print $1}') +# Add generated API docs to the release +# See https://github.com/bazelbuild/bazel-central-registry/blob/main/docs/stardoc.md +docs="$(mktemp -d)"; targets="$(mktemp)" +bazel --output_base="$docs" query --output=label --output_file="$targets" 'kind("starlark_doc_extract rule", //...)' +bazel --output_base="$docs" build --target_pattern_file="$targets" +tar --create --auto-compress \ + --directory "$(bazel --output_base="$docs" info bazel-bin)" \ + --file "$GITHUB_WORKSPACE/${ARCHIVE%.tar.gz}.docs.tar.gz" . + cat << EOF ## Using Bzlmod with Bazel 6 or greater diff --git a/MODULE.bazel b/MODULE.bazel index 86d1584..cacfebf 100644 --- a/MODULE.bazel +++ b/MODULE.bazel @@ -105,11 +105,3 @@ crate.from_cargo( ], ) use_repo(crate, "crate_index") - -http_jar = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_jar") - -http_jar( - name = "stardoc-prebuilt", - integrity = "sha256-jDi5ITmziwwiHCsfd8v0UOoraWXIAfICIll+wbpg/vE=", - urls = ["https://github.com/alexeagle/stardoc-prebuilt/releases/download/v0.7.1/renderer_deploy.jar"], -) diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel deleted file mode 100644 index c40d9f1..0000000 --- a/docs/BUILD.bazel +++ /dev/null @@ -1,25 +0,0 @@ -load("@aspect_bazel_lib//lib:docs.bzl", "stardoc_with_diff_test", "update_docs") - -stardoc_with_diff_test( - name = "integrity_map", - bzl_library_target = "//playwright:defs", - symbol_names = [ - "playwright_integrity_map", - "playwright_browser_matrix", - ], - renderer = "//tools:stardoc_renderer", -) - -stardoc_with_diff_test( - name = "extensions", - bzl_library_target = "//playwright:extensions", - renderer = "//tools:stardoc_renderer", -) - -stardoc_with_diff_test( - name = "repositories", - bzl_library_target = "//playwright:repositories", - renderer = "//tools:stardoc_renderer", -) - -update_docs(name = "update") diff --git a/docs/extensions.md b/docs/extensions.md deleted file mode 100644 index 4561bb6..0000000 --- a/docs/extensions.md +++ /dev/null @@ -1,42 +0,0 @@ - - -Extensions for bzlmod. - -Installs a playwright toolchain. -Every module can define a toolchain version under the default name, "playwright". -The latest of those versions will be selected (the rest discarded), -and will always be registered by rules_playwright. - -Additionally, the root module can define arbitrarily many more toolchain versions under different -names (the latest version will be picked for each name) and can register them as it sees fit, -effectively overriding the default named toolchain due to toolchain resolution precedence. - - - -## playwright - -
-playwright = use_extension("@rules_playwright//playwright:extensions.bzl", "playwright")
-playwright.repo(name, browsers_download_urls, browsers_json, integrity_map, integrity_path_map,
-                playwright_version)
-
- - -**TAG CLASSES** - - - -### repo - -**Attributes** - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | Base name for generated repositories, allowing more than one playwright toolchain to be registered. Overriding the default is only permitted in the root module. | Name | optional | `"playwright"` | -| browsers_download_urls | URLs to download playwright browsers from. Replace defaults if a mirror location is preferred. | List of strings | optional | `["https://playwright.azureedge.net", "https://playwright-akamai.azureedge.net", "https://playwright-verizon.azureedge.net"]` | -| browsers_json | Alternative to playwright_version. Skips downloading from unpkg | Label | optional | `None` | -| integrity_map | Deprecated: Mapping from brower target to integrity hash | Dictionary: String -> String | optional | `{}` | -| integrity_path_map | Mapping from browser path to integrity hash | Dictionary: String -> String | optional | `{}` | -| playwright_version | Explicit version of playwright to download browsers.json from | String | optional | `""` | - - diff --git a/docs/integrity_map.md b/docs/integrity_map.md deleted file mode 100644 index ca3f79d..0000000 --- a/docs/integrity_map.md +++ /dev/null @@ -1,60 +0,0 @@ - - -Public API re-exports - - - -## playwright_integrity_map - -
-load("@rules_playwright//playwright:defs.bzl", "playwright_integrity_map")
-
-playwright_integrity_map(name, browsers, output, silent)
-
- - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| browsers | A list of browser targets to generate integrity values for.

These targets should usually be the result of the playwright_browser_matrix() function, which creates a cross-product of browser names and platforms. Each target must provide the UnzippedBrowserInfo provider. | List of labels | optional | `[]` | -| output | The name of the output file to create containing the integrity map.

This file will contain the generated integrity values for the specified browsers. Defaults to "target_name.json" | String | optional | `""` | -| silent | Whether to suppress debug information output.

When set to False (default), the rule will print integrity information that users would typically copy and paste into their MODULE.bazel or WORKSPACE file. Set to True to prevent this debug output from being printed. | Boolean | optional | `False` | - - - - -## playwright_browser_matrix - -
-load("@rules_playwright//playwright:defs.bzl", "playwright_browser_matrix")
-
-playwright_browser_matrix(platforms, browser_names, playwright_repo_name, playright_repo_name)
-
- -Generates a list of Bazel target labels for browser dependencies. - -This function creates a cross-product of browser names and platforms, constructing -the appropriate Bazel target labels for each combination. - -"@{playright_repo_name}//browsers:{browser_name}-{platform}" - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| platforms | A list of platform identifiers (e.g., ['mac14-arm', 'ubuntu20.04-x64]). | none | -| browser_names | A list of browser names (e.g., ['chromium', 'firefox']). | none | -| playwright_repo_name | The name of the Playwright repository. | `None` | -| playright_repo_name | (DEPRECATED: use playwright_repo_name instead) The name of the Playwright repository. | `None` | - -**RETURNS** - -A list of browser labels to be used as the browsers attribute of the integrity_map rule. - - diff --git a/docs/repositories.md b/docs/repositories.md deleted file mode 100644 index 5b89f3f..0000000 --- a/docs/repositories.md +++ /dev/null @@ -1,56 +0,0 @@ - - -Declare runtime dependencies - -These are needed for local dev, and users must install them as well. -See https://docs.bazel.build/versions/main/skylark/deploying.html#dependencies - - - -## define_browsers - -
-load("@rules_playwright//playwright:repositories.bzl", "define_browsers")
-
-define_browsers(name, browser_integrity, browsers_download_urls, browsers_json, repo_mapping)
-
- -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this repository. | Name | required | | -| browser_integrity | A dictionary of browser names to their integrity hashes | Dictionary: String -> String | optional | `{}` | -| browsers_download_urls | URLs to download playwright browsers from. Replace defaults if a mirror location is preferred. | List of strings | optional | `["https://playwright.azureedge.net", "https://playwright-akamai.azureedge.net", "https://playwright-verizon.azureedge.net"]` | -| browsers_json | - | Label | optional | `None` | -| repo_mapping | In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).

This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | Dictionary: String -> String | optional | | - - - - -## playwright_repository - -
-load("@rules_playwright//playwright:repositories.bzl", "playwright_repository")
-
-playwright_repository(name, browsers_json, browsers_workspace_name_prefix, playwright_version,
-                      playwright_version_from, repo_mapping, rules_playwright_cannonical_name)
-
- -Fetch external tools needed for playwright toolchain - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this repository. | Name | required | | -| browsers_json | The browsers.json file to use. For example https://unpkg.com/playwright-core@1.51.0/browsers.json | Label | optional | `None` | -| browsers_workspace_name_prefix | The namespace prefix used when defining browser workspace repositories. | String | required | | -| playwright_version | The version of playwright to install | String | optional | `""` | -| playwright_version_from | The package.json file to use to find the version of playwright to install | Label | optional | `None` | -| repo_mapping | In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).

This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | Dictionary: String -> String | optional | | -| rules_playwright_cannonical_name | The cannonical name given to the rules_playwright repository. See https://bazel.build/external/module | String | required | | - - diff --git a/playwright/BUILD.bazel b/playwright/BUILD.bazel index 764e297..1953a7e 100644 --- a/playwright/BUILD.bazel +++ b/playwright/BUILD.bazel @@ -20,6 +20,16 @@ bzl_library( ], ) +starlark_doc_extract( + name = "defs.doc_extract", + src = "defs.bzl", + symbol_names = [ + "playwright_integrity_map", + "playwright_browser_matrix", + ], + deps = [":defs"], +) + bzl_library( name = "extensions", srcs = ["extensions.bzl"], @@ -32,6 +42,12 @@ bzl_library( ], ) +starlark_doc_extract( + name = "extensions.doc_extract", + src = "extensions.bzl", + deps = [":extensions"], +) + bzl_library( name = "repositories", srcs = ["repositories.bzl"], @@ -46,3 +62,9 @@ bzl_library( "@bazel_tools//tools/build_defs/repo:utils.bzl", ], ) + +starlark_doc_extract( + name = "repositories.doc_extract", + src = "repositories.bzl", + deps = [":repositories"], +) diff --git a/tools/BUILD.bazel b/tools/BUILD.bazel index 3eb7c65..e69de29 100644 --- a/tools/BUILD.bazel +++ b/tools/BUILD.bazel @@ -1,7 +0,0 @@ -package(default_visibility = ["//visibility:public"]) - -java_binary( - name = "stardoc_renderer", - main_class = "com/google/devtools/build/stardoc/renderer/RendererMain", - runtime_deps = ["@stardoc-prebuilt//jar"], -) From db226fde9c59aa539e392b4ae198407ae826d9ec Mon Sep 17 00:00:00 2001 From: Tyler Breisacher Date: Wed, 11 Feb 2026 11:49:55 -0800 Subject: [PATCH 2/5] Run the rules_playwright tests on CI --- .github/workflows/tests.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 8cbd7db..f84ffe7 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -27,6 +27,9 @@ jobs: - name: Install Playwright system dependencies run: npx playwright install-deps + - name: Build and Test rules_playwright + run: bazelisk test //... + - name: Build and Test WORKSPACE example working-directory: examples/workspace run: bazelisk test //... From 2d2ce9a3f98a9e0b14004b4ead598f03cc82e15d Mon Sep 17 00:00:00 2001 From: Tyler Breisacher Date: Thu, 5 Feb 2026 20:12:02 -0800 Subject: [PATCH 3/5] Upgrade deps --- MODULE.bazel | 6 +++--- examples/rules_js/MODULE.bazel | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/MODULE.bazel b/MODULE.bazel index cacfebf..f442b8c 100644 --- a/MODULE.bazel +++ b/MODULE.bazel @@ -8,9 +8,9 @@ module( bazel_dep(name = "bazel_skylib", version = "1.4.1") bazel_dep(name = "platforms", version = "0.0.10") -bazel_dep(name = "aspect_bazel_lib", version = "2.11.0") +bazel_dep(name = "aspect_bazel_lib", version = "2.22.5") -bazel_dep(name = "toolchains_musl", version = "0.1.20", dev_dependency = True) +bazel_dep(name = "toolchains_musl", version = "0.1.27", dev_dependency = True) toolchains_musl = use_extension( "@toolchains_musl//:toolchains_musl.bzl", @@ -21,7 +21,7 @@ toolchains_musl.config( extra_target_compatible_with = ["@//tools/linkers:musl"], ) -bazel_dep(name = "toolchains_llvm", version = "1.2.0", dev_dependency = True) +bazel_dep(name = "toolchains_llvm", version = "1.6.0", dev_dependency = True) # Configure and register the toolchain. llvm = use_extension("@toolchains_llvm//toolchain/extensions:llvm.bzl", "llvm", dev_dependency = True) diff --git a/examples/rules_js/MODULE.bazel b/examples/rules_js/MODULE.bazel index f5a5e4d..b626281 100644 --- a/examples/rules_js/MODULE.bazel +++ b/examples/rules_js/MODULE.bazel @@ -20,7 +20,7 @@ playwright.repo( ) use_repo(playwright, "playwright") -bazel_dep(name = "aspect_rules_js", version = "2.1.2") +bazel_dep(name = "aspect_rules_js", version = "2.9.2") npm = use_extension("@aspect_rules_js//npm:extensions.bzl", "npm", dev_dependency = True) npm.npm_translate_lock( From c3d323bc1f437520a0325a6d57aeb756e24ed44c Mon Sep 17 00:00:00 2001 From: Tyler Breisacher Date: Wed, 11 Feb 2026 13:18:46 -0800 Subject: [PATCH 4/5] Switch to Bazel 8 --- .bazelversion | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/.bazelversion b/.bazelversion index 4718f54..c6b7980 100644 --- a/.bazelversion +++ b/.bazelversion @@ -1,7 +1 @@ -latest -# The first line of this file is used by Bazelisk and Bazel to be sure -# the right version of Bazel is used to build and test this repo. -# This also defines which version is used on CI. -# -# Note that you should also run integration_tests against other Bazel -# versions you support. +8.x From 03c00759fcafbe31a1160ad5c7fe4bb03a7fdd4c Mon Sep 17 00:00:00 2001 From: Tyler Breisacher Date: Wed, 11 Feb 2026 13:21:35 -0800 Subject: [PATCH 5/5] ignore examples --- .bazelignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.bazelignore b/.bazelignore index 3f2d04e..31286f4 100644 --- a/.bazelignore +++ b/.bazelignore @@ -1,4 +1,4 @@ target/ node_modules/ -examples/rules_js +examples/ gen/ \ No newline at end of file