Partager via

Configuration de la mise en cache binaire

  • Article

Syntaxe de configuration

La mise en cache binaire est configurée avec la variable VCPKG_BINARY_SOURCES d’environnement (définie sur <source>;<source>;...) et l’option --binarysource=<source>de ligne de commande . Les options sont évaluées en premier à partir de l’environnement, puis à partir de la ligne de commande. La mise en cache binaire peut être complètement désactivée en passant --binarysource=clear comme dernière option de ligne de commande.

Formulaire Description
clear Désactiver toutes les sources précédentes (y compris la valeur par défaut)
default[,<rw>] Ajoute le fournisseur de fichiers par défaut
files,<absolute path>[,<rw>] Ajoute un emplacement basé sur un fichier
nuget,<uri>[,<rw>] Ajoute une source nuGet ; équivalent au -Source paramètre de l’interface CLI NuGet
nugetconfig,<path>[,<rw>] Ajoute une source basée sur NuGet-config-file ; équivalent au -Config paramètre de l’interface CLI NuGet.
nugettimeout,<seconds> Spécifie un délai d’expiration pour les opérations réseau NuGet ; équivalent au -Timeout paramètre de l’interface CLI NuGet.
http,<url_template>[,<rw>[,<header>]] Ajoute un emplacement http personnalisé.
x-azblob,<baseuri>,<sas>[,<rw>] Expérimental : change ou sera supprimé sans avertissement
Ajoute une source Stockage Blob Azure à l’aide d’une signature d’accès partagé
x-gcs,<prefix>[,<rw>] Expérimental : change ou sera supprimé sans avertissement
Ajoute une source Google Cloud Storage (GCS).
x-aws,<prefix>[,<rw>] Expérimental : change ou sera supprimé sans avertissement
Ajoute une source AWS S3.
x-aws-config,<parameter> Expérimental : change ou sera supprimé sans avertissement
Configurez tous les fournisseurs AWS S3.
x-cos,<prefix>[,<rw>] Expérimental : change ou sera supprimé sans avertissement
Ajoute une source de stockage d’objets cloud Tencent.
x-gha,<rw>] Expérimental : change ou sera supprimé sans avertissement
Utilisez le cache GitHub Actions comme source.
x-az-universal,<organization>,<project>,<feed>[,<rw>] Expérimental : change ou sera supprimé sans avertissement
Utilisez des packages universels dans Azure Artifacts comme source.
interactive Active la gestion interactive des informations d’identification pour NuGet (pour le débogage ; nécessite --debug sur la ligne de commande)

Le <rw> paramètre facultatif pour certaines sources contrôle s’ils seront consultés pour télécharger des fichiers binaires (readpar défaut), si les builds à la demande seront chargées vers cette version distante (write) ou les deux (readwrite).

Fournisseurs

Fournisseur AWS S3

Remarque

Cette section décrit une fonctionnalité expérimentale de vcpkg qui peut changer ou être supprimée à tout moment.

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

Ajoutez une source AWS S3 à l’aide de l’interface DE ligne de commande AWS. <le préfixe> doit commencer par s3:// et se terminer dans un /.

x-aws-config,no-sign-request

--no-sign-request Passez à l’interface DE ligne de commande AWS.

fournisseur Stockage Blob Azure

Remarque

Cette section décrit une fonctionnalité expérimentale de vcpkg qui peut changer ou être supprimée à tout moment.

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

Ajoute un fournisseur Stockage Blob Azure à l’aide de la validation de signature d’accès partagé. <baseuri> doit inclure le chemin d’accès du conteneur.

Démarrage rapide

Tout d’abord, vous devez créer un compte Stockage Azure ainsi qu’un conteneur. Pour obtenir des instructions, consultez la documentation de démarrage rapide Stockage Azure.

Ensuite, vous devez créer une signature d’accès partagé (SAP), qui peut être effectuée à partir du compte de stockage sous Paramètres ->Signature d’accès partagé. Cette SAP a besoin des éléments suivants :

  • Services autorisés : Blob
  • Types de ressources autorisés : Objet
  • Autorisations autorisées : Lecture (en cas d’utilisation read) ou Lecture, Créer (si vous utilisez write ou readwrite)

