From 87d994e8eb8dda5042467a003c568a53dc9261c6 Mon Sep 17 00:00:00 2001 From: Andreas Herrmann Date: Wed, 1 Mar 2023 05:12:34 -0800 Subject: [PATCH] Document module extension identity Closes #17633 Adds a section to the module extension documentation about the identity of module extensions as described in https://github.com/bazelbuild/bazel/issues/17564#issuecomment-1448442715. Closes #17634. PiperOrigin-RevId: 513206202 Change-Id: I8cdc8ef836b0a119911b04aa7efb4f9882c72f54 --- site/en/external/extension.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/site/en/external/extension.md b/site/en/external/extension.md index 26dd228514ede1..90f5490864d322 100644 --- a/site/en/external/extension.md +++ b/site/en/external/extension.md @@ -113,6 +113,25 @@ def _maven_impl(ctx): _generate_hub_repo(name = "maven", repo_attrs) ``` +### Extension identity + +Module extensions are identified by the name and the `.bzl` file that appears +in the call to `use_extension`. In the following example, the extension `maven` +is identified by the `.bzl` file `@rules_jvm_external//:extension.bzl` and the +name `maven`: + +```python +maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven") +``` + +Re-exporting an extension from a different `.bzl` file gives it a new identity +and if both versions of the extension are used in the transitive module graph, +then they will be evaluated separately and will only see the tags associated +with that particular identity. + +As an extension author you should make sure that users will only use your +module extension from one single `.bzl` file. + ## Repository names and visibility Repos generated by extensions have canonical names in the form of `{{ "" @@ -141,4 +160,4 @@ several repo visibility rules: * This might result in a conflict. If the module repo can see a repo with the apparent name `foo`, and the extension generates a repo with the specified name `foo`, then for all repos generated by that extension - `foo` refers to the former. \ No newline at end of file + `foo` refers to the former.