Ceci est une ancienne révision du document !
Table des matières
Utilisation
Standalone
C'est un installateur de dépendances en compilant depuis les sources.
Il suffit d'ajouter en tant que submodule le projet et de suivre les indications :
- Télécharger le dépôt
git clone https://github.com/microsoft/vcpkg
- Générer le bootstrap
Sous Windows :
.\vcpkg\bootstrap-vcpkg.bat
Sous Linux :
.\vcpkg\bootstrap-vcpkg.sh
- Installer les librairies
vcpkg\vcpkg install --triplet x64-windows --host-triplet x64-windows gtest
Si l'architecture de destination n'est pas compatible avec l'architecture de compilation, enlever --triplet-host
.
Par exemple:
Succès: ./vcpkg install --triplet=x64-linux --host-triplet=x64-linux qt --dry-run
Succès: ./vcpkg install --triplet=x64-linux-dynamic --host-triplet=x64-linux-dynamic qt --dry-run
Succès: ./vcpkg install --triplet=x64-linux qt --dry-run
Échec: ./vcpkg install --triplet=x64-linux-dynamic qt --dry-run
: qtwebengine is only supported on '!static & !((x86 | arm) & windows)', which does not match x64-linux.
- Spécificité à Windows
Si un paquet échoue car la longueur du chemin Windows est trop long avec plus de 255 caractères (par exemple qtwebengine), plutôt que tout effacer et de tout recommencer avec le chemin c:\v
, utiliser :
subst j: C:\Users\longlonglongpath\vcpkg
et travailler directement avec le lecteur J
.
La liste complète des triplets peut se consulter dans le dossier vcpkg/triplets
. Le sous dossier community
indique une disponibilité mais pas une obligation de support officiel.
Configuration globale
Spécifier l'emplacement du dossier de cache : variable VCPKG_DEFAULT_BINARY_CACHE
. Ce dossier ne stocke que les fichiers compilés. Le téléchargement se fait en local dans vcpkg/download
et la compilation dans vcpkg/buildtrees
.
Intégration dans une CI
Ne pas lancer le script bootstrap pour éviter de télécharger vcpkg.exe
à chaque fois. Utiliser les scripts ci-dessous qui va mettre en cache vcpkg.exe
.
Sous Linux :
vcpkg_tag=$(sed -n 's/^VCPKG_TOOL_RELEASE_TAG=\(.*\)/\1/p' < vcpkg/scripts/vcpkg-tool-metadata.txt) if [ ! -f "$VCPKG_CACHE_PATH/vcpkg-$vcpkg_tag" ]; then wget -O "$VCPKG_CACHE_PATH/vcpkg-$vcpkg_tag" "https://github.com/microsoft/vcpkg-tool/releases/download/$vcpkg_tag/vcpkg-glibc" || exit 1; chmod +x "$VCPKG_CACHE_PATH/vcpkg-$vcpkg_tag"; fi cp "$VCPKG_CACHE_PATH/vcpkg-$vcpkg_tag" vcpkg/vcpkg || exit 1
Sous Windows :
$vcpkg_tag = (Get-Content vcpkg\scripts\vcpkg-tool-metadata.txt) | Select-String -Pattern '^VCPKG_TOOL_RELEASE_TAG=(.*)' | %{$_.Matches.Groups[1].value} $url="https://github.com/microsoft/vcpkg-tool/releases/download/$vcpkg_tag/vcpkg.exe" $destination="$Env:VCPKG_CACHE_PATH/vcpkg-$vcpkg_tag.exe" if(-not(Test-Path $destination)){Invoke-WebRequest -Uri $url -OutFile $destination} Copy-Item $destination vcpkg/vcpkg.exe
CMake
cmake -B [build_directory] -S . -G "Visual Studio 17 2022" -A x64 -DBUILD_SHARED_LIBS=OFF -DVCPKG_TARGET_TRIPLET=x64-windows-static-md -DVCPKG_HOST_TRIPLET=x64-windows-static-md -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake cmake --build [build_directory] --config Release
Ici, on ne veut pas de librairie partagée pour le projet. Si on veut que cette contrainte s'applique également aux dépendances vcpkg
, il est nécessaire d'utiliser le triplet x64-windows-static
. Mais comme CMake
par défaut va également mettre les redistribuables de VC en statique, il faut également mettre -md
.
Si le host est compatible avec la target, il est préférable de mettre le même. Cela évitera à vcpkg
de récupérer tous les binaires pour la target mais également d'autres binaires pour que la compilation se passe bien sur le host. vcpkg creates multiple triplets for packages with no reason
Visual Studio
Préférer la méthode CMake
La présente méthode va avoir plusieurs conséquences :
- Il n'est possible d'avoir qu'un seul dépôt “intégré” (déclaré dans
C:\Users\xxx\AppData\Local\vcpkg
). - Si un projet dépend d'une librairie qui est déjà dans
vcpkg
mais avec une version différente, il va y avoir conflit et risque d'erreur de compilation.
Cette fonctionnalité permet d'avoir accès au dépôt vcpkg
en natif sans passer par CMake
.
.\vcpkg\vcpkg integrate install
Contraintes sur les paquets à installer (version / option de compilation)
Il peut être nécessaire d'installer une version précise. Ce n'est pas possible de le faire en ligne de commande. Cela se faire par l'ajout d'un fichier vcpkg.json
à la racine du projet. Pour rappel, vcpkg est cloné dans un sous dossier, à la racine du projet.
Sans vcpkg.json
, il est possible d'installer un paquet via vcpkg install paquetXXX
. Le dossier d'installation sera dans vcpkg/installed
.
Avec vcpkg.json
, il n'est plus possible d'utiliser vcpkg install paquetXXX
. Il n'est plus possible que de faire vcpkg install
et le dossier d'installation sera dans vcpkg_installed
et ne sera plus dans un sous dossier de vcpkg
.
Il est même possible de rendre optionnel certaines dépendances en fonction des WITH_*
passés à CMake.
- vcpkg.json
{ "features": { "hdf5": { "description": "Enable read / write of hdf files", "dependencies": [ { "name": "hdf5", "default-features": false, "features": [ "cpp" ] }, "boost-pfr", "magic-enum" ] }, "python": { "description": "Enable python binding", "dependencies": [ "pybind11" ] }, "tests": { "description": "Enable testing", "dependencies": [ "catch2" ] }, "matlab": { "description": "Enable matlab" } }, "overrides": [ { "name": "hdf5", "version": "1.8.23" } ], "builtin-baseline": "f31398b18d1c7cdf2360bebbe73010afdf8e6cb4" }
f31398b18d1c7cdf2360bebbe73010afdf8e6cb4
est le commit minimum du vcpkg qui permette de respecter les dépendances (généralement le commit du clone de vcpkg).
Et dans CMakeLists.txt
:
- CMakeLists.txt
cmake_minimum_required(VERSION 3.9) option(WITH_HDF5 "Build with HDF5" OFF) if(WITH_HDF5) list(APPEND VCPKG_MANIFEST_FEATURES "hdf5") endif() option(WITH_MATLAB "Build Matlab wrappers" OFF) if(WITH_MATLAB) list(APPEND VCPKG_MANIFEST_FEATURES "matlab") endif() option(WITH_PYTHON "Build Python module" OFF) if(WITH_PYTHON) list(APPEND VCPKG_MANIFEST_FEATURES "python") endif() option(BUILD_TESTING "Build the testing tree." ON) if(BUILD_TESTING) list(APPEND VCPKG_MANIFEST_FEATURES "tests") endif() project(...) include(CTest) enable_testing() ...
Les option
/ VCPKG_MANIFEST_FEATURES
doivent être définis avant project
. Par contre, il n'est pas possible de faire un include(CTest)
avant project(…)
. D'où la nécessité de définir l'option BUILD_TESTING
manuellement.
Contraintes sur les options de compilation
Pour spécifier le compilateur, il faut passer par un triplet personnalisé avec 2 fichiers :
Dans vcpkg/triplets
, créer un triplet personnalisé sur la base d'un existant et ajouter la ligne set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE ${CMAKE_CURRENT_LIST_DIR}/../scripts/toolchains/XXXXXXX.cmake)
- x64-linux-clang.cmake
include(${CMAKE_CURRENT_LIST_DIR}/x64-linux.cmake) set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE ${CMAKE_CURRENT_LIST_DIR}/../scripts/toolchains/linux-clang.cmake)
et dans vcpkg/scripts/toolchains
, ajouter les variables CMake pour définir l'utilisation de clang :
Arborescence des dossiers
Pour faciliter la recherche d'informations sur les paquets de vcpkg.
Liste des paquets avec leurs versions de publication et versions d'instructions de compilation :
vcpkg\versions
Liste des instructions pour la compilation des paquets :
vcpkg\ports
- Compilation
Dossier source :
vcpkg\buildtrees\[package]\src\[sha256]-[random_hash].clean
Dossier de compilation :
vcpkg\buildtrees\[package]\[triplet]-[dbg|rel]
Logs de compilation :
vcpkg\buildtrees\[package]\*.log
Le dossier vcpkg\buildtrees\[package]
ne contient qu'un fichier [triplet].vcpkg_abi_info.txt
avec les checksums des dépendances si la version compilée du paquet a été récupéré depuis le cache.
Binary Caching Archive du 10/01/2024 le 05/03/2024
Paquet installé :
vcpkg\packages\[package]_[triplet]
Ajout / modification d'un paquet
Voir les fichiers vcpkg.json
et portfile.cmake
dans les dossiers vcpkg/scripts/templates
et les mettre dans le dossier vcpkg/ports/[package]/
.
vcpkg.json
license
: doit correspondre à un élément de la liste https://spdx.org/licenses/. Si une autre licence, mettre null sans guillemet.
dependencies
: doit toujours avoirvcpkg-cmake
même si le paquet n'utilise pasCMake
. Ajouter égalementvcpkg-cmake-config
si le projet nécessiteCMake
pour configurer et compiler le projet.
features
:
Ici, on active une feature par défaut : hfd5
.
"default-features": [ "hdf5" ], "features": { "hdf5": { "description": "Enable read / write of hdf files", "dependencies": [ { "name": "hdf5", "features": [ "cpp" ] } ] } }
portfile.cmake
- Récupérer le code source
SHA512 se calcule depuis l'URL https://github.com/[REPO]/archive/[REF].tar.gz. Mais pour faire simple, mettre 0 (pas vide) et laisser le téléchargement échouer. vcpkg
affichera le bon SHA512
. Si la valeur change à chaque fois, il y a probablement un problème de droit. Ouvrir le fichier téléchargé dans le dossier download
avec un éditeur de texte pour vérifier le contenu (probablement une page HTML).
vcpkg_check_features
active le define WITH_HDF5
si la feature hdf5
est activée.
vcpkg_cmake_configure
. BUILD_SHARED_LIBS
est automatiquement transmis. Pour avoir la liste complète des variables automatiquement transmises, voir vcpkg\scripts\cmake\vcpkg_configure_cmake.cmake
.
vcpkg_from_github
: par défaut, c'est systématiquement REF
et son SHA512
associé qui est utilisé. Pour forcer l'utilisation de la branche HEAD_REF
, il faut ajouter set(VCPKG_USE_HEAD_VERSION ON)
avant.
vcpkg_from_github( OUT_SOURCE_PATH SOURCE_PATH REPO PLSysSec/rlbox_sandboxing_api REF 638807ad6842d82690fb2e712a32ccab4c7eec8f SHA512 d8f0788b2c46bb07041d28d9ce9426a9a3ec6df8217b81b311fc02366c49850ee138f9d3f9784cf34c778d5173779db20acc3bee436d6f1494fa8fccff5950af HEAD_REF master PATCHES catch2.patch )
- Compiler
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS FEATURES hdf5 WITH_HDF5) vcpkg_cmake_configure( SOURCE_PATH ${SOURCE_PATH} OPTIONS ${FEATURE_OPTIONS} )
- Installer
vcpkg_cmake_install()
- Patcher
Il faut ensuite tester l'installation et patcher pour rendre l'installation compatible avec vcpkg.
Pour tester :
./vcpkg.exe build [package] --triplet x64-windows
Fonctions et modifications possibles, à mettre après vcpkg_cmake_install
:
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE.txt") vcpkg_cmake_config_fixup(CONFIG_PATH "lib/cmake/package-1.2.3") file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")
- Subtilités
Sous Windows, les variables d'environnement ne sont pas passées à vcpkg et donc pas non plus à CMake.
Pour activer cette possibilité, il faut ajouter la liste des variables d'environnement dans le triplet souhaité :
set(VCPKG_ENV_PASSTHROUGH PATH) set(VCPKG_ENV_PASSTHROUGH_UNTRACKED VCPKG_TOKEN)
La modification d'une variable dans VCPKG_ENV_PASSTHROUGH
entrainera la recompilation des paquets. Contrairement à VCPKG_ENV_PASSTHROUGH_UNTRACKED
. Triplets reference
Publication des modifications
Mise à jour
Si on change de numéro de release de version du paquet, supprimer la ligne port-version
.
Si on garde le même numéro de release, il faut incrémenter (ou ajouter) la ligne port-version
(e.g. "port-version": 1
, sans guillemet autour du nombre. Un nombre à 0 équivalent à une absence de ligne).
git
Il faut commencer par faire un commit avec les modifications du dossier port/[package]
.
Lancer ensuite vcpkg.exe x-add-version package
.
Puis commiter à nouveau (en amendant) la modification des fichiers versions/baseline.json
et versions/[a-z]-/[package].json
.
git add ports/package/* git commit -m "[package] new port" vcpkg format-manifest ports/package/vcpkg.json ./vcpkg.exe x-add-version --overwrite-version package git add versions git commit -a -m "[package] new port" git push