Le point de terminaison d’objet blob plus le conteneur doit être transmis en tant que <baseuri> SAP généré sans le ? préfixe doit être transmis en tant que <sas>.

Exemple :

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 tentera d’éviter de révéler la signature d’accès partagé pendant les opérations normales, toutefois :

  1. Il sera imprimé en intégralité s’il --debug est passé
  2. Il sera passé en tant que paramètre de ligne de commande aux sous-processus, tels que curl.exe

Stockage Blob Azure inclut une fonctionnalité permettant de supprimer les entrées de cache qui n’ont pas été consultées dans un nombre donné de jours, qui peuvent être utilisées pour gérer automatiquement la taille de votre cache binaire. Pour plus d’informations, consultez Gestion du cycle de vie des données sur Microsoft Docs, ou recherchez la gestion> du cycle de vie des données dans le portail Azure pour votre compte de stockage.

Fournisseur de stockage d’objets cloud Tencent

Remarque

Cette section décrit une fonctionnalité expérimentale de vcpkg qui peut changer ou être supprimée à tout moment.

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

Ajoute une source COS. <prefix> doit commencer par cos:// et se terminer par /.

Fournisseur de fichiers

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

Stocke les archives compressées zip au niveau du chemin d’accès en fonction de l’ID de mise en cache binaire.

Fournisseur Google Cloud Storage

Remarque

Cette section décrit une fonctionnalité expérimentale de vcpkg qui peut changer ou être supprimée à tout moment.

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

Ajoute un fournisseur Google Cloud Storage. <prefix> doit commencer par gs:// et se terminer par /.

Démarrage rapide

Tout d’abord, vous devez créer un compte Google Cloud Platform ainsi qu’un compartiment de stockage (démarrage rapide GCS).

Dans le cadre de ce guide de démarrage rapide, vous avez configuré l’outil gsutil en ligne de commande pour vous authentifier auprès de Google Cloud. vcpkg utilise cet outil en ligne de commande. Vérifiez donc qu’il se trouve dans votre chemin de recherche pour les exécutables.

Exemple 1 (utilisation d’un compartiment sans préfixe commun pour les objets) :

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

Exemple 2 (utilisation d’un compartiment et d’un préfixe pour les objets) :

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

Les virgules (,) sont valides dans le cadre d’un préfixe d’objet dans GCS. N’oubliez pas de les échapper dans la configuration vcpkg, comme illustré dans l’exemple précédent. GCS n’a pas de dossiers (certains des outils GCS simulent des dossiers). Il n’est pas nécessaire de créer ou de manipuler le préfixe utilisé par votre cache vcpkg.

Cache GitHub Actions

Remarque

Cette section décrit une fonctionnalité expérimentale de vcpkg qui peut changer ou être supprimée à tout moment.

x-gha[,<rw>]

Ajoute le cache GitHub Actions en tant que fournisseur. Ce fournisseur de mise en cache binaire n’est valide que dans le contexte d’un flux de travail GitHub Actions. Ce fournisseur nécessite la définition des variables d’environnement et ACTIONS_RUNTIME_TOKEN des ACTIONS_CACHE_URL variables d’environnement. La définition correcte de ces variables d’environnement est décrite dans la section de démarrage rapide suivante.

Démarrage rapide

Pour que vcpkg utilise le cache GitHub Actions, il a besoin de l’URL du cache d’actions et du jeton d’exécution. Pour ce faire, les deux valeurs doivent être exportées en tant que variables d’environnement dans une étape de flux de travail similaire à ce qui suit :

- 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 || '');

La spécification de ces valeurs en tant que variables d’environnement au lieu des arguments de ligne de commande vcpkg est par conception, car le fournisseur de mise en cache binaire cache GitHub Actions ne peut être utilisé qu’à partir d’un flux de travail GitHub Actions.

Une fois les variables d’environnement exportées, vcpkg peut être exécuté avec le fournisseur de mise en cache binaire GitHub Actions comme suit :

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

Packages universels dans Azure Artifacts

Remarque

Cette section décrit une fonctionnalité expérimentale de vcpkg qui peut changer ou être supprimée à tout moment.

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

Ajoute des packages universels dans Azure Artifacts en tant que fournisseur.

Démarrage rapide

Tout d’abord, vous devez créer un flux packages universels. Consultez le guide de démarrage rapide des packages universels pour obtenir des instructions.

