From caa54b0b322d5024c8d3e053904022014c987c93 Mon Sep 17 00:00:00 2001 From: Jordan Mele Date: Thu, 18 Jul 2024 22:33:07 -0700 Subject: [PATCH] Document source of truth for `rctx.download*` cache key MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documenting the default caching behaviour for `rctx.download` and `rctx.download_and_extract`.   Related to #22652 Closes #22716. PiperOrigin-RevId: 653878029 Change-Id: I129f9eede2b841483a98d5335651c1d1198aaf76 --- .../starlark/StarlarkBaseExternalContext.java | 21 ++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java index 901deae6939223..c250dfe966049c 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java @@ -632,7 +632,10 @@ private StructImpl completeDownload(PendingDownload pendingDownload) + " This must match the SHA-256 hash of the file downloaded. It is a security" + " risk to omit the SHA-256 as remote files can change. At best omitting this" + " field will make your build non-hermetic. It is optional to make development" - + " easier but should be set before shipping."), + + " easier but should be set before shipping." + + " If provided, the repository cache will first be checked for a file with the" + + " given hash; a download will only be attempted if the file was not found in" + + " the cache. After a successful download, the file will be added to the cache."), @Param( name = "executable", defaultValue = "False", @@ -651,7 +654,8 @@ private StructImpl completeDownload(PendingDownload pendingDownload) named = true, doc = "If set, restrict cache hits to those cases where the file was added to the cache" - + " with the same canonical id"), + + " with the same canonical id. By default caching uses the checksum" + + "(sha256 or integrity)."), @Param( name = "auth", defaultValue = "{}", @@ -672,7 +676,10 @@ private StructImpl completeDownload(PendingDownload pendingDownload) + " This must match the checksum of the file downloaded. It is a security" + " risk to omit the checksum as remote files can change. At best omitting this" + " field will make your build non-hermetic. It is optional to make development" - + " easier but should be set before shipping."), + + " easier but should be set before shipping." + + " If provided, the repository cache will first be checked for a file with the" + + " given checksum; a download will only be attempted if the file was not found in" + + " the cache. After a successful download, the file will be added to the cache."), @Param( name = "block", defaultValue = "True", @@ -852,7 +859,8 @@ public Object download( named = true, doc = "If set, restrict cache hits to those cases where the file was added to the cache" - + " with the same canonical id"), + + " with the same canonical id. By default caching uses the checksum" + + "(sha256 or integrity)."), @Param( name = "auth", defaultValue = "{}", @@ -873,7 +881,10 @@ public Object download( + " This must match the checksum of the file downloaded. It is a security" + " risk to omit the checksum as remote files can change. At best omitting this" + " field will make your build non-hermetic. It is optional to make development" - + " easier but should be set before shipping."), + + " easier but should be set before shipping." + + " If provided, the repository cache will first be checked for a file with the" + + " given checksum; a download will only be attempted if the file was not found in" + + " the cache. After a successful download, the file will be added to the cache."), @Param( name = "rename_files", defaultValue = "{}",