Make get_default_canonical_id public

.devcontainer/Dockerfile

@@ -0,0 +1,37 @@
+FROM ubuntu:24.10
+
+# Update package lists
+RUN apt-get update
+
+RUN apt-get install -y \
+    # Required to build Bazel - https://bazel.build/install/compile-source#build-bazel-on-unixes
+    # NOTE python3 already installed, python2 is no longer supported
+    build-essential \
+    openjdk-21-jdk \
+    zip \
+    unzip \
+    # Dev utils
+    git \
+    curl
+
+# Install bazelisk, buildifier, buildozer, unused_deps, starpls (amd64 only)
+ARG TARGETARCH
+RUN if [ $TARGETARCH = "arm64" ]; then \
+        curl https://github.com/bazelbuild/bazelisk/releases/download/v1.20.0/bazelisk-linux-arm64 -Lo /usr/local/bin/bazel ; \
+        curl https://github.com/bazelbuild/buildtools/releases/download/v7.1.2/buildifier-linux-arm64 -Lo /usr/local/bin/buildifier ; \
+        curl https://github.com/bazelbuild/buildtools/releases/download/v7.1.2/buildozer-linux-arm64 -Lo /usr/local/bin/buildozer ; \
+        curl https://github.com/bazelbuild/buildtools/releases/download/v7.1.2/unused_deps-linux-arm64 -Lo /usr/local/bin/unused_deps ; \
+    fi
+RUN if [ $TARGETARCH = "amd64" ]; then \
+        curl https://github.com/bazelbuild/bazelisk/releases/download/v1.20.0/bazelisk-linux-amd64 -Lo /usr/local/bin/bazel ; \
+        curl https://github.com/bazelbuild/buildtools/releases/download/v7.1.2/buildifier-linux-amd64 -Lo /usr/local/bin/buildifier ; \
+        curl https://github.com/bazelbuild/buildtools/releases/download/v7.1.2/buildozer-linux-amd64 -Lo /usr/local/bin/buildozer ; \
+        curl https://github.com/bazelbuild/buildtools/releases/download/v7.1.2/unused_deps-linux-amd64 -Lo /usr/local/bin/unused_deps ; \
+        curl https://github.com/withered-magic/starpls/releases/download/v0.1.14/starpls-linux-amd64 -Lo /usr/local/bin/starpls ; \
+    fi
+RUN chmod +x /usr/local/bin/bazel /usr/local/bin/buildifier /usr/local/bin/buildozer /usr/local/bin/unused_deps
+RUN if [ $TARGETARCH = "amd64" ]; then \
+        chmod +x /usr/local/bin/starpls ; \
+    fi
+
+CMD [ "bash"]

.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+{
+	"name": "Bazel from master",
+	"build": {
+		"dockerfile": "./Dockerfile"
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"bazelbuild.vscode-bazel",
+				"zxh404.vscode-proto3",
+				"ms-vscode.cpptools",
+				"galexite.bazel-cpp-tools",
+				"siliconsoldier.java-with-bazel"
+			],
+			"settings": {
+				"bazel.enableCodeLens": true,
+				"bazel.lsp.command": "starpls",
+				"bazel.lsp.args": ["server"]
+			}
+		}
+	}
+}

src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java

@@ -602,7 +602,16 @@ private StructImpl completeDownload(PendingDownload pendingDownload)
           "Downloads a file to the output path for the provided url and returns a struct"
               + " containing <code>success</code>, a flag which is <code>true</code> if the"
               + " download completed successfully, and if successful, a hash of the file"
-              + " with the fields <code>sha256</code> and <code>integrity</code>.",
+              + " with the fields <code>sha256</code> and <code>integrity</code>."
+              + "Setting an explicit <code>canonical_id</code> is highly recommended. e.g."
+              + "<pre class='language-python'>\n"
+              + "load(\"@bazel_tools//tools/build_defs/repo:cache.bzl\", \"get_default_canonical_id\")\n"
+              + "# ...\n"
+              + "    repository_ctx.download(\n"
+              + "        url = urls,\n"
+              + "        canonical_id = get_default_canonical_id(repository_ctx, urls),\n"
+              + "    ),\n"
+              + "</pre>",
       useStarlarkThread = true,
       parameters = {
         @Param(
@@ -782,7 +791,16 @@ public Object download(
           "Downloads a file to the output path for the provided url, extracts it, and returns a"
               + " struct containing <code>success</code>, a flag which is <code>true</code> if the"
               + " download completed successfully, and if successful, a hash of the file with the"
-              + " fields <code>sha256</code> and <code>integrity</code>.",
+              + " fields <code>sha256</code> and <code>integrity</code>."
+              + "Setting an explicit <code>canonical_id</code> is highly recommended. e.g."
+              + "<pre class='language-python'>\n"
+              + "load(\"@bazel_tools//tools/build_defs/repo:cache.bzl\", \"get_default_canonical_id\")\n"
+              + "# ...\n"
+              + "    repository_ctx.download_and_extract(\n"
+              + "        url = urls,\n"
+              + "        canonical_id = get_default_canonical_id(repository_ctx, urls),\n"
+              + "    ),\n"
+              + "</pre>",
       useStarlarkThread = true,
       parameters = {
         @Param(

tools/build_defs/repo/BUILD

@@ -40,6 +40,7 @@ genrule(
 )
 
 REPO_BZL_FILES = [
+    "cache",
     "git",
     "http",
     "local",

tools/build_defs/repo/cache.bzl

@@ -20,7 +20,7 @@
 
 """Returns the default canonical id to use for downloads."""
 
-visibility("private")
+visibility("public")
 
 DEFAULT_CANONICAL_ID_ENV = "BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID"
 
@@ -37,7 +37,14 @@ machines without the file in the cache. This behavior can be disabled with
 """.format(env = DEFAULT_CANONICAL_ID_ENV)
 
 def get_default_canonical_id(repository_ctx, urls):
-    """Returns the default canonical id to use for downloads."""
+    """Returns the default canonical id to use for downloads.
+
+    Args:
+      repository_ctx: The repository context of the repository rule calling this utility
+        function.
+      urls: A list of URLs matching what is passed to `repository_ctx.download` and
+        `repository_ctx.download_and_extract`.
+    """
     if repository_ctx.os.environ.get(DEFAULT_CANONICAL_ID_ENV) == "0":
         return ""