Ensuite, vous devez installer et s’authentifier auprès d’Azure CLI. Consultez le guide de l’authentification auprès d’Azure CLI pour obtenir des instructions. vcpkg utilise cet outil en ligne de commande. Vérifiez donc qu’il se trouve dans votre chemin de recherche pour les exécutables.

Exemple :

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

Fournissez le project_name paramètre pour télécharger et publier des packages universels dans votre flux dans une étendue de projet.

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

Laissez le project_name paramètre vide pour télécharger et publier des packages universels dans votre flux dans une étendue d’organisation.

Fournisseur HTTP

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

Chaque opération de mise en cache binaire est mappée à un verbe HTTP :

  • Télécharger- GET
  • Télécharger- PUT
  • Vérifier l’existence - HEAD

Modèle URL

Le modèle utilise des crochets curly pour l’expansion des variables. Vous pouvez utiliser les variables « name », « version », « sha » et « triplet ». Par exemple :

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

Avertissement

Cette valeur peut apparaître sur la ligne de commande des appels de processus externes, ce qui peut avoir des implications en matière de sécurité dans votre environnement.

L’authentification est prise en charge en spécifiant un en-tête d’autorisation HTTP. Par exemple :

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

Fournisseur NuGet

Ajoutez un serveur NuGet avec le -Source paramètre CLI NuGet :

nuget,<uri>[,<rw>]

Utilisez un fichier de configuration NuGet avec le -Config paramètre CLI NuGet :

nugetconfig,<path>[,<rw>]

Configurez le délai d’expiration pour les sources NuGet :

nugettimeout,<seconds>

Les fichiers de configuration doivent définir un defaultPushSource pour prendre en charge l’écriture de packages dans le flux.

Informations d'identification

De nombreux serveurs NuGet nécessitent des informations d’identification supplémentaires pour accéder. La méthode la plus flexible pour fournir des informations d’identification est via la nugetconfig source avec un fichier personnalisé nuget.config . Pour plus d’informations, consultez Consommation de packages à partir de flux authentifiés .

Toutefois, il est toujours possible de s’authentifier auprès de nombreux serveurs à l’aide des fournisseurs d’informations d’identification intégrés de NuGet ou via la personnalisation de la valeur par défaut nuget.configde votre environnement. La configuration par défaut peut être étendue par le biais d’appels clients nuget, tels que :

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

puis passé à vcpkg via nuget,MyRemote,readwrite. Vous pouvez obtenir un chemin d’accès à la copie précise de NuGet utilisée par vcpkg en exécutant vcpkg fetch nuget, ce qui signale quelque chose comme :

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

Les utilisateurs non-Windows devront l’appeler via mono via mono /path/to/nuget.exe sources add ....

metadata.repository

Les nuget fournisseurs sources respectent nugetconfig certaines variables d’environnement lors de la génération de packages nuget. Le metadata.repository champ de tous les packages sera généré comme suit :

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

or

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

si les variables d’environnement appropriées sont définies et non vides. Cela est spécifiquement utilisé pour associer des packages dans GitHub Packages au projet de génération et non destiné à l’associer aux sources de package d’origine.

NuGet Cache

Le cache à l’échelle de l’utilisateur de NuGet n’est pas utilisé par défaut. Pour l’utiliser pour chaque source nuget, définissez la variable trueVCPKG_USE_NUGET_CACHE d’environnement sur (sans respect de la casse) ou .1

Exemples de fournisseurs

Si votre système d’intégration continue n’est pas répertorié, vous êtes invité à soumettre une demande de tirage pour l’ajouter !

GitHub Packages

Pour utiliser vcpkg avec GitHub Packages, il est recommandé d’utiliser le fournisseur NuGet.

Remarque

2020-09-21 : les agents hébergés de GitHub sont fournis avec une copie antérieure et préinstallée de vcpkg sur le chemin qui ne prend pas en charge la dernière mise en cache binaire. Cela signifie que les appels directs vers bootstrap-vcpkg ou vcpkg sans préfixe de chemin d’accès peuvent appeler une instance vcpkg inattendue. Si vous souhaitez utiliser votre propre copie de vcpkg, les deux étapes suivantes pour éviter les problèmes si vous souhaitez utiliser votre propre copie de vcpkg :

  1. Exécutez l’équivalent de l’utilisation rm -rf "$VCPKG_INSTALLATION_ROOT" shell: 'bash'.
  2. Appelez vcpkg toujours et bootstrap-vcpkg avec un préfixe de chemin d’accès, tel que ./vcpkg, vcpkg/vcpkg, .\bootstrap-vcpkg.bat, etc.
