[vcpkg] Add experimental $X_VCPKG_ASSET_SOURCES for source caching (#13639)

* [vcpkg] Add experimental $VCPKG_X_READWRITE_MIRROR_URL_TEMPLATE for source caching

* [vcpkg] Use prerelease version for testing

* [docs] Add assetcaching.md

* Revert bootstrap changes

* [vcpkg_download_distfile] Deprecate SILENT_EXIT

* cmake_parse_arguments() always defines option arguments

* Adjust CI baseline

* [vcpkg_download_distfile] Address CR comments, restore ARIA2

* [CI] Add source caching to Linux and OSX CI passes

* [ci.baseline.txt] Skip chartdir on more platforms

2 files changed, 49 insertions, 0 deletions

diff --git a/docs/users/assetcaching.md b/docs/users/assetcaching.md
new file mode 100644
index 000000000..425e1158f
--- /dev/null
+++ b/docs/users/assetcaching.md
@@ -0,0 +1,43 @@
+# Asset Caching
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/assetcaching.md).**
+
+**Experimental feature: this may change or be removed at any time**
+
+Vcpkg can utilize mirrors to cache downloaded assets, ensuring continued operation even if the original source changes
+or disappears.
+
+In-tool help is available via `vcpkg help assetcaching`.
+
+## Configuration
+
+Asset caching can be configured by setting the environment variable `X_VCPKG_ASSET_SOURCES` to a semicolon-delimited
+list of source strings. Characters can be escaped using backtick (\`).
+
+### Valid source strings
+
+The `<rw>` optional parameter for certain strings controls how they will be accessed. It can be specified as `read`,
+`write`, or `readwrite` and defaults to `read`.
+
+#### `clear`
+
+Syntax: `clear`
+
+Removes all previous sources
+
+#### `x-azurl`
+
+Syntax: `x-azurl,<url>[,<sas>[,<rw>]]`
+
+Adds an Azure Blob Storage source, optionally using Shared Access Signature validation. URL should include the container
+path and be terminated with a trailing `/`. SAS, if defined, should be prefixed with a `?`. Non-Azure servers will also
+work if they respond to GET and PUT requests of the form: `<url><sha512><sas>`.
+
+See also the [binary caching documentation for Azure Blob Storage](binarycaching.md#azure-blob-storage-experimental) for
+more information on how to set up an `x-azurl` source.
+
+#### `x-block-origin`
+
+Syntax: `x-block-origin`
+
+Disables use of the original URLs in case the mirror does not have the file available.
diff --git a/docs/users/config-environment.md b/docs/users/config-environment.md
index 132f84fb6..73dd64a21 100644
--- a/docs/users/config-environment.md
+++ b/docs/users/config-environment.md
@@ -87,3 +87,9 @@ This environment variable changes the metadata of produced NuGet packages. See [
 #### VCPKG_USE_NUGET_CACHE

 

 This environment variable allows using NuGet's cache for every nuget-based binary source. See [Binary Caching](binarycaching.md#NuGets-cache) for more details.

+

+#### X_VCPKG_ASSET_SOURCES

+

+> Note: This is an experimental feature and may change or be removed at any time

+

+This environment variable allows using a private mirror for all SHA512-tagged assets. See [Asset Caching](assetcaching.md) for more details.