From 67fcf78df06c7df147cb7d1024f1dd9350411830 Mon Sep 17 00:00:00 2001 From: Jordan Mele Date: Wed, 12 Jun 2024 15:58:26 +1000 Subject: [PATCH 1/3] Document `canonical_id` defaults for `rctx.download*` --- .../repository/starlark/StarlarkBaseExternalContext.java | 6 ++++-- 1 file changed, 4 insertions(+), 2 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 6bb495b895ba2c..de366c1a5a958f 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 @@ -625,7 +625,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 the checksum (`sha256` or" + + " `integrity`) is used otherwise caching is disabled."), @Param( name = "auth", defaultValue = "{}", @@ -825,7 +826,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 the checksum (`sha256` or" + + " `integrity`) is used otherwise caching is disabled."), @Param( name = "auth", defaultValue = "{}", From 23a82cba84222b3fe95ef0ecc11c19cc30ad3e00 Mon Sep 17 00:00:00 2001 From: Jordan Mele Date: Wed, 12 Jun 2024 16:12:18 +1000 Subject: [PATCH 2/3] Note cache behaviour in `sha256` and `integrity`, rephrase `canonical_id` --- .../starlark/StarlarkBaseExternalContext.java | 30 +++++++++++++------ 1 file changed, 21 insertions(+), 9 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 de366c1a5a958f..9271f97b729fb1 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 @@ -602,11 +602,15 @@ private StructImpl completeDownload(PendingDownload pendingDownload) defaultValue = "''", named = true, doc = - "the expected SHA-256 hash of the file downloaded." + "Expected SHA-256 hash of the file downloaded." + " 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", @@ -625,8 +629,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. By default the checksum (`sha256` or" - + " `integrity`) is used otherwise caching is disabled."), + + " with the same canonical id. By default caching uses the checksum" + + " (`sha256` or `integrity`)."), @Param( name = "auth", defaultValue = "{}", @@ -647,7 +651,11 @@ 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", @@ -784,7 +792,7 @@ public Object download( defaultValue = "''", named = true, doc = - "the expected SHA-256 hash of the file downloaded." + "Expected SHA-256 hash of the file downloaded." + " 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" @@ -826,8 +834,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. By default the checksum (`sha256` or" - + " `integrity`) is used otherwise caching is disabled."), + + " with the same canonical id. By default caching uses the checksum" + + " (`sha256` or `integrity`)."), @Param( name = "auth", defaultValue = "{}", @@ -848,7 +856,11 @@ 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 = "{}", From 9f9da95abd77ccf6fd25cd7ca542aa41b25bb070 Mon Sep 17 00:00:00 2001 From: Jordan Mele Date: Wed, 17 Jul 2024 22:57:27 +0000 Subject: [PATCH 3/3] Match reindenting of those docs --- .../bazel/repository/starlark/StarlarkBaseExternalContext.java | 3 +-- 1 file changed, 1 insertion(+), 2 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 49bed087d7227a..6e85a9ec83f896 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 @@ -640,8 +640,7 @@ private StructImpl completeDownload(PendingDownload pendingDownload) 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. + the cache. After a successful download, the file will be added to the cache. """), @Param( name = "executable",