Конфигурация двоичного кэширования

Статья
05/29/2024

Синтаксис конфигурации

Двоичное кэширование настроено с помощью переменной VCPKG_BINARY_SOURCES среды (задано <source>;<source>;...значение ) и параметра --binarysource=<source>командной строки. Параметры вычисляются сначала из среды, а затем из командной строки. Двоичное кэширование можно полностью отключить, передав --binarysource=clear в качестве последнего параметра командной строки.

Форма	Description
`clear`	Отключите все предыдущие источники (включая значения по умолчанию)
`default[,<rw>]`	Добавляет поставщика файлов по умолчанию
`files,<absolute path>[,<rw>]`	Добавляет расположение на основе файлов
`nuget,<uri>[,<rw>]`	Добавляет источник на основе NuGet; `-Source` эквивалентен параметру Интерфейса командной строки NuGet
`nugetconfig,<path>[,<rw>]`	Добавляет источник на основе nuGet-config-file; эквивалентен `-Config` параметру интерфейса командной строки NuGet.
`nugettimeout,<seconds>`	Указывает время ожидания для сетевых операций NuGet; эквивалентен `-Timeout` параметру интерфейса командной строки NuGet.
`http,<url_template>[,<rw>[,<header>]]`	Добавляет настраиваемое расположение на основе HTTP.
`x-azblob,<baseuri>,<sas>[,<rw>]`	Экспериментальный: изменение или удаление без предупреждения Добавляет источник Хранилище BLOB-объектов Azure с помощью подписанного URL-адреса
`x-gcs,<prefix>[,<rw>]`	Экспериментальный: изменение или удаление без предупреждения Добавляет источник Google Cloud Storage (GCS).
`x-aws,<prefix>[,<rw>]`	Экспериментальный: изменение или удаление без предупреждения Добавляет источник AWS S3.
`x-aws-config,<parameter>`	Экспериментальный: изменение или удаление без предупреждения Настройте всех поставщиков AWS S3.
`x-cos,<prefix>[,<rw>]`	Экспериментальный: изменение или удаление без предупреждения Добавляет источник хранилища объектов Tencent Cloud.
`x-gha,<rw>]`	Экспериментальный: изменение или удаление без предупреждения Используйте кэш GitHub Actions в качестве источника.
`x-az-universal,<organization>,<project>,<feed>[,<rw>]`	Экспериментальный: изменение или удаление без предупреждения Используйте универсальные пакеты в Артефактах Azure в качестве источника.
`interactive`	Включает интерактивное управление учетными данными для NuGet (для отладки; требуется `--debug` в командной строке)

Необязательный <rw> параметр для определенных источников определяет, будут ли они обращаться к скачиванию двоичных файлов ()(readпо умолчанию), будут ли сборки по запросу отправляться в этот удаленный (writeили оба) (readwrite).

Поставщики

Поставщик AWS S3

Примечание.

В этом разделе рассматривается экспериментальная функция vcpkg, которая может изменяться или удаляться в любое время.

x-aws,<prefix>[,<rw>]

Добавьте источник AWS S3 с помощью интерфейса командной строки AWS. <Префикс> должен начинаться с s3:// и заканчиваться в /формате .

x-aws-config,no-sign-request

Передайте --no-sign-request интерфейс командной строки AWS.

поставщик Хранилище BLOB-объектов Azure

Примечание.

x-azblob,<baseuri>,<sas>[,<rw>]

Добавляет поставщик Хранилище BLOB-объектов Azure с помощью проверки подписанного URL-адреса. <baseuri> должен включать путь к контейнеру.

Быстрое начало

Сначала необходимо создать учетную запись служба хранилища Azure, а также контейнер. Инструкции см. в документации по служба хранилища Azure краткого запуска.

Затем необходимо создать подписанный URL-адрес (SAS), который можно сделать из учетной записи хранения в разделе "Параметры - подписанный URL-адрес>". Этот SAS потребуется:

