vcpkg dans les projets MSBuild

Méthodes d’intégration

Intégration au niveau de l’utilisateur

Pour utiliser vcpkg dans vos projets MSBuild, exécutez la commande suivante :

vcpkg integrate install

Vous devez uniquement exécuter la commande vcpkg integrate install la première fois que vous souhaitez activer l’intégration MSBuild. Cela permet l’intégration de MSBuild pour tous vos projets existants et futurs.

Si vous avez plusieurs instances de vcpkg, vous pouvez utiliser la commande pour mettre à jour l’instance vcpkg integrate install vcpkg utilisée dans MSBuild. Utilisez vcpkg integrate remove pour supprimer l’intégration MSBuild au niveau utilisateur.

Cette méthode d’intégration ajoute automatiquement des packages installés sur vcpkg aux propriétés de projet suivantes : Inclure des répertoires, des répertoires de liens et des bibliothèques de liens. En outre, cela crée une action post-build qui garantit que toutes les DLL requises sont copiées dans le dossier de sortie de build. Cela fonctionne pour toutes les solutions et projets utilisant Visual Studio 2017 ou version ultérieure.

C’est tout ce que vous devez faire pour la grande majorité des bibliothèques. Toutefois, certaines bibliothèques adoptent des comportements contradictoires, comme redéfinir main(). Étant donné que vous devez choisir par projet parmi ces options conflictuelles souhaitées, vous devez ajouter manuellement ces bibliothèques à vos entrées de l’éditeur de liens.

Voici quelques exemples où la liaison manuelle est nécessaire (pas une liste exhaustive) :

• Gtest fournit gtest, gmock, gtest_mainet gmock_main
• SDL2 fournit SDL2main
• SFML fournit sfml-main
• Boost.Test fournit boost_test_exec_monitor

Pour obtenir une liste complète de tous vos packages installés, exécutez vcpkg owns manual-link.

Importer .props et .targets

vcpkg peut également être intégré à des projets MSBuild en important explicitement les fichiers scripts/buildsystems/vcpkg.props et scripts/buildsystems/vcpkg.targets dans chaque .vcxproj. En utilisant des chemins d’accès relatifs, vcpkg peut être utilisé par un sous-module et récupéré automatiquement par les utilisateurs lorsqu’ils exécutent git clone.

La façon la plus simple de les ajouter à chaque projet de votre solution consiste à créer des fichiers Directory.Build.props et Directory.Build.targets à la racine de votre dépôt.

Les exemples suivants supposent qu’ils se trouvent à la racine de votre dépôt, avec un sous-module microsoft/vcpkg situé à l’emplacement vcpkg.

Exemple Directory.Build.props

<Project>
 <Import Project="$(MSBuildThisFileDirectory)vcpkg\scripts\buildsystems\msbuild\vcpkg.props" />
</Project>

Exemple Directory.Build.targets

<Project>
 <Import Project="$(MSBuildThisFileDirectory)vcpkg\scripts\buildsystems\msbuild\vcpkg.targets" />
</Project>

Consultez la section Personnaliser votre build de la documentation MSBuild officielle pour plus d’informations sur Directory.Build.targets et Directory.Build.props.

Passer les propriétés MSBuild aux triplets et aux fichiers de port

Vous pouvez transmettre la valeur des propriétés MSBuild aux builds vcpkg en tant que variables d’environnement à l’aide de la SetEnv tâche. Vous devez définir ces variables d’environnement avant la VcpkgTripletSelection tâche.

L’exemple suivant montre un projet MSBuild qui transmet la valeur de la MyProp propriété à vcpkg en tant que variable d’environnement, pour le rendre utilisable à l’intérieur des triplets et des portsfiles.

Exemple Directory.Build.props

<Project>
  <PropertyGroup>
    <VcpkgRoot>C:\dev\vcpkg\</VcpkgRoot>
    <MyProp Condition="'$(Platform)' == 'x64'">X64_VALUE</MyProp>
    <MyProp Condition="'$(Platform)' == 'x86'">X86_VALUE</MyProp>
  </PropertyGroup>
 <Import Project="$(VcpkgRoot)scripts\buildsystems\msbuild\vcpkg.props" />
</Project>

Exemple Directory.Build.targets

<Project>
  <Import Project="$(VcpkgRoot)scripts\buildsystems\msbuild\vcpkg.targets" />
  <Target Name="_SetVcpkgEnvVars" BeforeTargets="VcpkgTripletSelection">
    <Message Text="Setting MY_PROP to $(MyProp)" />
    <SetEnv Name="MY_PROP" Value="$(MyProp)" Prefix="false" />
  </Target>
</Project>

Exemple de triplet x64-windows-custom.cmake

set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic)

# Pass the environment variable to port builds
set(VCPKG_ENV_PASSTHROUGH_UNTRACKED MY_PROP)

Exemple de portfile.cmake

set(VCPKG_POLICY_EMPTY_PACKAGE enabled)

MESSAGE(STATUS "MY_PROP is $ENV{MY_PROP}")

Package NuGet associé

Les projets VS peuvent également être intégrés via un package NuGet. Cela modifie le fichier projet. Nous vous déconseillons donc cette approche pour les projets open source.

PS D:\src\vcpkg> .\vcpkg integrate project
Created nupkg: D:\src\vcpkg\scripts\buildsystems\vcpkg.D.src.vcpkg.1.0.0.nupkg

With a project open, go to Tools->NuGet Package Manager->Package Manager Console and paste:
    Install-Package vcpkg.D.src.vcpkg -Source "D:/src/vcpkg/scripts/buildsystems"

