vcpkg w projektach MSBuild

Metody integracji

Integracja na poziomie użytkownika

Aby użyć narzędzia vcpkg w projektach MSBuild, uruchom następujące polecenie:

vcpkg integrate install

Wystarczy uruchomić polecenie vcpkg integrate install po raz pierwszy, aby włączyć integrację programu MSBuild. Umożliwia to integrację programu MSBuild ze wszystkimi istniejącymi i przyszłymi projektami.

Jeśli masz wiele wystąpień programu vcpkg, możesz użyć vcpkg integrate install polecenia , aby zaktualizować, które wystąpienie programu vcpkg jest używane w programie MSBuild. Użyj vcpkg integrate remove , aby usunąć integrację użytkownika z MSBuild.

Ta metoda integracji automatycznie dodaje zainstalowane pakiety vcpkg do następujących właściwości projektu: Dołączanie katalogów, Katalogi łączy i Biblioteki łączy. Ponadto spowoduje to utworzenie akcji po kompilacji, która gwarantuje, że wszystkie wymagane biblioteki DLL zostaną skopiowane do folderu wyjściowego kompilacji. Działa to w przypadku wszystkich rozwiązań i projektów korzystających z Visual Studio 2017 lub nowszych.

To wszystko, co musisz zrobić dla zdecydowanej większości bibliotek. Jednak niektóre biblioteki wykonują sprzeczne zachowania, takie jak ponowne zdefiniowanie elementu main(). Ponieważ dla każdego projektu musisz wybrać, które z tych opcji prowadzących do konfliktu chcesz zastosować, musisz ręcznie dodać te biblioteki do wejść linkera.

Poniżej przedstawiono kilka przykładów, w których konieczne jest ręczne łączenie (nie jest to wyczerpująca lista):

• Gtest udostępnia gtest, gmock, gtest_main i gmock_main
• SDL2 zapewnia SDL2main
• SFML dostarcza sfml-main
• Boost.Test zapewnia boost_test_exec_monitor

Aby uzyskać pełną listę wszystkich zainstalowanych pakietów, uruchom polecenie vcpkg owns manual-link.

Importowanie .props i .targets

Narzędzie vcpkg można również zintegrować z projektami MSBuild przez jawne zaimportowanie plików scripts/buildsystems/vcpkg.props i scripts/buildsystems/vcpkg.targets do każdego elementu .vcxproj. Korzystanie ze ścieżek względnych umożliwia użycie narzędzia vcpkg przez moduł podrzędny i jego automatyczne pobieranie przez użytkowników po uruchomieniu polecenia git clone.

Najprostszym sposobem dodania ich do każdego projektu w rozwiązaniu jest utworzenie plików Directory.Build.props i Directory.Build.targets w głównym katalogu repozytorium.

W poniższych przykładach założono, że znajdują się one w katalogu głównym repozytorium z modułem podrzędnym microsoft/vcpkg w vcpkg.

Przykład: Directory.Build.props

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

Przykład: Directory.Build.targets

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

Aby uzyskać więcej informacji na temat i Directory.Build.targets, zobacz sekcję Directory.Build.props oficjalnej dokumentacji programu MSBuild.

Przekazywanie właściwości programu MSBuild do trypletów i plików portów

Wartość właściwości MSBuild można przekazać do kompilacji za pomocą vcpkg jako zmienną środowiskową za pomocą zadania SetEnv. Przed zadaniem należy ustawić te zmienne VcpkgTripletSelection środowiskowe.

W poniższym przykładzie pokazano projekt MSBuild przekazujący wartość właściwości MyProp do vcpkg jako zmienną środowiskową, aby można było ją używać wewnątrz triplets i portfiles.

Przykład: 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>

Przykład: 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>

Przykładowa trójka 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)

Przykład pliku portfile.cmake

set(VCPKG_POLICY_EMPTY_PACKAGE enabled)

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

Połączony pakiet NuGet

Projekty vs można również zintegrować za pomocą pakietu NuGet. Spowoduje to zmodyfikowanie pliku projektu, dlatego nie zalecamy tego podejścia w przypadku projektów 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"

Wspólna konfiguracja

VcpkgEnabled (Użyj narzędzia Vcpkg)

Można to ustawić na wartość "false", aby jawnie wyłączyć integrację programu vcpkg dla projektu

VcpkgConfiguration (Konfiguracja programu Vcpkg)

Jeśli nazwy konfiguracji są zbyt złożone, aby vcpkg mógł je poprawnie rozpoznać, możesz przypisać tę właściwość do Release lub Debug, aby wyraźnie określić, jaki wariant bibliotek chcesz używać.

VcpkgEnableManifest (Użyj manifestu Vcpkg)

Ta właściwość musi być ustawiona na true , aby korzystać z pliku lokalnego vcpkg.json . Jeśli ustawiono wartość false, wszystkie pliki lokalne vcpkg.json zostaną zignorowane.

Obecnie jest to domyślnie ustawione na false, ale w przyszłości będzie domyślnie ustawione na true.

VcpkgTriplet (Trójka)