Разрешенные службы: BLOB-объект
Допустимые типы ресурсов: Объект
Разрешенные разрешения: чтение (при использованииread) или чтение, создание (при использовании write илиreadwrite)

Конечная точка большого двоичного объекта и контейнер должны передаваться в качестве <baseuri> созданного SAS без ? префикса <sas>.

Пример:

x-azblob,https://<storagename>.blob.core.windows.net/<containername>,sv=2019-12-12&ss=b&srt=o&sp=rcx&se=2020-12-31T06:20:36Z&st=2020-12-30T22:20:36Z&spr=https&sig=abcd,readwrite

vcpkg попытается избежать выявления SAS во время обычных операций, однако:

Он будет напечатан в полном объеме, если --debug передается
Он будет передан в качестве параметра командной строки в подпроцессы, например curl.exe

Хранилище BLOB-объектов Azure включает функцию для удаления записей кэша, которые не были доступны в течение заданного количества дней, которые можно использовать для автоматического управления размером двоичного кэша. Дополнительные сведения см. в статье "Управление жизненным циклом данных" Документация Майкрософт или поиск управления жизненным циклом данных на> портале Azure для учетной записи хранения.

Поставщик облачного хранилища объектов Tencent

Примечание.

x-cos,<prefix>[,<rw>]

Добавляет источник COS. <prefix> должен начинаться с cos:// и заканчиваться /.

Поставщик файлов

files,<absolute path>[,<rw>]

Хранит сжатые zip-архивы по пути на основе двоичного идентификатора кэширования.

Поставщик облачного хранилища Google

Примечание.

x-gcs,<prefix>[,<rw>]

Добавляет поставщик облачного хранилища Google. <prefix> должен начинаться с gs:// и заканчиваться /.

Быстрое начало

Сначала необходимо создать учетную запись Google Cloud Platform, а также контейнер хранилища (краткое руководство по GCS).

В рамках этого краткого руководства вы настроили gsutil средство командной строки для проверки подлинности в Google Cloud. vcpkg будет использовать это средство командной строки, поэтому убедитесь, что он находится в пути поиска для исполняемых файлов.

Пример 1 (использование контейнера без общего префикса для объектов):

x-gcs,gs://<bucket-name>/,readwrite

Пример 2 (использование контейнера и префикса для объектов):

x-gcs,gs://<bucket-name>/my-vcpkg-cache/maybe/with/many/slashes/,readwrite
x-gcs,gs://<bucket-name>/my-vcpkg-cache/maybe/with`,commas/too!/,readwrite

Запятые (,) допустимы как часть префикса объекта в GCS. Не забудьте скрыть их в конфигурации vcpkg, как показано в предыдущем примере. У GCS нет папок (некоторые из инструментов GCS имитируют папки). Не требуется создавать или иначе управлять префиксом, используемым кэшем vcpkg.

Кэш GitHub Actions

Примечание.

x-gha[,<rw>]

Добавляет кэш GitHub Actions в качестве поставщика. Этот поставщик двоичного кэширования действителен только в контексте рабочего процесса GitHub Actions. Для этого поставщика необходимо задать как переменные среды, так ACTIONS_CACHE_URL и ACTIONS_RUNTIME_TOKEN переменные среды. Правильное задание этих переменных среды рассматривается в следующем разделе краткого руководства.

Быстрое начало

Чтобы vcpkg использовал кэш действий GitHub, он нуждается в URL-адресе кэша действий и маркере среды выполнения. Для этого оба значения должны экспортироваться в виде переменных среды на шаге рабочего процесса следующим образом:

- uses: actions/github-script@v7
  with:
    script: |
      core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
      core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');

Указание этих значений в качестве переменных среды вместо аргументов командной строки vcpkg выполняется путем проектирования, так как поставщик двоичного кэширования GitHub Actions может использоваться только из рабочего процесса GitHub Actions.

После экспорта переменных среды vcpkg можно запустить с помощью поставщика двоичного кэширования GitHub Actions следующим образом:

