From 5833641b3c96cb862226105d119196e2bf05fb77 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 fda4fac76a9f65..5df934f7e1fd96 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 @@ -637,7 +637,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", @@ -660,7 +663,8 @@ private StructImpl completeDownload(PendingDownload pendingDownload) 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", @@ -683,7 +687,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", @@ -879,7 +886,8 @@ public Object download( 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", @@ -902,7 +910,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",