Ta właściwość kontroluje tryplet, z którego korzystają biblioteki, takie jak x64-windows-static lub arm64-windows.

Jeśli nie zostanie to jawnie ustawione, narzędzie vcpkg ustali poprawny triplet na podstawie ustawień programu Visual Studio. vcpkg będzie wywnioskowywać tylko trójki, które korzystają z dynamicznej biblioteki linkowania i dynamicznego CRT; jeśli potrzebujesz zależności statycznych lub chcesz użyć statycznego CRT (/MT), musisz ręcznie ustawić trójkę.

Możesz zobaczyć automatycznie dedukowany triplet, ustawiając poziom szczegółowości MSBuild na normalny lub wyższy.

Skrót: Ctrl+Q "buduj i uruchom"

Narzędzia -> Opcje -> Projekty i rozwiązania -> Kompilowanie i uruchamianie -> Szczegółowość kompilacji projektu MSBuild

Zobacz też Trójkropki

VcpkgHostTriplet (Trójka hostów)

Można to ustawić na niestandardową trójkę do użycia na potrzeby rozpoznawania zależności hosta.

Jeśli opcja nie zostanie ustawiona, wartość domyślna to "native" triplet (x64-windows).

Zobacz również Zależności hosta.

VcpkgInstalledDir (Zainstalowany katalog)

Ta właściwość definiuje lokalizację, skąd vcpkg zainstaluje i wykorzysta biblioteki. Użyj VcpkgManifestInstalledBaseDir w rozwiązaniu, które używa trybu manifestu i używa wielu trójkropków.

W trybie manifestu ta wartość domyślna to $(VcpkgManifestRoot)\vcpkg_installed\$(VcpkgTriplet)\. W trybie klasycznym ta wartość domyślna to $(VcpkgRoot)\installed\.

VcpkgManifestInstalledBaseDir (Zainstalowany katalog podstawowy)

W przypadku korzystania z trybu manifestu w rozwiązaniu, który tworzy wiele trojaków, ustawienie VcpkgInstalledDir może być challanging, ponieważ musi być inne w przypadku projektów, które wymagają różnych trypletów.

W tym przypadku można ustawić, które można ustawić VcpkgManifestInstalledBaseDir globalnie i jest dołączane przez potrójną nazwę.

VcpkgApplocalDeps (Lokale wdrażanie bibliotek DLL aplikacji)

Ta właściwość włącza lub wyłącza wykrywanie i kopiowanie zależnych bibliotek DLL z zainstalowanego drzewa vcpkg do katalogu wyjściowego projektu. Wartość domyślna to true.

VcpkgXUseBuiltInApplocalDeps (Użyj wbudowanego wdrożenia lokalnego aplikacji)

Ta właściwość kontroluje, która implementacja wdrożenia biblioteki DLL w środowisku app-local używa narzędzia vcpkg, gdy VcpkgApplocalDeps jest włączona. Domyślnie jest ustawione na true, które korzysta z wbudowanej implementacji vcpkg z-applocal. Ustaw wartość false, aby użyć starszej implementacji programu PowerShell applocal.ps1.

Ta właściwość nie ma wpływu, gdy wartość $(VcpkgApplocalDeps) jest false.

Konfiguracja trybu manifestu

Aby używać manifestów (vcpkg.json) w programie MSBuild, najpierw należy użyć jednej z powyższych metod integracji. Następnie dodaj vcpkg.json powyżej pliku projektu (na przykład w katalogu głównym repozytorium źródłowego) i ustaw właściwość VcpkgEnableManifest na true. Tę właściwość można ustawić za pomocą środowiska IDE we właściwościach> projektuVcpkg>Użyj manifestu Vcpkg. Może być konieczne ponowne załadowanie środowiska IDE, aby wyświetlić stronę właściwości narzędzia vcpkg.

Narzędzie vcpkg zostanie uruchomione podczas kompilacji projektu i zainstaluje wszystkie wymienione zależności do lokalizacji sąsiadującej z plikiem vcpkg_installed/$(VcpkgTriplet)/ . Te biblioteki zostaną następnie automatycznie dołączone do projektów MSBuild i połączone z nimi.

Znane problemy

• Program Visual Studio 2015 nie śledzi poprawnie edycji plików vcpkg.json i vcpkg-configuration.json i nie odpowie na zmiany, chyba że .cpp zostanie edytowany.

VcpkgAdditionalInstallOptions (Dodatkowe opcje)

W przypadku korzystania z manifestu ta opcja określa dodatkowe flagi wiersza polecenia, które mają być przekazywane do wywołania podstawowego narzędzia vcpkg. Może to służyć do uzyskiwania dostępu do funkcji, które nie zostały jeszcze ujawnione za pośrednictwem innej opcji.

VcpkgManifestInstall (Zainstaluj zależności programu Vcpkg)

Tę właściwość można ustawić tak false , aby wyłączyć automatyczne przywracanie zależności podczas kompilacji projektu. Zależności muszą zostać ręcznie przywrócone za pośrednictwem wiersza polecenia vcpkg oddzielnie.