- name: Install dependencies via vcpkg
  run: vcpkg install zlib --binarysource="clear;x-gha,readwrite"

Универсальные пакеты в артефактах Azure

Примечание.

x-az-universal,<organization>,<project>,<feed>[,<rw>]

Добавляет универсальные пакеты в артефакты Azure в качестве поставщика.

Быстрое начало

Сначала необходимо создать веб-канал универсальных пакетов. Инструкции см. в кратком руководстве по универсальным пакетам.

Затем необходимо установить и пройти проверку подлинности в Azure CLI. Инструкции см. в руководстве по проверке подлинности в Azure CLI. vcpkg будет использовать это средство командной строки, поэтому убедитесь, что он находится в пути поиска для исполняемых файлов.

Пример:

x-az-universal,organization_url,project_name,feed_name,readwrite

project_name Укажите параметр для скачивания и публикации универсальных пакетов в веб-канале в области проекта.

x-az-universal,organization_url,,feed_name,readwrite

Оставьте параметр пустым, чтобы скачать и опубликовать универсальные project_name пакеты в веб-канале организации.

Поставщик HTTP

http,<url_template>[,<rw>[,<header>]]

Каждая двоичная операция кэширования сопоставляется с HTTP-командой:

Загружать- GET
Закачать- PUT
Проверка существования — HEAD

Шаблон URL

Шаблон использует фигурные скобки для расширения переменной. Можно использовать переменные "name", "version", "sha" и "triplet". Например:

https://cache.example.com/{name}/{version}/{sha}

Предупреждение

Это значение может отображаться в командной строке вызовов внешних процессов, которые могут повлиять на безопасность в вашей среде.

Проверка подлинности поддерживается путем указания заголовка авторизации HTTP. Например:

http,https://cache.example.com/{name}/{version}/{sha},readwrite,Authorization: Bearer BearerTokenValue

Поставщик NuGet

Добавьте сервер NuGet с параметром ИНТЕРФЕЙСА командной -Source строки NuGet:

nuget,<uri>[,<rw>]

Используйте файл конфигурации NuGet с параметром Интерфейса командной -Config строки NuGet:

nugetconfig,<path>[,<rw>]

Настройте время ожидания для источников NuGet:

nugettimeout,<seconds>

Файлы конфигурации должны определять defaultPushSource поддержку записи пакетов обратно в веб-канал.

Подтверждение компетенции

Для доступа ко многим серверам NuGet требуются дополнительные учетные данные. Самый гибкий способ предоставления учетных данных — через nugetconfig источник с пользовательским nuget.config файлом. Дополнительные сведения см. в разделе "Использование пакетов из проверенных веб-каналов".

Однако проверка подлинности на многих серверах по-прежнему возможна с помощью встроенных поставщиков учетных данных NuGet или настройки по умолчанию nuget.configсреды. Конфигурация по умолчанию может быть расширена с помощью вызовов клиентов nuget, таких как:

nuget sources add -Name MyRemote -Source https://... -Username $user -Password $pass

а затем передается в vcpkg через nuget,MyRemote,readwrite. Путь к точной копии NuGet, используемой vcpkg, можно получить, выполнив команду vcpkg fetch nuget, которая будет сообщать примерно следующее:

$ vcpkg fetch nuget
/vcpkg/downloads/tools/nuget-5.5.1-linux/nuget.exe

Пользователям, отличным от Windows, потребуется вызвать это через mono.mono /path/to/nuget.exe sources add ...

`metadata.repository`

Поставщики nuget источников nugetconfig учитывают определенные переменные среды при создании пакетов nuget. Поле metadata.repository всех пакетов будет создано следующим образом:

    <repository type="git" url="${VCPKG_NUGET_REPOSITORY}"/>

    <repository type="git"
                url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git"
                branch="${GITHUB_REF}"
                commit="${GITHUB_SHA}"/>

Если соответствующие переменные среды определены и не пусты. Это специально используется для связывания пакетов в пакетах GitHub с проектом сборки и не предназначено для связывания с исходными источниками пакетов.