Configuration courante

VcpkgEnabled (Utiliser Vcpkg)

Cela peut être défini sur « false » pour désactiver explicitement l’intégration de vcpkg pour le projet

VcpkgConfiguration (Configuration de Vcpkg)

Si vos noms de configuration sont trop complexes pour que vcpkg suppose correctement, vous pouvez affecter cette propriété à Release ou Debug indiquer explicitement à vcpkg quelle variante de bibliothèques vous souhaitez consommer.

VcpkgEnableManifest (Utiliser le manifeste Vcpkg)

Cette propriété doit être définie true pour pouvoir consommer à partir d’un fichier local vcpkg.json . Si la valeur est définie false, tous les fichiers locaux vcpkg.json sont ignorés.

Cela correspond actuellement par défaut à false, mais correspondra par défaut à true à l’avenir.

VcpkgTriplet (Triplet)

Cette propriété contrôle le triplet à utiliser pour consommer les bibliothèques, tel que x64-windows-static ou arm64-windows.

S’il n’est pas défini explicitement, vcpkg déduira le triplet correct en fonction de vos paramètres de Visual Studio. vcpkg déduira uniquement les triplets qui utilisent la liaison de bibliothèque dynamique et la liaison CRT dynamique ; si vous souhaitez des dépendances statiques ou utiliser le CRT statique (/MT), vous devez définir le triplet manuellement.

Vous pouvez voir le triplet déduit automatiquement en définissant le niveau de verbosité de MSBuild sur Normal ou plus :

Raccourci : Ctrl+Q « générer et exécuter »

Outils -> Options -> Projets et solutions -> Générer et exécuter -> Niveau de détail de la sortie de génération du projet MSBuild

Voir aussi Triplets

VcpkgHostTriplet (Triplet hôte)

Cette valeur peut être définie sur un triplet personnalisé afin de résoudre les dépendances de l’hôte.

Si ce paramètre n’est pas défini, il s’agit par défaut du triplet « natif » (x64-windows).

Consultez également les dépendances de l’hôte.

VcpkgInstalledDir (Répertoire installé)

Cette propriété définit l’emplacement à partir duquel vcpkg installe et consomme des bibliothèques. Utiliser VcpkgManifestInstalledBaseDir dans une solution qui utilise le mode manifeste et utilise plusieurs triplets.

En mode manifeste, cette valeur par défaut est $(VcpkgManifestRoot)\vcpkg_installed\$(VcpkgTriplet)\. En mode classique, cette valeur par défaut est $(VcpkgRoot)\installed\.

VcpkgManifestInstalledBaseDir (Répertoire de base installé)

Lorsque vous utilisez le mode manifeste dans la solution qui génère plusieurs triplets, le paramètre VcpkgInstalledDir peut être challanging, car il doit être différent pour les projets qui ont besoin de triplets différents.

Dans ce cas, vous pouvez définir qui peut être défini VcpkgManifestInstalledBaseDir globalement et est ajouté par le nom triplet.

VcpkgApplocalDeps (Déployer des DLL localement pour l’application)

Cette propriété active ou désactive la détection et la copie de DLL dépendantes de l’arborescence installée vcpkg vers le répertoire de sortie du projet. Sa valeur par défaut est true.

VcpkgXUseBuiltInApplocalDeps (Utiliser un déploiement local intégré d’application)

Cette propriété contrôle la méthode de déploiement local à l’application des DLL que vcpkg utilise lorsque VcpkgApplocalDeps est activé. Par défaut true, il utilise l’implémentation intégrée vcpkg z-applocal . Définissez-le sur false pour utiliser l’ancienne implémentation PowerShell applocal.ps1.

Cette propriété n’a aucun effet lorsqu’elle $(VcpkgApplocalDeps) a la valeur false.

Configuration du mode manifeste

Pour utiliser des manifestes (vcpkg.json) avec MSBuild, vous devez d’abord utiliser l’une des méthodes d’intégration ci-dessus. Ensuite, ajoutez un fichier vcpkg.json au-dessus de votre fichier de projet (par exemple, à la racine de votre dépôt de code source) et définissez la propriété VcpkgEnableManifest sur true. Vous pouvez définir cette propriété via l’IDE dans Project Propriétés>Vcpkg>Utiliser le manifeste Vcpkg. Vous devrez peut-être recharger l’IDE pour afficher la page de propriétés vcpkg.

vcpkg s’exécute pendant la génération de votre projet et installe toutes les dépendances répertoriées à vcpkg_installed/$(VcpkgTriplet)/ côté du vcpkg.json fichier . Ces bibliothèques seront ensuite automatiquement incluses et liées à vos projets MSBuild.

Problèmes connus

• Visual Studio 2015 ne détecte pas correctement les modifications apportées aux fichiers vcpkg.json et vcpkg-configuration.json, et ne réagit pas à ces modifications à moins qu’un fichier .cpp ne soit modifié.

VcpkgAdditionalInstallOptions (Options supplémentaires)

Lorsque vous utilisez un manifeste, cette option spécifie des indicateurs de ligne de commande supplémentaires à passer à l’appel de l’outil vcpkg sous-jacent. Cela peut être utilisé pour accéder aux fonctionnalités qui n’ont pas encore été exposées via une autre option.

VcpkgManifestInstall (Installer les dépendances Vcpkg)

Cette propriété peut être définie sur false pour désactiver la restauration automatique des dépendances pendant la génération du projet. Les dépendances doivent être restaurées manuellement, séparément, à l’aide de la ligne de commande vcpkg.