Asset caching

Note

This section covers an experimental feature of vcpkg which 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>. As an example, if you set X_VCPKG_ASSET_SOURCES to x-azurl,https://mydomain.com/vcpkg/,token=abc123,readwrite your server should respond to GET and PUT requests of the form https://mydomain.com/vcpkg/<sha512>?token=abc123.

You can also use the filesystem (e.g. a network drive) via file:// as asset cache. For example you then set X_VCPKG_ASSET_SOURCES to x-azurl,file:///Z:/vcpkg/assetcache/,,readwrite when you have a network folder mounted at Z:/.

The workflow of this asset source is:

  1. Attempt to read from the mirror
  2. (If step 1 failed) Read from the original url
  3. (If step 2 succeeded) Write back to the mirror

You can enable/disable steps 1 and 3 via the <rw> specifier and you can disable step 2 via x-block-origin below.

See also the binary caching documentation for Azure Blob Storage 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.

x-script

Syntax: x-script,<template>

Dispatches to an external tool to fetch the asset. Within the template, {url} will be replaced by the original url, {sha512} will be replaced by the SHA512 value, and {dst} will be replaced by the output path to save to. These substitutions will all be properly shell escaped, so an example template would be: curl -L {url} --output {dst}. {{ will be replaced by } and }} will be replaced by } to avoid expansion. Note that this will be executed inside the build environment, so the PATH and other environment variables will be modified by the triplet.

See How to create an x-script Asset Caching source for NuGet for a walkthrough using x-script.