Кэш NuGet

Кэш NuGet по умолчанию не используется. Чтобы использовать его для каждого источника на основе nuget, задайте для переменнойVCPKG_USE_NUGET_CACHE среды значение true (без учета регистра) или 1.

Примеры поставщика

Если ваша система CI не указана в списке, вы можете отправить PR-запрос, чтобы добавить его!

Пакеты GitHub

Чтобы использовать vcpkg с пакетами GitHub, рекомендуется использовать поставщик NuGet.

Примечание.

2020-09-21: размещенные агенты GitHub поставляются со старой предварительно установленной копией vcpkg на пути, который не поддерживает последнее двоичное кэширование. Это означает, что прямые вызовы к bootstrap-vcpkg префиксу пути или vcpkg без нее могут вызывать непреднамеренное экземпляр vcpkg. Если вы хотите использовать собственную копию vcpkg, выполните следующие два шага, чтобы избежать проблем, если вы хотите использовать собственную копию vcpkg:

Выполните эквивалент rm -rf "$VCPKG_INSTALLATION_ROOT" использования shell: 'bash'.
Всегда вызывайте vcpkg и bootstrap-vcpkg с префиксом пути, например ./vcpkg, vcpkg/vcpkg, .\bootstrap-vcpkg.batи т. д.

# actions.yaml
#
# In this example, vcpkg has been added as a submodule (`git submodule add https://github.com/Microsoft/vcpkg`).
env:
  VCPKG_BINARY_SOURCES: 'clear;nuget,GitHub,readwrite'

matrix:
  os: ['windows-2019', 'ubuntu-20.04']
  include:
    - os: 'windows-2019'
      triplet: 'x86-windows'
      mono: ''
    - os: 'ubuntu-20.04'
      triplet: 'x64-linux'
      # To run `nuget.exe` on non-Windows platforms, `mono` must be used.
      mono: 'mono'

steps:
  # This step assumes `vcpkg` has been bootstrapped (run `./vcpkg/bootstrap-vcpkg`)
  - name: 'Setup NuGet Credentials'
    shell: 'bash'
    # Replace <OWNER> with your organization name
    run: |
      ${{ matrix.mono }} `./vcpkg/vcpkg fetch nuget | tail -n 1` \
        sources add \
        -source "https://nuget.pkg.github.com/<OWNER>/index.json" \
        -storepasswordincleartext \
        -name "GitHub" \
        -username "<OWNER>" \
        -password "${{ secrets.GITHUB_TOKEN }}"
      ${{ matrix.mono }} `./vcpkg/vcpkg fetch nuget | tail -n 1` \
        setapikey "${{ secrets.GITHUB_TOKEN }}" \
        -source "https://nuget.pkg.github.com/<OWNER>/index.json"

  # Omit this step if you're using manifests
  - name: 'vcpkg package restore'
    shell: 'bash'
    run: >
      ./vcpkg/vcpkg install sqlite3 cpprestsdk --triplet ${{ matrix.triplet }}

Если вы используете манифесты, вы можете опустить vcpkg package restore этот шаг: он будет выполняться автоматически в рамках сборки.

Дополнительные сведения см. в документации по NuGet пакетов GitHub.

Артефакты Azure DevOps

Чтобы использовать vcpkg с Azure DevOps Artifacts, рекомендуется использовать поставщик NuGet.

Сначала убедитесь, что артефакты включены в учетной записи DevOps. Администратор может включить это с помощью параметров проекта ->Общие сведения ->Обзор ->Артефакты Azure DevOps Services.>

Затем создайте веб-канал для проекта. URL-адрес веб-канала будет ссылкой https:// , заканчивающейся /nuget/v3/index.json. Дополнительные сведения см. в документации по артефактам Azure DevOps.

Использование веб-канала из конвейера

# azure-pipelines.yaml
variables:
- name: VCPKG_BINARY_SOURCES
  value: 'clear;nuget,<FEED_URL>,readwrite'

