Skip to content

Commit

Permalink
Document source of truth for rctx.download* cache key
Browse files Browse the repository at this point in the history
Documenting the default caching behaviour for `rctx.download` and `rctx.download_and_extract`.
 
Related to bazelbuild#22652

Closes bazelbuild#22716.

PiperOrigin-RevId: 653878029
Change-Id: I129f9eede2b841483a98d5335651c1d1198aaf76
  • Loading branch information
Silic0nS0ldier authored and fmeum committed Aug 22, 2024
1 parent 772ba98 commit 5833641
Showing 1 changed file with 16 additions and 5 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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 \
(<code>sha256</code> or <code>integrity</code>).
"""),
@Param(
name = "auth",
Expand All @@ -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",
Expand Down Expand Up @@ -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"
(<code>sha256</code> or <code>integrity</code>).
"""),
@Param(
name = "auth",
Expand All @@ -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",
Expand Down

0 comments on commit 5833641

Please sign in to comment.