vcpkg in MSBuild-Projekten

Integrationsmethoden

Benutzerweite Integration

Führen Sie den folgenden Befehl aus, um vcpkg in Ihren MSBuild-Projekten zu verwenden:

vcpkg integrate install

Sie müssen den befehl vcpkg integrate install nur ausführen, wenn Sie die MSBuild-Integration zum ersten Mal aktivieren möchten. Dies ermöglicht die MSBuild-Integration für alle vorhandenen und zukünftigen Projekte.

Wenn Sie über mehrere Instanzen von vcpkg verfügen, können Sie den vcpkg integrate install Befehl verwenden, um zu aktualisieren, welche vcpkg-Instanz innerhalb von MSBuild verwendet wird. Verwenden Sie vcpkg integrate remove, um die benutzerweite MSBuild-Integration zu entfernen.

Diese Integrationsmethode fügt automatisch von vcpkg installierte Pakete den folgenden Projekteigenschaften hinzu: Include Directories, Link Directories und Link Libraries. Darüber hinaus wird eine Nachbuildaktion erstellt, die sicherstellt, dass alle erforderlichen DLLs in den Buildausgabeordner kopiert werden. Dies funktioniert für alle Lösungen und Projekte mit Visual Studio 2017 oder höher.

Dies ist alles, was Sie für die überwiegende Mehrheit der Bibliotheken tun müssen. Einige Bibliotheken führen jedoch widersprüchliche Verhaltensweisen aus, z. B. das Neudefinieren main(). Da Sie pro Projekt auswählen müssen, welche dieser in Konflikt stehenden Optionen angezeigt werden sollen, müssen Sie diese Bibliotheken manuell zu Ihren Linkereingaben hinzufügen.

Hier sind einige Beispiele, in denen manuelle Verknüpfungen erforderlich sind (keine vollständige Liste):

• Gtest stellt gtest, gmock, gtest_main, und gmock_main
• SDL2 bietet SDL2main
• SFML bietet sfml-main
• Boost.Test bietet boost_test_exec_monitor

Führen Sie zum Abrufen einer vollständigen Liste für alle installierten Pakete aus vcpkg owns manual-link.

.props und .targets importieren

vcpkg kann auch in MSBuild-Projekte integriert werden, indem die Dateien scripts/buildsystems/vcpkg.props und scripts/buildsystems/vcpkg.targets explizit in jedes .vcxproj importiert werden. Durch die Verwendung relativer Pfade wird ermöglicht, dass vcpkg in einem Untermodul verwendet und automatisch bezogen wird, wenn Benutzer git clone ausführen.

Die einfachste Möglichkeit, diese zu allen Projekten in Ihrer Lösung hinzuzufügen, besteht darin, im Stammverzeichnis Ihres Repositorys die Dateien Directory.Build.props und Directory.Build.targets zu erstellen.

In den folgenden Beispielen wird davon ausgegangen, dass sich diese im Stammverzeichnis Ihres Repositorys befinden und dass das Untermodul microsoft/vcpkg unter vcpkg liegt.

Beispiel: Directory.Build.props

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

Beispiel: Directory.Build.targets

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

Siehe den Abschnitt Anpassen Ihres Builds in der offiziellen MSBuild-Dokumentation für weitere Informationen zu Directory.Build.targets und Directory.Build.props.

MSBuild-Eigenschaften an Triplets und Portfiles übergeben

Sie können den Wert von MSBuild-Eigenschaften als Umgebungsvariablen an vcpkg-Builds übergeben, indem Sie die SetEnv-Aufgabe verwenden. Sie müssen diese Umgebungsvariablen vor der VcpkgTripletSelection Aufgabe festlegen.

Das folgende Beispiel zeigt ein MSBuild-Projekt, das den Wert der MyProp Eigenschaft als Umgebungsvariable an vcpkg übergibt, damit es innerhalb von Triplets und Portdateien verwendet werden kann.

Beispiel: 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>

Beispiel: 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>

Beispiel-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)

Beispiel portfile.cmake

set(VCPKG_POLICY_EMPTY_PACKAGE enabled)

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

Verknüpftes NuGet-Paket

VS-Projekte können auch über ein NuGet-Paket integriert werden. Dadurch wird die Projektdatei geändert, daher wird dieser Ansatz für Open Source Projekte nicht empfohlen.

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"

Allgemeine Konfiguration

VcpkgEnabled (Verwenden von Vcpkg)

Dies kann auf "false" festgelegt werden, um die vcpkg-Integration für das Projekt explizit zu deaktivieren.

VcpkgConfiguration (Vcpkg-Konfiguration)

Wenn Ihre Konfigurationsnamen für eine korrekte Erkennung durch vcpkg zu komplex sind, können Sie diese Eigenschaft auf Release oder Debug setzen, um vcpkg explizit mitzuteilen, welche Bibliotheksvariante Sie nutzen möchten.

VcpkgEnableManifest (Verwenden des Vcpkg-Manifests)

Diese Eigenschaft muss auf true gesetzt werden, um aus einer lokalen vcpkg.json-Datei zu lesen. Bei Festlegung auf false, werden lokale vcpkg.json Dateien ignoriert.

Derzeit ist standardmäßig false festgelegt, künftig wird jedoch true als Standard verwendet.

VcpkgTriplet (Triplet)

Diese Eigenschaft steuert das Triplet, von dem Bibliotheken bezogen werden, z. B. x64-windows-static oder arm64-windows.