steps:
# Remember to add this task to allow vcpkg to upload archives via NuGet
- task: NuGetAuthenticate@0

Если вы используете пользовательские агенты с операционной системой, отличной от Windows, необходимо установить Mono для запуска nuget.exe (apt install mono-completeи brew install monoт. д.).

Использование веб-канала локально

# On Windows Powershell
PS> & $(vcpkg fetch nuget | select -last 1) sources add `
  -name ADO `
  -Source https://pkgs.dev.azure.com/$ORG/_packaging/$FEEDNAME/nuget/v3/index.json `
  -Username $USERNAME `
  -Password $PAT
PS> $env:VCPKG_BINARY_SOURCES="nuget,ADO,readwrite"

# On Linux or OSX
$ mono `vcpkg fetch nuget | tail -n1` sources add \
  -name ADO \
  -Source https://pkgs.dev.azure.com/$ORG/_packaging/$FEEDNAME/nuget/v3/index.json \
  -Username $USERNAME \
  -Password $PAT
$ export VCPKG_BINARY_SOURCES="nuget,ADO,readwrite"

Используйте личный маркер доступа (PAT) в качестве пароля для максимальной безопасности. Вы можете создать PAT в параметрах пользователя —>личные маркеры доступа или https://dev.azure.com/<ORG>/_usersSettings/tokens.

Хэш ABI

Примечание.

Сведения о хэше ABI предоставляются в виде заметки о реализации и будут изменяться без уведомления.

Для каждой сборки vcpkg вычисляет хэш ABI, чтобы определить эквивалентность. Если две сборки имеют одинаковый хэш ABI, vcpkg будет рассматривать их как идентичные, так и повторно использовать двоичные файлы в проектах и компьютерах.

Хэш ABI считает:

Каждый файл в каталоге портов
Содержимое и имя тройного файла
Исполняемый файл компилятора C++
Исполняемый файл компилятора C
Выбранный набор компонентов
Хэш ABI каждой зависимости
Все вспомогательные функции, portfile.cmake на которые ссылается (эвристика)
Используемая версия CMake
Содержимое всех переменных среды, перечисленных в VCPKG_ENV_PASSTHROUGH
Текстовое содержимое файла цепочки инструментов (VCPKG_CHAINLOAD_TOOLCHAIN_FILE)
Набор средств GRDK (только при выборе платформы Xbox)

Несмотря на этот обширный список, можно победить кэш и ввести недетерминированность. Если у вас есть дополнительные сведения, необходимые для отслеживания среды, можно создать тройной файл с дополнительными сведениями в комментарии. Эта дополнительная информация будет включена в хэш ABI и обеспечит уникальную вселенную двоичных файлов.

Именованные .DS_Store файлы не учитываются для хэша ABI.

Вычисляемые хэши ABI хранятся в каждом пакете и в текущем установленном каталоге /share/<port>/vcpkg_abi_info.txt для проверки.

Пример хэша ABI zlib

Включите выходные данные отладки для печати полного хэша двоичного интерфейса приложения (ABI) pacakge. Для zlib:

[DEBUG] Trying to hash <path>\buildtrees\zlib\x86-windows.vcpkg_abi_info.txt
[DEBUG] <path>\buildtrees\zlib\x86-windows.vcpkg_abi_info.txt has hash bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87

Хэш bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87 ABI для пакета zlib создается путем хэширования всех возможных соответствующих сведений для различания двоичных пакетов.

Версия компилятора является частью хэша ABI и вычисляется ниже:

[DEBUG] -- The C compiler identification is MSVC 19.36.32538.0
[DEBUG] -- The CXX compiler identification is MSVC 19.36.32538.0
[DEBUG] #COMPILER_HASH#f5d02a6542664cfbd4a38db478133cbb1a18f315

Соответствующие файлы, сведения о версии компилятора и средства хэшируются для вычисления окончательного хэша ABI:

[DEBUG] <abientries for zlib:x86-windows>
[DEBUG]   0001-Prevent-invalid-inclusions-when-HAVE_-is-set-to-0.patch|750b9542cb55e6328cca01d3ca997f1373b9530afa95e04213168676936e7bfa
[DEBUG]   0002-skip-building-examples.patch|835ddecfed752e0f49be9b0f8ff7ba76541cb0a150044327316e22ca84f8d0c2
[DEBUG]   0003-build-static-or-shared-not-both.patch|d6026271dcb3d8fc74b41e235620ae31576a798e77aa411c3af8cd9e948c02b1
[DEBUG]   0004-android-and-mingw-fixes.patch|37a43eddbcb1b7dde49e7659ae895dfd0ff1df66666c1371ba7d5bfc49d8b438
[DEBUG]   cmake|3.26.2
[DEBUG]   features|core
[DEBUG]   portfile.cmake|ac63047b644fa758860dd7ba48ff9a13b058c6f240b8e8d675b8fbba035976be
[DEBUG]   ports.cmake|5a8e00cedff0c898b1f90f7d129329d0288801bc9056562b039698caf31ff3f3
[DEBUG]   post_build_checks|2
[DEBUG]   powershell|7.3.6
[DEBUG]   triplet|x86-windows
[DEBUG]   triplet_abi|3e71dd1d4afa622894ae367adbbb1ecbd42c57c51428a86b675fa1c8cad3a581-36b818778ba6f2c16962495caedb9a7b221d5be4c60de1cd3060f549319a9931-f5d02a6542664cfbd4a38db478133cbb1a18f315
[DEBUG]   usage|be22662327df993eebc437495add75acb365ab18d37c7e5de735d4ea4f5d3083
[DEBUG]   vcpkg-cmake|1b3dac4b9b0bcbef227c954b495174863feebe3900b2a6bdef0cd1cf04ca1213
[DEBUG]   vcpkg-cmake-wrapper.cmake|5d49ef2ee6448479c2aad0e5f732e2676eaba0411860f9bebabe6002d66f57d1
[DEBUG]   vcpkg.json|bc94e2540efabe36130a806381a001c57194e7de67454ab7ff1e30aa15e6ce23
[DEBUG]   vcpkg_copy_pdbs|d57e4f196c82dc562a9968c6155073094513c31e2de475694143d3aa47954b1c
[DEBUG]   vcpkg_fixup_pkgconfig|588d833ff057d3ca99c14616c7ecfb5948b5e2a9e4fc02517dceb8b803473457
[DEBUG]   vcpkg_from_git|8f27bff0d01c6d15a3e691758df52bfbb0b1b929da45c4ebba02ef76b54b1881
[DEBUG]   vcpkg_from_github|b743742296a114ea1b18ae99672e02f142c4eb2bef7f57d36c038bedbfb0502f
[DEBUG]   vcpkg_replace_string|d43c8699ce27e25d47367c970d1c546f6bc36b6df8fb0be0c3986eb5830bd4f1
[DEBUG] </abientries>

Примечание.

Запись triplet_abi содержит три хэша: хэш содержимого x86-windows файла триплета, windows.cmake цепочку инструментов и хэш компилятора. Эти хэши изменятся, если вы решили нацелиться на другую платформу.

Поделиться через

Конфигурация двоичного кэширования

Синтаксис конфигурации

Поставщики

Поставщик AWS S3

поставщик Хранилище BLOB-объектов Azure

Быстрое начало

Поставщик облачного хранилища объектов Tencent

Поставщик файлов

Поставщик облачного хранилища Google

Быстрое начало

Кэш GitHub Actions

Быстрое начало

Универсальные пакеты в артефактах Azure

Быстрое начало

Поставщик HTTP

Шаблон URL

Верхний колонтитул

Поставщик NuGet

Подтверждение компетенции

`metadata.repository`

Кэш NuGet

Примеры поставщика

Пакеты GitHub

Артефакты Azure DevOps

Использование веб-канала из конвейера

Использование веб-канала локально

Хэш ABI

Пример хэша ABI zlib

Дополнительные ресурсы