# 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 }}

Si vous utilisez des manifestes, vous pouvez omettre l’étape vcpkg package restore : elle sera exécutée automatiquement dans le cadre de votre build.

Pour plus d’informations, consultez la documentation NuGet des packages GitHub.

Artefacts Azure DevOps

Pour utiliser vcpkg avec Azure DevOps Artifacts, il est recommandé d’utiliser le fournisseur NuGet.

Tout d’abord, vérifiez que les artefacts ont été activés sur votre compte DevOps. Un administrateur peut l’activer via les paramètres du projet ->General ->Overview ->Azure DevOps Services>Artifacts.

Ensuite, créez un flux pour votre projet. Votre URL de flux sera un https:// lien se terminant par /nuget/v3/index.json. Pour plus d’informations, consultez la documentation Azure DevOps Artifacts.

Utilisation du flux à partir d’un pipeline

# 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

Si vous utilisez des agents personnalisés avec un système d’exploitation non Windows, vous devez installer Mono pour exécuter nuget.exe (apt install mono-complete, brew install monoetc.).

Utilisation du flux localement

# 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"

Utilisez un jeton d’accès personnel (PAT) comme mot de passe pour une sécurité maximale. Vous pouvez générer un PAT dans les paramètres utilisateur ->Jetons d’accès personnels ou https://dev.azure.com/<ORG>/_usersSettings/tokens.

Hachage ABI

Remarque

Les informations sur le hachage ABI sont fournies sous la forme d’une note d’implémentation et changeront sans préavis.

Pour chaque build, vcpkg calcule un hachage ABI pour déterminer l’équivalence. Si deux builds ont le même hachage ABI, vcpkg les considère comme identiques et réutilise les fichiers binaires entre les projets et les machines.

Le hachage ABI prend en compte les éléments suivants :

  • Chaque fichier dans le répertoire de port
  • Contenu et nom du fichier triplet
  • Fichier exécutable du compilateur C++
  • Fichier exécutable du compilateur C
  • Ensemble de fonctionnalités sélectionnées
  • Hachage ABI de chaque dépendance
  • Toutes les fonctions d’assistance référencées par portfile.cmake (heuristique)
  • Version de CMake utilisée
  • Contenu de toutes les variables d’environnement répertoriées dans VCPKG_ENV_PASSTHROUGH
  • Contenu textuel du fichier de chaîne d’outils (VCPKG_CHAINLOAD_TOOLCHAIN_FILE)
  • Kit de ressources GRDK (uniquement lors du ciblage de la plateforme Xbox)

Malgré cette liste étendue, il est possible de vaincre le cache et d’introduire un non déterminisme. Si vous avez des détails supplémentaires à suivre pour votre environnement, vous pouvez générer un fichier triplet avec vos informations supplémentaires dans un commentaire. Ces informations supplémentaires seront incluses dans le hachage ABI et garantiront un univers unique de binaires.

Les fichiers nommés .DS_Store ne sont pas pris en compte pour le hachage ABI.

Les hachages ABI calculés sont stockés dans chaque package et dans le répertoire installé actuel à des fins /share/<port>/vcpkg_abi_info.txt d’inspection.

Exemple de hachage ABI de zlib

Activez la sortie de débogage pour imprimer le hachage ABI (Application Binary Interface) complet d’un pacakge. Pour 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

Le hachage bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87 ABI pour le package zlib est construit en hachage de toutes les informations pertinentes possibles pour distinguer les packages binaires.

La version de votre compilateur fait partie du hachage ABI et est calculée ci-dessous :

[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

Les fichiers pertinents, les informations de version du compilateur et de l’outil sont hachées pour calculer le hachage ABI final :

[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>

Remarque

L’entrée triplet_abi contient trois hachages : le hachage du contenu du fichier du x86-windows triplet, de la windows.cmake chaîne d’outils et du hachage du compilateur. Ces hachages changent si vous avez décidé de cibler une autre plateforme.