Wenn dies nicht explizit festgelegt ist, leitet vcpkg das richtige Triple basierend auf Ihren Visual Studio Einstellungen ab. vcpkg führt nur Triplets ab, die dynamische Bibliotheksverknüpfung und dynamische CRT-Verknüpfung verwenden; Wenn Sie statische Abhängigkeiten benötigen oder die statische CRT (/MT) verwenden möchten, müssen Sie das Triplet manuell festlegen.

Sie können das automatisch abgeleitete Triplet sehen, indem Sie Ihre MSBuild-Ausführlichkeit auf "Normal" oder höher festlegen:

Tastenkürzel: STRG+Q "Erstellen und ausführen"

Tools -> Optionen -> Projekte und Lösungen -> Erstellen und Ausführen -> Ausgabeausführlichkeit MSBuild-Projekt-Build

Siehe auch Dreifache

VcpkgHostTriplet (Host-Triplet)

Dies kann auf ein benutzerdefiniertes Triplet festgelegt werden, das zum Auflösen von Hostabhängigkeiten verwendet werden soll.

Wenn dies nicht gesetzt ist, wird standardmäßig das „native“-Triplet (x64-windows) verwendet.

Siehe auch Hostabhängigkeiten.

VcpkgInstalledDir (Installiertes Verzeichnis)

Diese Eigenschaft definiert den Speicherort, von dem vcpkg Bibliotheken installiert und verwendet. Verwenden Sie VcpkgManifestInstalledBaseDir in einer Lösung, die den Manifestmodus verwendet und mehrere Triplets verwendet.

Im Manifestmodus ist die Standardeinstellung $(VcpkgManifestRoot)\vcpkg_installed\$(VcpkgTriplet)\. Im klassischen Modus ist dies standardmäßig auf $(VcpkgRoot)\installed\.

VcpkgManifestInstalledBaseDir (Installiertes Basisverzeichnis)

Wenn Sie den Manifestmodus in einer Lösung verwenden, in der mehrere Triplets erstellt werden, kann die Einstellung VcpkgInstalledDir challanging sein, da sie für Projekte unterschiedlich sein muss, die unterschiedliche Triplets benötigen.

In diesem Fall kann man festlegen VcpkgManifestInstalledBaseDir , welche global festgelegt werden kann und vom Dreifachnamen angefügt wird.

VcpkgApplocalDeps (App-lokale Bereitstellung von DLLs)

Diese Eigenschaft aktiviert oder deaktiviert die Erkennung und das Kopieren abhängiger DLLs aus dem installierten vcpkg-Verzeichnisbaum in das Ausgabeverzeichnis des Projekts. Der Standardwert ist true.

VcpkgXUseBuiltInApplocalDeps (Verwenden der integrierten app-lokalen Bereitstellung)

Diese Eigenschaft steuert, welche app-lokale DLL-Bereitstellungsimplementierung vcpkg verwendet, wenn VcpkgApplocalDeps aktiviert ist. Standardmäßig wird true verwendet, das die integrierte vcpkg z-applocal-Implementierung nutzt. Legen Sie den Wert auf false fest, um die Legacy-PowerShell-Implementierung applocal.ps1 zu verwenden.

Diese Eigenschaft hat keine Auswirkung, wenn $(VcpkgApplocalDeps) "false" ist.

Konfiguration des Manifestmodus

Um Manifeste (vcpkg.json) mit MSBuild zu verwenden, müssen Sie zuerst eine der oben genannten Integrationsmethoden verwenden. Fügen Sie dann eine vcpkg.json oberhalb der Projektdatei (z. B. im Stammverzeichnis Ihres Quell-Repositorys) hinzu, und legen Sie die Eigenschaft VcpkgEnableManifest auf true. Sie können diese Eigenschaft über die IDE in Project Eigenschaften>Vcpkg>Verwenden des Vcpkg-Manifests festlegen. Möglicherweise müssen Sie die IDE neu laden, um die vcpkg-Eigenschaftenseite anzuzeigen.

vcpkg wird während des Builds Ihres Projekts ausgeführt und installiert alle aufgelisteten Abhängigkeiten nach vcpkg_installed/$(VcpkgTriplet)/ neben der vcpkg.json-Datei; diese Bibliotheken werden dann automatisch in Ihre MSBuild-Projekte eingebunden und mit ihnen verknüpft.

Bekannte Probleme

• Visual Studio 2015 erfasst Änderungen an den vcpkg.json- und vcpkg-configuration.json-Dateien nicht korrekt und reagiert nicht auf Änderungen, es sei denn, eine .cpp-Datei wird bearbeitet.

VcpkgAdditionalInstallOptions (Zusätzliche Optionen)

Bei Verwendung eines Manifests gibt diese Option zusätzliche Befehlszeilenkennzeichnungen an, die an den zugrunde liegenden vcpkg-Toolaufruf übergeben werden sollen. Dies kann verwendet werden, um auf Features zuzugreifen, die noch nicht über eine andere Option verfügbar gemacht wurden.

VcpkgManifestInstall (Vcpkg-Abhängigkeiten installieren)

Diese Eigenschaft kann auf false festgelegt werden, um die automatische Wiederherstellung von Abhängigkeiten während der Projekterstellung zu deaktivieren. Abhängigkeiten müssen über die vcpkg-Befehlszeile separat manuell wiederhergestellt werden.